CLI commands

Choose a command

Use the CLI to build images, check prerequisites and inspect retained work. Write agent tasks in TypeScript and run them with Node.js, as shown in Your first task.

• outpost doctorChecks the host, the sandbox provider and an image.
• outpost image buildBuilds the agent image from its recipe.
• outpost image removeDeletes the agent image.
• outpost recovery inspectLists what .outpost retains, read-only.
• outpost recovery verifyChecks a retained transfer before you restore it.
• outpost recovery restoreRestores a retained transfer into a new directory.
• outpost recovery pruneDeletes old data according to a retention policy.
• outpost --helpLists the commands, or one command’s options.

In a project that depends on @elie-laloum/outpost, run npx outpost <command>. Elsewhere, run npx @elie-laloum/outpost <command>.

Common options

Option	Commands	Effect
-h, --help	All	Prints the usage and options, then exits.
--json	doctor, recovery	Writes the report as JSON on stdout.
-y, --yes	init	Accepts the defaults without prompting.
--apply	restore, prune	Performs the change; without it, only preview.

Exit code	Meaning
0	Success. doctor warnings and skipped checks still exit 0.
1	A check failed, a report is incomplete, or the command failed (message on stderr).
130	Interrupted with Ctrl+C, or an init prompt was cancelled.
143	Stopped with SIGTERM.

outpost doctor

Check the host tools and selected sandbox provider. Add --image to check a local agent image in a temporary container as well.

outpost doctor [--sandbox-provider NAME] [--agent NAME] [--image NAME] [--json]

Flag	Default	Values and effect
--sandbox-provider	docker	docker, podman, local, vercel, daytona.
--agent	codex	codex, claude, antigravity, copilot, kimi.
--image	None	Also checks this local image in a temporary container. Docker and Podman only.
--json	Off	JSON report.

It exits 1 when a check fails. Diagnostics explains the report.

outpost image build

Build the agent image from the recipe in the chosen directory. Select Docker or Podman and give the result the image name used by your scripts.

outpost image build [--directory PATH] [--engine docker|podman] [--file PATH] [--image NAME] [--uid N] [--gid N]

Flag	Default	Values and effect
--directory	Current directory	Build context holding the recipe.
--engine	docker	docker, podman.
--file	Dockerfile (Docker), Containerfile (Podman)	Recipe path, relative to --directory.
--image	outpost:<directory name>	Image tag.
--uid, --gid	Your user and group IDs (1000 on Windows)	IDs of the agent user inside the image.

The engine’s output streams to the terminal, then the command prints build: <image>. A build stops after 30 minutes.

outpost image remove

Remove the local agent image when you no longer need it. Use the engine and image name from the build you want to remove.

outpost image remove [--directory PATH] [--engine docker|podman] [--image NAME]

--directory, --engine and --image take the same defaults as image build. The command prints remove: <image>.

outpost recovery inspect

Inspect the workspaces, retained transfers and recorded activity under a repository’s .outpost. This command reads the inventory without changing it.

outpost recovery inspect [--repository PATH] [--max-entries N] [--git] [--locks] [--resources] [--json]

Flag	Default	Values and effect
--repository	Checkout of the current directory	Repository whose .outpost is listed.
--max-entries	100000	Stops the inventory after this many entries.
--git	Off	Adds each workspace’s branch, HEAD and dirty state.
--locks	Off	Adds local lock PIDs and ownership.
--resources	Off	Adds recorded sandbox activity.
--json	Off	JSON report.

It changes nothing. It exits 1 when the inventory is partial.

outpost recovery verify

Verify a retained transfer before restoring it. You can compare checksums and test whether its patches apply in a temporary clone.

outpost recovery verify --directory TRANSFER [--checksums [--max-bytes N]] [--restorability --repository PATH] [--json]

Flag	Default	Values and effect
--directory	Required	Retained transfer directory.
--checksums	Off	Compares the files with the transfer’s checksum manifest.
--max-bytes	1 GiB	Bytes checked by --checksums, which it requires.
--restorability	Off	Applies the transfer’s patches in a temporary clone of --repository.
--repository	None	Checkout used by --restorability; they go together.
--json	Off	JSON report.

It changes no files. It exits 1 when a check fails or is incomplete.

outpost recovery restore

Restore the saved host state or incoming sandbox changes into a new directory. Preview the plan first, then add --apply when you are ready to create the copy.

outpost recovery restore --directory TRANSFER --repository PATH --destination NEW_PATH --side previous|incoming [--max-bytes N] [--apply] [--json]

Flag	Default	Values and effect
--directory	Required	Retained transfer directory.
--repository	Required	Checkout the transfer belongs to.
--destination	Required	New directory outside the repository; it must not exist.
--side	Required	previous (host state before synchronization) or incoming (sandbox changes).
--max-bytes	1 GiB	Largest retained payload accepted.
--apply	Off	Creates the destination; without it, prints the plan.
--json	Off	JSON plan or result.

The restored copy is a detached checkout. The transfer stays in place; review the copy before integrating it.

outpost recovery prune

Preview the removals selected by your JSON retention policy. Add --apply to delete those entries after reviewing the plan.

outpost recovery prune --policy FILE [--repository PATH] [--apply] [--json]

Flag	Default	Values and effect
--policy	Required	JSON policy file, up to 64 KiB (format).
--repository	Checkout of the current directory	Repository whose .outpost is pruned.
--apply	Off	Deletes the candidates; without it, a dry run.
--json	Off	JSON plan and result.

It exits 1 when the inventory is incomplete, the projected size exceeds the policy’s limit, or --apply had to keep a candidate. Branches and recovery artifacts are always kept.

outpost init

This command generates an example project and, with Docker or Podman, prepares its image. The recommended installation path uses it to build the image; you then write your own TypeScript scripts.

outpost init [--yes] [--directory PATH] [--repository PATH] [--agent NAME] [--sandbox-provider NAME] [options]

In a terminal, init prompts for the agent, sandbox provider, package manager and authentication you did not pass. Without a terminal, pass --yes or both --agent and --sandbox-provider.

init writes run.ts, brief.md, .env.example, .gitignore, the image recipe and, when none exists, package.json (optional project generation). It stops before writing if one of these files exists, except .gitignore, which it extends.

It then prints the sign-in steps for the chosen authentication and the command to run, such as node run.ts.

npx outpost init --yes --directory .outpost-image --image outpost:dev

Flag	Default	Values and effect
--directory	Current directory	Where the project is written.
--repository	.	Git checkout the workflow edits, relative to --directory.
--agent	codex	codex, claude, antigravity, copilot, kimi.
--sandbox-provider	docker	docker, podman, local, vercel, daytona.
--authentication	account (usage with --base-url)	account, usage; account-token for claude and copilot.
--model	The CLI’s default	Model name. Required for Kimi usage and for --base-url.
--base-url	None	Custom Codex Responses endpoint. Requires --model and usage.
--api-key-env	OPENAI_API_KEY	Key variable for --base-url.
--manager	packageManager field, lockfile, or npm	npm, pnpm, yarn, bun.
--install	Off	Installs @elie-laloum/outpost and the provider SDK as dev dependencies.
--build, --no-build	Build for docker and podman	Builds the image once the files are written.
--image	outpost:<directory name>	Image tag built and used by run.ts (Docker and Podman).

API: inspectRecovery · verifyRecoveryTransfer · planRecoveryRestore · restoreRecoveryTransfer · planRecoveryRetention · pruneRecoveryRetention.