[ docs · guides ]
CLI reference
The whole surface is small: one interactive session, one headless runner, and a handful of supporting commands. This page is all of them.
Commands
| Command | What it does |
|---|---|
grist | Open the interactive TUI in the current directory. |
grist run | Run a task headlessly and print the result — the scripting and agent-delegation entry point. |
grist auth login | Sign in to your Grist account, or paste an API key, and attach provider keys. |
grist doctor | No-spend health check: sign-in, gateway reachability, and gate mode. |
grist upgrade | Update the CLI to the latest release. grist update works too — same command. |
grist models | Show the ladder: the rungs and the model currently behind each one. |
grist stats | Session and spend statistics for work done through your account. |
grist session | List and inspect past sessions, so you can pick one up again. |
grist mcp | Manage the MCP servers Grist can call as tools. |
grist debug | Print diagnostic detail — config, paths, and environment — for support and debugging. |
grist serve --service | Run Grist as a managed background service. The TUI and grist run talk to it when one is elected. |
grist run flags
| Flag | Effect |
|---|---|
-m grist/<rung> | Pin a rung for this run — grist/cheapest, grist/medium, grist/frontier, or grist/premium. The default is to let the gate decide, and that default is usually right. |
--format json | Emit machine-readable output, including the session id — what scripts and delegating agents parse. |
--session <id> | Resume an existing session instead of starting a new one. |
Resuming work
There is deliberately no grist resume command. A session already knows where it lives: resume it with grist run --session <id> "next instruction" and it restores its own directory and history. Find ids with grist session, or read them from --format json output at creation time.
When something looks wrong, run grist doctor first. It spends nothing, and it separates the three failure classes that matter — sign-in, gateway reachability, and gate mode — in one pass.
Environment knobs
The harness reads a handful of environment variables. The defaults are the product — reach for these only when you mean it:
| Variable | What it does |
|---|---|
GRIST_GATE=off | Turns the Jev gate off (not recommended) — runs pass through unrouted. |
GRIST_EFFORT=low|standard|high | Pins the effort dial instead of letting the gate dial it per task. |
GRIST_MECH=auto|efficiency|performance|off | SoL-Pi mechanism profile. efficiency turns every token cut on; performance keeps full tool output with fusion still on; off disables both. |
GRIST_WARM_SUBAGENTS=0 | Disables warm subagent resume — repeat specialist calls start cold. |
GRIST_API_KEY | Supplies a grist_sk_ key without an interactive login (the headless path for agents on a VM). |
GRIST_GATEWAY_URL | Points the CLI at a gateway other than https://grist.lol. |