| name | chariot-cli |
| description | Deploy and manage Chariot agents, images, and fleet packs with the Chariot CLI. Use when Codex needs to install or update Chariot, authenticate an account, inspect credits or agents, deploy and lifecycle agents, connect over SSH, push custom images, publish or deploy fleet packs, or wire production messaging through Chariot's HTTP API. |
Chariot CLI
Use the CLI for account, fleet, image, and lifecycle operations. Use Chariot's
HTTP API for application messaging.
Start Safely
- Run
chariot version and chariot --help before relying on remembered
syntax. Use chariot update when the CLI reports a newer release.
- Install with
brew install chariots-sh/tap/chariot when Chariot is missing.
- Never print
~/.chariot/config.json, token seeds, bot tokens, API keys, or
deployment handoff files.
- Treat purchases, permanent deletion, publication, and public endpoints as
user-confirmed external actions.
For a second account, isolate all CLI state rather than replacing the user's
main login:
mkdir -p ~/.chariot-test-account
HOME=~/.chariot-test-account chariot login
HOME=~/.chariot-test-account chariot account
Keep using the same HOME override for every command on that account.
Authenticate And Inspect
Run chariot login. It opens a browser and waits for approval. Pause when the
user must enter an email code, approve the device, or buy credits. After login,
verify the intended account before changing anything:
chariot account
chariot list
chariot images
chariot models
Do not infer agent state from a previous conversation; query it again.
Deploy Agents
Choose the count, image, model, and optional webhook endpoint with the user.
Omit --endpoint for inbox polling.
chariot deploy --count <N> \
[--image <image>] \
[--model <provider/model>] \
[--endpoint <https-url>]
Agents start deactivated and wake on first use. Deployment prints a token seed
once. Capture output in a private directory, immediately store the seed as
CHARIOT_TOKEN_SEED in a mode-0600 secret file or secret manager, and ensure
it cannot enter source control. Do not paste it into chat or terminal summaries.
After deployment, verify:
chariot list
chariot account
Use the long UUID from chariot list when an API or destructive command
requires an agent ID. Use the slug where the command explicitly accepts a slug.
Verify Messaging Once
Use demo commands only as a smoke test:
chariot demo watch --from-now
chariot demo send <agent-uuid> "hello"
Stop the watcher after receiving the reply. For production integrations, run
chariot api and call the HTTP API directly:
POST /v1/agents/{agent-id}/messages to send.- Receive replies through the configured webhook or poll
GET /v1/replies.
- Authenticate with the deployment token seed as documented by
chariot api.
Never build an application by spawning chariot demo processes.
Manage Lifecycle
Query state before acting:
chariot list
chariot hibernate <agent-slug> is reversible. It stops active compute while
preserving persistent state; a message or SSH session wakes the agent.chariot hibernate-after manages automatic idle hibernation. Its duration is
dd:hh:mm.chariot delete <agent-uuid> --yes is permanent. Confirm intent and the UUID
immediately before deletion.
Do not delete an agent merely to stop charges; hibernate it unless the user
explicitly wants the persistent state destroyed.
Connect Over SSH
Use Chariot-issued short-lived certificates:
chariot ssh <agent-slug>
chariot ssh <agent-slug> -- <command> [args...]
chariot ssh --config <agent-slug>
SSH can wake a hibernating agent. Prefer non-interactive remote commands for
repeatable checks. Use --config only when the user needs plain ssh, scp,
or VS Code Remote access.
Push A Custom Image
- Run
chariot image guidelines and read the complete container contract.
- Ensure Docker is running and build for
linux/amd64.
- Verify locally before upload.
- Push with a stable name and explicit pod size:
chariot image push <image:tag> --name <name> --pod-size <small|medium|large>
chariot image status
Wait for ready. A failed push does not alter the running fleet. Push and
verify the intended image before sending the first message to newly deployed
agents, because first wake selects their runtime.
Work With Fleet Packs
Fleet packs bundle image/count recipes and may carry a setup skill. The setup
skill guides the recipient's coding agent; it is not injected into agent pods.
chariot fleet create <pack> --image <name>:<count> \
--description "<description>"
chariot fleet skill set <pack> <file.md>
chariot fleet publish <pack>
chariot fleet browse
chariot deploy-fleet <pack> --from <owner-email>
Before publishing, verify the pack composition and skill. Before deploying
another account's pack, report its images, agent count, and daily fee. Secure
the fleet token seed exactly like a normal deployment.
Use chariot fleet unpublish <pack> to stop discovery and new deployments;
existing deployed fleets continue running. Delete a pack only when the user
intends to remove the recipe itself.
Finish
Report the account, created or affected agent slugs, image/model, final states,
active daily fees, verification performed, and any remaining setup owned by the
user. Never include secret values. Hibernate disposable test agents and remove
temporary watchers or test resources before handing off.
