Commands
The canonical detail for any command is im-cli <command> --help. This page is
the at-a-glance map.
Global flags
Available on every command:
| Flag | What it does |
|---|---|
--api-url <url> (env IM_CLI_API_URL) | One-shot override of the active login's server for a single command. |
--output / -o <fmt> | table | json | yaml (table on a TTY, json when piped). |
--config <path> | Path to the user config file (default $XDG_CONFIG_HOME/im-cli/config.json). |
--verbose / -v | Verbose diagnostics. |
--no-color | Disable coloured output. |
Authentication
The CLI keeps a single active login — one server at a time.
| Command | What it does |
|---|---|
im-cli login | Browser device-flow sign-in (defaults to --api-url http://localhost/api); stores the active login + PAT. --with-token - reads a PAT from stdin (CI). |
im-cli logout | Clear the active login and its stored token. |
im-cli whoami | Show the active server, the authenticated user, and (inside a project) the linked agent. |
Switching servers
There are no named contexts — to use another server (staging / prod / another org's Portal), just log in again; the new login replaces the active one.
| Command | What it does |
|---|---|
im-cli login --api-url <url> | Sign in to another server (replaces the active login). |
--api-url <url> / IM_CLI_API_URL (global) | One-shot override for a single command (pair with IM_CLI_TOKEN in CI). |
Scaffold + lifecycle
| Command | What it does |
|---|---|
im-cli new [<slug> [<dir>]] | List the template catalog (--list, filter with --language/--search), or scaffold a starter (--var key=value, --force). |
im-cli link [<uuid>] [--agent <uuid>] | Bind the project to a Portal agent; creates .im/, derives the org (--org to disambiguate). |
im-cli unlink | Remove the active server's agent binding from .im/config.json (other servers untouched). |
im-cli push [--submit] [--new-version] [--force] | Zip + upload: updates the agent's open draft in place, or creates a new draft when there is none (see below); --new-version always creates one; --submit → pending_review. Also --dry-run (validate + zip, no upload), --zip <file>, --replaces-version <label>, --timeout. |
im-cli pull [--version vN] [--into <dir>] [--force] | Download a version's source and extract it (default: the latest published version of the linked agent). --agent <uuid> pulls an agent this directory isn't linked to; --org <uuid> names the organization when it can't be resolved from the agent. |
When push creates a version
A push updates the agent's open draft instead of creating a new version every time, so iterating on an agent stays on one draft rather than producing v1…v47. What happens depends on the agent's latest open version:
| Latest version | push | push --new-version | push --force |
|---|---|---|---|
| draft | updates it in place | new draft; the old one is marked replaced | updates it in place |
| pending_review | refused (409) | refused (409) | new draft; the one under review is marked replaced |
| published, rejected, archived, or none | new draft | new draft | new draft |
An update keeps the draft's id, number and label and replaces its code, its
.im/io.json contract and its pinned SDK. im-cli push always says which case it
was:
Updated draft v5 (0193f6cf-…).
Pushed new version v6 (0193f6d0-…), draft. v5 marked replaced.
Pushed new version v8 (0193f6d2-…), draft. v7 (under review) marked replaced.
Two consequences of updating in place:
- A run paused for input on that draft can't be continued. Its next step would
run the new code against what the old code left behind. The push cancels such
runs and lists them (
Cancelled 1 paused run (waiting for input): its code changed.); any it leaves (a read-only token, or more paused runs than it cancels at once) are cancelled when someone answers them, with a 409. Either way the run shows that reason in the Portal. Pass--new-versionto keep it answerable. - Earlier runs of the draft point at the updated code. Retrying or running one again runs the latest push. Versions under review and published versions never change.
What push requires in the bundle
The runner installs your code with uv sync --locked, so the zip must carry
both a pyproject.toml and a uv.lock at its root, plus the
.im/io.json contract. im-cli push checks the first two locally and refuses
before uploading (exit 5):
im-cli: nothing to install: the bundle has no uv.lock. The runner installs with
`uv sync --locked`, which needs a committed lockfile — run `uv lock` and push again
Two things this catches that are easy to misread as a server problem:
- No
uv.lock.--lockednever creates one — the install just fails.uv lockwrites it; commit it. - A project one directory down. Push from the project root. uv is pointed at
the bundle root, so a
pyproject.tomlinside a wrapper folder is not a project it will find, even though everything works locally.
If the install fails on the server anyway — a lockfile that no longer matches
pyproject.toml, a dependency that will not resolve, a full runner container, an
install that ran past the runner's time limit —
the Portal answers with the reason and im-cli prints it verbatim. No version is
created by a failed push: it consumes no version number and leaves your
previous draft alone, so fixing the cause and pushing again picks up exactly
where you were.
Pulling source back
im-cli pull is the read counterpart of push: it fetches the exact zip a version
was pushed with and unpacks it. Three things it is good for — populating a fresh
directory from a live agent, checking what a portal is actually running against
what is in git, and recovering the source of an older version.
im-cli pull # latest published version, into the current directory
im-cli pull --version v3 # a specific version, published or not
im-cli pull --into ./live # somewhere else, so you can diff it
im-cli pull --agent <uuid> # an agent this directory isn't linked to
im-cli pull --org <uuid> # name the org explicitly, when --agent can't resolve itNaming a version with --version pulls it whatever its status — a draft or a
pending-review version is pullable, not only a published one. That is deliberate:
recovering the source you just pushed is the common case, and the endpoint is
gated on the same permission as the push that created it (agents.versions.develop),
so being able to pull a draft implies nothing more than being able to have made
one. Only the default — no --version — is restricted to the latest published
version.
It is a snapshot extract, not a merge. Files with the same path are overwritten; files the archive doesn't contain are left alone; there is no history, no three-way merge and no VCS semantics — git owns all of that.
Because of that, pull refuses to run in a directory that already has files in
it. .git/, .im/ and .DS_Store don't count, so the clone-then-pull flow
works as-is:
git clone git@example.com:team/billing-agent.git && cd billing-agent
im-cli pull # fills the clone with the live codeAnywhere else you get a refusal naming what is in the way, and two ways out:
--into <dir> to extract somewhere fresh (the usual choice for a drift diff), or
--force to overwrite in place.
Extraction validates before it commits. Entry names that would escape the target
are refused, symlinks in the archive are skipped, and — importantly with
--force — the whole archive is unpacked to a staging directory and checked
first, on both sides: the archive itself (names, size caps, readability) and the
destination (a symlink in the path, a file where a directory has to go). Only
then is anything moved into place, so nothing about the archive you pulled, or
about what was already sitting in the target, can leave you with a directory that
is half your work and half the artifact.
The commit that follows is ordinary file moves, not a database transaction — an exhausted disk part-way through still has no rollback.
If a version says it has a retained source and the download still fails, that is
not an old push: the stored copy is gone, which normally means the Portal's
AGENTS_ARTIFACT_ARCHIVE_DISK points at storage that didn't survive a redeploy.
pull says so rather than telling you to push again. It deliberately does not
suggest other versions there — they are stamped exactly like the one that just
failed, so after a wiped disk they would all be equally unpullable.
pull never restores .im/config.json. That file is your local, gitignored
link, and an archive can carry whoever pushed it — writing theirs over yours
would silently retarget your next im-cli push. The rest of .im/ is extracted
normally.
Pulling source needs the same permission as pushing it (agents.versions.develop
— org admin/owner, or a developer participant on the agent). Being able to list
versions is not enough.
Run + inspect
| Command | What it does |
|---|---|
im-cli run [<version>] | Run a version of the linked agent (default: latest runnable), streaming console output. Inputs via repeatable --input key=value or --input-file <json>; --detach returns the execution UUID immediately; --no-prompt never asks when the run pauses for input; also --timeout. The run is queued at the agent's priority, which an admin sets on the agent's Manifest tab in the Portal. |
im-cli logs <execution> [--follow] | Replay or stream an execution's events (--since, --tail). |
im-cli execution list / get <uuid> / cancel <uuid> | Inspect and cancel executions (exec alias; list takes --status/--agent/--limit). get returns the run's full input and output — but see payload retention for runs older than four weeks. |
im-cli execution resume <uuid> | Answer the question a paused agent asked and continue the same run. Prompts on a terminal; otherwise --answer <str>, --answer-file <path>, or repeatable --field name=value. --no-stream returns immediately. |
im-cli agent versions | List the agent's versions + which you can run + each version's inputs/output. |
im-cli agent models / im-cli agent services | The model aliases / connected services the agent may use. |
im-cli agent variables | The organization variables and secrets the agent is granted, with the line to use each: core.vars["KEY"] for a variable (its value is shown), core.secret("KEY") for a secret (its value never is — only set / not set and, under USABLE WITH, the services it may be sent to that the agent is also granted; -o json keeps the secret's full allowed_services beside usable_services, which is on secret rows only — absent when no agent is linked, [] when the agent holds none of the allowed services). A grant the agent's workspace does not reach is marked. See Variables & secrets. |
im-cli agent list | Agents in the active organization (agents/ls aliases; --status/--workspace/--limit). |
When a run pauses for input
An agent can pause and ask a human a question (human-in-the-loop). The run stops at awaiting_input, and the question is stored server-side — so you never have to keep a terminal open.
On a terminal, im-cli run shows the question and prompts you for it, then keeps streaming. Answer as many pauses as the agent makes; it all stays one run.
Piped, or with --no-prompt, it prints the question and the command to answer it, then exits 9 — a code of its own, because a parked run has not failed:
im-cli run > run.log
# Execution 8f3c… is waiting for input.
# Approve the transfer
# Fields: approved, reason
#
# Answer it with:
# im-cli execution resume 8f3c…Come back whenever and finish it:
im-cli execution resume 8f3c… # prompts for each field
im-cli execution resume 8f3c… --field approved=true --field reason='looks fine'
im-cli execution resume 8f3c… --answer 'yes, go ahead' # free-text question
im-cli execution resume 8f3c… --answer-file ./reply.json # long or structured answerim-cli execution list --status awaiting_input finds every run that is waiting, and im-cli execution get <uuid> shows a question without answering it.
--field values are typed: true/false become booleans and plain digits become numbers, so a field the agent declared boolean gets a boolean. Values with a leading zero (007) stay strings, since those are identifiers rather than quantities.
If nobody is going to answer, cancel it: a paused run has no other terminal state — no timeout moves it — and cancelling closes the open question with it, so no surface keeps offering a form for a dead run.
im-cli execution cancel 8f3c…Payload retention
A run's input and output are kept in full for four weeks. Inside that
window im-cli execution get returns them exactly as it always has, so
im-cli execution get <uuid> -o json | jq and anything built on it keep working
unchanged.
Afterwards the Portal keeps a preview — the same document with the long text
inside it shortened, marked (truncated..). The shape is
preserved, so a script that reads output.stderr or output.output still finds
its field; it just sees the first few kilobytes of it. The response also carries
output_truncated, output_bytes and payloads_expire_at, though a CLI built
before this change silently drops fields it does not know and will not show them.
If you need a run's payload for longer than four weeks, capture it when the run finishes rather than expecting to fetch it later.
Files
Documents an agent reads by id. Files belong to a workspace, not to an agent — the workspace comes from the linked agent, so run these from your project folder. Any agent in that workspace can read an uploaded file, and uploads expire after the platform's retention window (3 days by default).
| Command | What it does |
|---|---|
im-cli files upload <path> | Upload a document; prints the file id on stdout (pipe-friendly). Also --timeout. |
im-cli files list | The workspace's live files — id, filename, size, expiry. Paged (50 per page, 100 max): --page / --per-page select the page, and when there is more than one page a note on stderr says so — the rows are never silently incomplete. Honours -o: with json / yaml (the default when piped) the rows come back under files and the paginator under page, so a script can see it is holding one page of many. A --page / --per-page outside the server's range is refused locally with exit 5. |
im-cli files delete <file-id> | Remove the object + row. Workspace-wide, not per-run. |
All three take --workspace / --agent / --org to target something other than the linked
agent's workspace. The id is what the agent receives:
im-cli files upload report.pdf # → 2247c37d-…
im-cli run --input 'files=["2247c37d-…"]'The agent reads it with document_parse(service, file_ref=…) — the bytes never enter the agent
process — or file_store.get(file_ref) for the raw bytes as Base64 (no service, no grant: the
buffer is the platform's). The server enforces a size cap plus two independent allow-lists (the
filename's extension and the sniffed content type), so renaming a binary does not get it in.
An upload is gone after 3 days. To keep one, the agent writes it into a connected data bucket
with object_store.put_from_upload(...) — see Files & storage, which
also covers declaring the input as "type": "file" so the playground shows an uploader.
Diagnostics
| Command | What it does |
|---|---|
im-cli doctor | Validate local config, check API reachability, and confirm the stored token still authenticates (reports the signed-in user and organization). Also checks the toolchain an agent project needs: python3 3.11 or newer, and uv. For each one missing or too old it names the command that fixes it, and it reports these even when you are not logged in. -o json carries them as python and uv, each with found, path, version and ok. Inside an agent project it also notes code that reads a legacy CIU_ agent name (CIU_CHECKER_URL, CIU_RESUME_FILE, CIU_EMIT_PORTAL_EVENTS, CIU_LOG_LEVEL, or a CIU_ tracing constant) and names its IM_ replacement; the old names keep working. |
im-cli version | Print version, commit, and build date. --trust-anchor prints the release signing keys this binary verifies upgrades against instead. |
Staying current
| Command | What it does |
|---|---|
im-cli upgrade | Install the newest published release over this binary. |
im-cli upgrade --version 1.2.3 | Install a named release, including a pre-release or an earlier one. |
im-cli upgrade --check | Resolve and verify the newest release, then stop without changing anything. |
upgrade verifies the release's signed checksums.txt against the signing key
compiled into the binary you are running — not against a key fetched from the
downloads host, which would be asking the thing being verified to supply the
standard. It then takes the archive's digest from that verified manifest rather
than from the unsigned release index, checks the downloaded bytes against it, and
runs the new binary once before putting it in place. Nothing on disk changes
until all of that has passed, so a failed upgrade leaves a working CLI.
It refuses rather than half-succeeding on Windows (an open executable cannot be replaced in place) and on Homebrew or Scoop installs, naming that channel's own upgrade command. Compare the pinned key with the fingerprint published outside the downloads host — see Getting started.
Exit codes
| Code | Meaning |
|---|---|
0 | Success |
1 | Generic failure (also HTTP 409 on push while a version is under review, without --force) |
2 | push ok but --submit failed |
3 | Forbidden (403) |
4 | Unauthenticated (401) |
5 | Validation error (422) |
6 | Rate limited (429) |
7 | Server error (5xx) |
8 | Network error |
9 | Awaiting input — the run paused for a human and was not answered here. Not a failure: the run is parked and still resumable with im-cli execution resume. |
130 | SIGINT (Ctrl-C) |