CLI

The engram CLI

One command installs everything: a client for document bases, documents and keys, the fastest way to load a large folder, and the config block your assistant needs. It scripts cleanly, and it never invents a reason for a failure.

What it does

The CLI is the terminal half of the product. Five things it is the best tool for:

Loading a folder. engram push hashes locally, asks the server what it is missing, and sends only that. A folder of 50,000 documents where three changed is one small request and three uploads.
Connecting an assistant. engram mcp prints the config block for the hosted MCP server, filled in for the profile you are logged in on, in whichever client's shape you name with --client.
Keys. Create, list and revoke workspace API keys without leaving the terminal.
Checking. engram status is a real gate: it exits non-zero when the API is down or the credential is refused, so engram status && deploy means something. It also prints the region the platform runs in and what that means for your egress bill.
Scripting. --json puts a JSON document on stdout and nothing else, with every human aside on stderr.

Install

The package is engram-dynamics and the command it installs is engram. Use whichever tool you already have:

pipx install engram-dynamics

uv tool install engram-dynamics

Both give you an isolated install on your PATH, which is what you want for a tool rather than a library. Confirm it:

engram --version

Pushing from an s3:// URL needs boto3, which is an optional extra so that nobody pushing a local folder has to carry it:

pipx install "engram-dynamics[s3]"

Upgrading is the same command with -U for pipx, or uv tool upgrade engram-dynamics. Nothing is needed for MCP: that server is hosted, so there is no second thing to keep current.

First run

Create a key on the API keys page in the app, or ask a workspace admin for one, and log in. Scope it to what it will do: query to ask questions, ingest to load documents, admin to manage the workspace.

engram login --api-key <your key> --api-url https://api.engramdynamics.org
engram status
engram corpora list

Login makes a real authenticated call before saving anything, so a typo, a revoked key or a wrong URL fails immediately rather than on your next command. It reports how many document bases the key can see, which is the fastest confirmation you hit the right workspace.

--api-url can be left off: it defaults to https://api.engramdynamics.org. Pass it when you are pointing a profile at another environment.

A first load, end to end

engram corpora create --name "Support KB"
engram push ./docs --corpus "Support KB" --dry-run   # see what would go
engram push ./docs --corpus "Support KB"             # send it and wait
engram status "Support KB"

Everywhere a document base is named, its name or its id both work. Names are matched exactly first, then case-insensitively, so --corpus sales finds "Sales". Two bases with the same name is the one case that needs an id, and the error lists the candidates.

Push is safe to interrupt: nothing is registered until every byte has landed, so a killed run leaves the base exactly as it was and re-running picks up what is outstanding. There is no local state to clean up. Full detail on Push a folder.

The commands

Command	What it covers
`engram login`	Store a key in a profile, after checking it works.
`engram status`	Platform health and the profile in use, or one document base's progress.
`engram profiles`	The configured profiles and where the config file lives.
`engram corpora`	Document bases: list, create, show.
`engram docs`	Documents inside a base: list, and upsert one by path.
`engram push`	Upload a folder, a file, or an `s3://` prefix, sending only what changed.
`engram keys`	Workspace API keys: list, create, revoke.
`engram mcp`	Print the config block for the hosted MCP server, in your client's own shape.
`engram sources`	Buckets and connected folders a base pulls from. S3 buckets are set up here, IAM template included.
`engram sync`	Pull from a registered source now, and read the run history.

Every option and subcommand is on the command reference. --help works at every level, including engram sources add s3 --help.

Conventions worth knowing up front

--profile and --json work before or after the subcommand. engram --json status and engram status --json are the same.
Failures exit non-zero with the server's own message on stderr. The CLI does not reword it or guess at the reason.
Output drops colour and box drawing when stdout is not a terminal, so piped output stays diffable.
Progress bars are drawn on stderr, never stdout, so engram push --json | jq works while a human watches the bar.
Secrets are never printed twice. A created key's secret is shown once, and a stored profile's key is only ever shown as a prefix.

Login, profiles and environmentWhere credentials live, how to run several environments, and the https rule. Push a folderWhat gets picked up, dry runs, mirror mode and large loads. Command referenceEvery command, option and example. Scripting and CIExit codes, JSON output, and credentials in a pipeline.