Version lifecycle & roles

An im-cli push lands in the agent's draft version: it updates the open draft when there is one, and creates a new version when there is not. A version moves through a fixed set of states, and which ones you can run depends on your role.

States

StateHow it's reached
draftThe default landing state of im-cli push. Iterate on it freely: each push updates it in place.
pending_reviewA draft submitted for review — via im-cli push --submit or a later submit.
publishedA pending-review version approved by a reviewer, or promoted by an admin. Publishing auto-archives the previously published version.
archivedA previously published version, superseded by a newer publish.
rejectedA pending-review version a reviewer declined.
replacedA draft superseded by im-cli push --new-version, or a pending-review version superseded by im-cli push --force (see below).
push ──▶ draft ──submit──▶ pending_review ──approve/publish──▶ published
                                  │                                 │
                                  └── reject ──▶ rejected      supersede ──▶ archived

Who can run what

im-cli run and the Portal playground apply the same rule, so you can test a version before it's public:

RoleCan run
Developer (agent participant)Their draft versions
Reviewer (agent participant)pending_review versions
Anyone with accesspublished versions
Org admin / owner (and superadmin)Any state

im-cli agent versions shows every version, its status, and a RUNNABLE column telling you which ones you may run. With no version argument, im-cli run picks the latest runnable version — so right after im-cli push you can im-cli run your fresh draft immediately.

Runs started from the CLI are stamped with the cli trigger source (the Portal playground uses playground; external PAT calls use external), which is visible in the execution history.

Review

A pending_review version is approved or rejected by a reviewer. Approval publishes it (and archives the old published version atomically); rejection records a reason. A reviewer cannot approve their own submission — the Portal blocks self-approval. An org admin can also publish a pending-review version directly, without a separate reviewer.

Updating a draft, replacement & --force

  • Pushing while the agent has an open draft updates that draft in place: same id, number and label, new code, new .im/io.json contract. A run that was paused for input on the draft can't be continued, because its next step would run the new code: the push cancels it, or, if it can't, answering it does. Earlier runs keep pointing at the draft and show its current code.
  • im-cli push --new-version creates a new draft instead and supersedes the old one into the replaced state, so the timeline stays a clean chain. Use it to keep a draft's code (and any run paused on it) as it is.
  • Pushing while a version is in pending_review requires im-cli push --force, which preempts the version under review with a new draft. Without --force the push is rejected (HTTP 409, exit code 1).

Only drafts are ever updated: a version under review, published, archived or rejected never changes after its push.

Use --replaces-version <label> to make the lineage explicit when you want to chain a push to a specific prior version.

Getting the source back

Every push retains the uploaded archive, so a version's source can be downloaded again with im-cli pull — the code a portal is actually running, recoverable independently of whoever's laptop pushed it. Pulling needs the same permission as pushing.

Retention started with the release that introduced im-cli pull; versions pushed before it have no archive and report so rather than failing quietly. Deleting an agent deletes its retained archives, and an operator can set a retention window (AGENTS_ARTIFACT_ARCHIVE_TTL_DAYS) after which older archives are pruned — the currently published version's archive is always kept, whatever its age.