mocactl command reference
Preview. Install
mocactlwith the one-line installer; how to use it, with its key bindings and troubleshooting, is Use mocactl.mocactltalks to the multi-user control plane, which tells it where the harness is. The sandbox service's commands aremocactl sbx.
Usageβ
The block below is mocactl --help, generated from USAGE in packages/mocactl/src/cli.ts; a
test fails when the two disagree. mocactl COMMAND --help prints only that command's syntax. To
update the block after changing the help text:
UPDATE_MOCACTL_REFERENCE=1 pnpm -C packages/mocactl exec vitest run test/mocactl-reference.test.ts
usage:
mocactl [--setup] [--no-animation] interactive terminal UI
mocactl --version print this build's version (a release tag, edge-<sha>,
or dev-<sha> from a source checkout)
mocactl login [--no-browser] log in with the GitHub device flow (in a local
terminal: copies the code, opens the browser)
mocactl login --test-user N log in as test user N (needs the control plane's
SH_TEST_USERS; secret in MOCA_TEST_USER_SECRET)
mocactl logout [--all] end this login (--all: every login of yours)
mocactl auth token [--json] print a valid API token, refreshing if needed
(exit 3: log in first; 4: control plane unreachable)
mocactl doctor [--json] check the setup; one fix per failure
mocactl run "prompt" [--session ID | --new] [--option key=value ...] [--json]
mocactl run "prompt" --config DIGEST start the new session with a promoted config bundle
mocactl run "prompt" --show-tools print each tool call the turn makes, between its
text (not with --json, which streams the frames)
mocactl run "prompt" --record F append one NDJSON line per HTTP attempt to F (0600):
path, status, times, ids; a stream's bytes, sha256
and frame count; never a token, host, prompt,
reply or patch (kept as sha256 or length)
mocactl promote DIR [--dry-run] [--json] upload DIR's .claude/skills and .claude/commands
(--dry-run: build and report, upload nothing)
mocactl bundles list [--json] your own stored bundles, newest first
mocactl bundles delete DIGEST [--json] delete a bundle you promoted and free its budget
mocactl sbx β¦ the sandbox service, workspaces in isolated VMs for your agent: login, up, pull, rm (mocactl sbx --help)
mocactl sessions [--json] list your sessions
mocactl sessions delete ID [--json]
mocactl credentials [--json] list your credentials (never their secrets)
mocactl credentials add NAME --host HOST [--host HOST ...] [--kind KIND] [--consumer CONSUMER]
[--endpoint URL] [--json] the secret is read from stdin
mocactl credentials delete NAME [--json]
mocactl spawn "prompt" [--config DIGEST] --kind prompt|solve
[--repo URL --ref REF] [--tag T] [--label L] [--json]
fork a detached subagent (solve needs --repo/--ref;
--label names one dispatch within a --tag group,
surfaced on 'mocactl subagents --json' as label)
mocactl spawn --prompt-file FILE [...] read the prompt from FILE (UTF-8, trimmed); use when
the prompt would otherwise be awkward on argv
mocactl spawn "prompt" --kind prompt --workload ID [--writable] [...]
run the subagent on a workload's context
(--writable: its own copy, discarded after)
mocactl spawn "prompt" --async [...] dispatch as a cancellable async turn instead of a
local worker process (needs SH_ASYNC_DRAIN on the
deployment; not available with --workload)
mocactl spawn "prompt" --max-concurrent N [...]
refuse the dispatch when N of your subagents are
already running (default 4)
mocactl subagents [--tag T] [--json] list spawned subagents + current state
mocactl watch [--tag T] [--json] one line per state change, until every watched
subagent is finished (--json: one JSON object per
line, for an agent's background monitor)
mocactl get SESSIONID [--out DIR] [--json] write result files + bounded summary
mocactl get SESSIONID --wait [--timeout S] block until the result is there, then write it
(default 300 s; exit 1 and status 'queued' if the
budget runs out, 'unknown' if the run is over
without one)
mocactl workloads create --context FILE [--name NAME] [--json]
[--sandboxes N [--mount read-only|writable]]
upload a context file (contextctl ctx pack) to a
new workload; prints its id (--sandboxes: N
sandboxes of its own; --mount: its context on
their own volume, no per-run copy)
mocactl workloads list [--json] your own live workloads, newest first
mocactl workloads get ID [--json]
mocactl workloads delete ID [--json] delete a workload and its context
flags for every command: --control-plane-url URL
(the control plane says where the harness is; --harness-url URL overrides that)
mocactl --version prints a release tag or edge-<sha>; run from a source checkout it prints
dev-<sha> (the checkout's commit, -dirty if tracked files differ from it), or dev where git can't say.
All flags are accepted by one parser. An unknown flag, or a missing flag value, prints the usage and
exits 2. Some flags are always rejected (exit 2) outside their command: --consumer, --host and
--endpoint outside credentials add; --kind outside credentials add and spawn; --config
outside run and spawn; --repo and --ref outside spawn; --tag outside spawn,
subagents and watch; --label outside spawn; --out, --wait and --timeout outside get;
--max-concurrent outside spawn; --workload outside spawn; --async outside spawn;
--prompt-file outside spawn; --record outside run;
--context, --name, --sandboxes and --mount outside workloads create; and --all outside logout. Other flags a
command does not use are not rejected and may be ignored.
Endpointsβ
For both URLs the order is: flag, then environment variable, then config.json. Trailing slashes are
trimmed and blank values count as unset.
| URL | Flag | Environment | Config key |
|---|---|---|---|
| Control plane | --control-plane-url | SH_CONTROL_PLANE_URL | controlPlaneUrl |
| Harness | --harness-url | SH_HARNESS_URL | harnessUrl |
With no harness URL, mocactl asks the control plane (GET /v1/discovery), which advertises the
SH_PUBLIC_HARNESS_URL its operator set. Every command that talks to the control plane exits 2 with
missing control-plane URL if none is set.
The cached login belongs to one control plane, and is matched by endpoint rather than by spelling:
host case, an explicit :80/:443 and a trailing slash all name the same control plane, so moving
between the flag, the environment variable and config.json keeps you logged in. A different
scheme, host, port or path prefix is a different control plane β its login is not used, and the
message (and mocactl doctor) then names the control plane the login on this machine is for.
Exit codesβ
| Code | Meaning |
|---|---|
0 | It worked |
1 | It failed (the turn, or the control plane refused) |
2 | Usage or setup problem: bad flags, not logged in, no destination for the turn |
130 | Cancelled (Ctrl-C) |
3 | auth token: login required. promote: a credential would reach a shared store |
4 | auth token: the control plane is unreachable |
Output convention: stdout carries only the result, and all messages go to stderr. Times in tables are
UTC. Most commands that need a login print not logged in β run `mocactl login` first and exit 2, with
exceptions: a login that cannot be refreshed prints the login could not be refreshed β is the control plane reachable? instead; auth token exits 3 (login required) or 4; logout while logged out exits 0; and
promote --dry-run skips the check.
Commandsβ
| Command | What it does and calls |
|---|---|
mocactl [--setup] [--no-animation] | The interactive UI. --setup re-runs onboarding. Exits 2 when stdin is not a terminal |
mocactl login | GitHub device-flow login (POST /v1/auth/device, then polls /v1/auth/device/token). Prints the code to stderr |
mocactl logout [--all] | Ends this login on the server (POST /v1/auth/revoke); --all ends all of yours (/v1/auth/revoke-all). The local file is cleared anyway |
mocactl auth token [--json] | Prints a valid API token for scripts, refreshing if needed. --json: {"token","expiresAt","subject"} |
mocactl doctor [--json] | Seven ordered checks that stop at the first failure (below). Exit 1 if any fails |
mocactl run "prompt" [--session ID | --new] [--option k=v ...] [--config DIGEST] [--json] [--record F] | Runs a turn. Continues --session, or starts a new session (--new, the default) |
mocactl promote DIR [--dry-run] [--json] | Builds a config bundle from DIR/.claude and uploads it (POST /v1/config-bundles). See Promoting |
mocactl bundles list [--json] | Lists the bundles you own, newest first (GET /v1/config-bundles). See below |
mocactl bundles delete DIGEST [--json] | Deletes a bundle you promoted (DELETE /v1/config-bundles/{digest}). DIGEST must be sha256: plus 64 hex characters |
mocactl sessions [--json] | Lists every session you own (all pages of GET /v1/sessions) |
mocactl sessions delete ID [--json] | Deletes a session and its local transcript. status is deleted, or accepted when a turn was in flight |
mocactl credentials [--json] | Lists names, kinds, consumers, hosts and endpoints; never secrets |
printf %s "$KEY" | mocactl credentials add NAME --host HOST [--host H ...] [--kind K] [--consumer C] [--endpoint URL] [--json] | Stores a credential (PUT /v1/credentials/{name}). The secret is read from stdin and a terminal on stdin is refused |
mocactl credentials delete NAME [--json] | Deletes a credential; exit 1 if you own none of that name |
mocactl spawn "prompt" [--config DIGEST] --kind prompt|solve [--repo URL --ref REF] [--tag T] [--label L] [--json] | Creates a session, writes a ledger record, forks a detached worker that holds a POST /v1/runs. Prints the sessionId on stdout. --label names one dispatch within a --tag group ([A-Za-z0-9][A-Za-z0-9._-]{0,63}), surfaced on mocactl subagents --json as label. Pass --prompt-file FILE (regular file, no symlinks, UTF-8, trimmed) instead of an inline prompt when the content would be awkward on argv |
mocactl subagents [--tag T] [--json] | Lists spawned subagents from the ledger joined with GET /runs/status |
mocactl watch [--tag T] [--json] | Prints one line per state change of the watched subagents and exits when every one is finished. See below |
mocactl get SESSIONID [--out DIR] [--json] | Fetches a terminal result from GET /runs/status and writes <sid>.text / <sid>.verdict.json / <sid>.patch |
mocactl workloads create --context FILE [--name NAME] [--sandboxes N [--mount read-only|writable]] [--json] | POST /workloads (with sandboxes: {count: N} and workspace: {mount} when given), uploads FILE to the returned grant, then POST /workloads/{id}/activate, and with --sandboxes waits until the workload is ready. Prints the workload id |
mocactl workloads list [--json] | Lists your own live workloads, newest first (GET /workloads, following its cursor to the end). See workloads list |
mocactl workloads get ID [--json] | Reads a workload (GET /workloads/{id}) |
mocactl workloads delete ID [--json] | Deletes a workload and its context (DELETE /workloads/{id}) |
runβ
- The prompt is the positionals joined with spaces. Exit 2 for an empty prompt,
--newwith--session,--configwith--session(a session's bundle is fixed at creation), a blank--config, or an--optionwithout=. --optionkeys:inferenceCredential=NAME,model=IDandsandboxTier=NAME.modelis listed from the chosen credential's endpoint, with the deployment default as the first choice;mocactl runnever asks: with none given, the session runs on the deployment default (only the TUI's New Session form asks, even for a single listed model, the deployment default preselected unless a model was used last);model=(empty) also means the deployment default; an id the catalog does not list exits 2 (unknown model 'X'; declared: β¦), including an id a LiteLLM wildcard route such asanthropic/*would accept, becauseGET /v1/modelslists only concrete models (switch to such an id with/model Xin the TUI); when the endpoint cannot list its models, the id is sent as given and checked by the gateway at the first turn. An ambiguous or unknown choice forinferenceCredentialexits 2 with the declared values. With severalsandboxTierchoices and none given, the tier is left unset for the server default; a value for a field that has no choices exits 2. Unknown keys are silently ignored, and=x(no key) exits 2.--optionis ignored when resuming a session.- Text mode streams the reply to stdout, and reports a
workspace_resetto stderr. --jsonemits NDJSON: a first line{"type":"session","sessionId":...}, then one raw turn frame per line.--record Fappends one NDJSON line per HTTP attempt, to the control plane and to the harness (the login's refresh included), in the format below, withcommand: "run"andendpoint(control-planeorharness;otherfor a request under neither, its host unwritten). Kept: the path below that endpoint's base URL, the status, the session's id, model and times, the sandbox placement,patchSha256andpatchBytes. Kept as their length: the prompt, the reply, a frame's text, the patch, a transcript, a message and other free text, a person's display name, a credential's hosts and endpoint.--recordon any other top-level command exits 2.
--record Fβ
mocactl run and every mocactl sbx command that calls the API, except sbx token, sbx login,
sbx logout and sbx credentials (they handle a secret on purpose, and exit 2), take --record F.
It appends one JSON line per HTTP attempt to F:
| Field | What it holds |
|---|---|
command, invocation | The command (run, sbx create, β¦) and a UUID for this run of it |
seq, try | The line's number in this invocation; 1, 2, β¦ for the same method and path in a row (a retry) |
method, path | The path relative to the endpoint's base URL, with its query; never the scheme or host |
status or error | The HTTP status, or a transport error's code or class (never its message) |
request, answer | The JSON bodies, redacted (below); a body that is not JSON as its length |
requestAt, answerAt, retryAfter | UTC times with milliseconds, and the Retry-After header when there is one |
stream, event: "stream_end" | A streamed answer (SSE or NDJSON) passes through live: its line has stream: true at the headers, and a stream_end line for the same seq gives bytes, sha256, frames, endedAt, and error or closedBy: "reader" when it did not end normally |
Never written: a token, a host or a URL. Token fields (token, refreshToken, refresh_token,
sessionToken, apiToken, accessToken), a gate record, a credential's secret, and any string
shaped like a JWT or a refresh token, under any field, are replaced by their sha256:; execEndpoint,
execCa, harnessUrl, a reason's message, a log, and any string that is an absolute URL by
{"length": N}. F is created 0600 and opened for appending; an existing F readable or
writable by anyone else, or not a regular file, exits 2 before any request. Each line is written
whole in one write; a line longer than PIPE_BUF takes a lock file F.lock, so several processes
can append to one record. sbx run, put, push and pull reach the sandbox over gRPC, which is
not recorded: the record holds their control-plane calls (the sandbox read, the token mint).
sbx claude and sbx codex record their own calls only, not those of the mocactl sbx mcp
server the agent starts.
workloads listβ
Your own live workloads, newest first; nobody else's, and there is no route that lists another
user's (#552). Takes no id: finding one without
already holding its id is the point, so workloads list ID exits 2.
- A table of
WORKLOAD STATUS TYPE SIZE SANDBOXES CREATED REVISION.CREATEDis relative (4m ago),REVISIONis the first 12 characters, and-means unset βCREATEDis-for a workload created before the harness recorded the field, which is also absent from the listing (see "Upgrading" in Context Service and workloads). --jsonprints one document,{"workloads": [...]}, withnullfor what a workload lacks andcreatedAtin ISO 8601.- With no workloads it says
no workloadson stderr and prints no table, somocactl workloads list | wc -lcounts workloads;--jsonprints{"workloads": []}. - A
deletingworkload is listed, because it still holds a quota unit; adeletedone is not, thoughworkloads getstill reads it for a day. SANDBOXEScan lag: the listing never settles aprovisioningworkload (so listing N makes no provisioner calls).workloads get IDsettles one.
credentials addβ
--host is required and repeatable (a comma list also works). Defaults: --kind bearer,
--consumer inference. --endpoint is for the inference consumer only. Everything except the secret
is validated before stdin is read.
| Kind | stdin |
|---|---|
bearer | The token, one line |
api-key | The key, one line |
oauth2-token | The access token, one line |
basic | username=β¦ and password=β¦, one per line |
Consumers are inference, sandbox-egress and control-plane. basic is not for inference; use it
with --consumer sandbox-egress. For the inference consumer, an Anthropic sk-ant-api⦠key under
a bearer kind (bearer or oauth2-token) is rejected, as is an api.anthropic.com endpoint with a
bearer kind holding anything but an Anthropic OAuth token. A Claude Pro/Max sk-ant-oat⦠OAuth token
works with kind oauth2-token (or bearer) and endpoint https://api.anthropic.com β and only
there: aimed at a gateway it is rejected before the credential is sent. That check needs the secret,
so it runs after stdin is read.
A subscription OAuth token is a per-caller credential: it runs the session under the Claude Code
identity (the claude-code-20250219 beta and its system prompt), and consumer tokens are meant for
Anthropic's own apps β storing one here is your call about your own account's terms. The deployment's
shared operator fallback refuses them for exactly that reason: one subscription must not serve every
caller.
spawn, subagents, watch, getβ
See Use mocactl and
docs/specs/2026-10-12-mocactl-subagent-commands-design.md
for behavior; this section covers only CLI-reference details.
spawnexit 2: empty prompt, prompt over 64 KiB, bundle digest not matchingsha256:<64 lowercase hex>,--kindother thanprompt/solve,--kind solvewithout both--repoand--ref, or--repo/--refon--kind prompt,--workloadwithout--kind prompt, a workload id that is not a lowercase Kubernetes name of at most 50 characters, a--labeloutside[A-Za-z0-9][A-Za-z0-9._-]{0,63}, or--prompt-filecombined with an inline prompt, pointing at a missing/unreadable path, a symlink, a non-regular file (FIFO, socket, device, directory), a file over 64 KiB, or an empty/whitespace-only file.spawnon a sync 503saturated: the worker retries up to 3 times honoringRetry-After, bounded by a 5-minute wall budget; after that the ledger row isfailedwithstateDetail: 'saturated β exhausted retries'.spawn --max-concurrent N(default 4) refuses the dispatch, exit 1, when N of your subagents are already running β before the session is created and before the worker is forked, so a refused dispatch costs nothing. The count is of this machine's ledger rows that are both non-terminal and have a live child pid; a row whose child is gone holds no slot, so an unreconciled crash cannot wedgespawn. An--asyncrow has no child, so it holds its slot until asubagentsorgetcall reads the turn and records a terminal state. The server's own pool is the real bound (a sync 503saturated, retried as above). Exit 2 for anNthat is not a whole number of at least 1.spawn --asyncdispatches the leaf as an async turn (POST /v1/sessions/{id}/turns) instead of forking a local worker that holds a synchronous/v1/runs. What it buys: a turn record, which is what makes a subagent cancellable, and no local process β nothing on this machine has to survive the command, so a laptop can close on a running subagent. The turn id is recorded in the ledger row and is whatsubagentsandgetread the leaf through from then on. Exit 2 with--workload: the control plane refuses a workload on the async path (501), so it is refused before the session is created. It needsSH_ASYNC_DRAIN=1on at least one worker of the deployment β that is off by default, and without a drain the turn sitsqueueduntil the server's reaper calls itlost. A row spawned with--asyncon another machine is invisible to this one'sget: there is no ledger row to carry the turn id.watch [--tag T]prints one line per state change of the rows it watches β the same ledger rowssubagentslists, read the same way (aturnIdrow through its turn, any other throughGET /runs/status), and persisted the same way. The first sweep reports every row, so watching a batch that is already over says so rather than printing nothing; after that a row is printed only when its state or detail changes. It polls every 5 s, slower thanget --wait's 2 s, because it is meant to run as a background monitor rather than as an interactive wait. The ledger is re-read each tick, so aspawn --tag Tfrom another terminal joins a runningwatch --tag Tβ spawn some, watch, spawn more. It exits 0 once every watched row isdone,failed,pausedorunknown.unknowncounts as finished even though it is not a terminal state: it is the client's "no result is coming" β a child that exited without writing one, past the 60 s result-write grace, or a status read that failed β so a read failure ends the watch with a line that says so instead of retrying silently; re-run it for another look. Ctrl-C exits 130, and the subagents keep running. There is no--timeout: every row reaches a finished state on its own (the sync path bounded by its child, an--asyncrow by the server's reaper marking the turnlost), so wrap it intimeoutif a script needs a hard cap. Exit 0 with ano subagentsline on stderr when the ledger has no matching row.getexit 2: sessionId outside[A-Za-z0-9][A-Za-z0-9._-]*[A-Za-z0-9], or--timeoutwithout--wait, or a--timeoutthat is not a whole number of seconds of at least 1. Exit 0 only onresponded/done/solved;queued/paused/failedexit 1.get --wait [--timeout S]blocks until the result is collectable instead of reading once, then writes and summarizes it exactly as a plaingetdoes β one call, result inline, for a caller that spawns and collects in the same turn. It pollsGET /runs/statusevery 2 s within anSbudget (default 300, never overrun) and re-mints the session token as it nears expiry, sinceSH_SESSION_TOKEN_TTL_SECONDSalso defaults to 300. On an--asyncrow it pollsGET /v1/sessions/{id}/turns/{turnId}instead, with the API token the command already holds, and fetches the reply and the patch from the turn's artifact routes once it has a result. It stops early, exit 1 andstatus: "unknown", when the ledger says no result is coming: the row already went terminal client-side (a fork failure), or its child exited without writing one, past the 60 s result-write grace. On the budget running out the output is what a not-finishedgethas always printed βstatus: "queued", exit 1 β soqueuedandunknowndistinguish "not yet" from "never". Ctrl-C ends the wait with exit 130 and no error line, whether it lands during a poll or between two; the subagent itself keeps running, so a latergetstill collects it.--json:spawnβ{"type":"session","sessionId","pid"}, or{"type":"session","sessionId","turnId"}with--async, which has no local process to name.subagentsβ{"subagents":[{"sessionId","tag","label"?,"kind","state","detail","bundle","workload","writable"?,"submittedAt"}]}(labelandwritableare present only on rows dispatched with them). The non---jsontable columns areSESSION TAG LABEL KIND STATE BUNDLE(-on unlabeled rows).watchβ NDJSON, one event per line:{"sessionId","tag","label"?,"kind","state","detail","at"}(atis epoch milliseconds; the other fields aresubagents --json's, so one parser reads both). Without--jsoneach line isstate sessionId [label or tag] (detail), the state padded so the ids line up.getβ{"sessionId","status","files":[β¦],"reason"?,"message"?}, or{"sessionId","status":"queued"}with nothing to collect, or{"sessionId","status":"unknown","detail"}when--waitstops because no result is coming.
Following up on a subagentβ
There is no follow-up command: mocactl run "prompt" --session ID already is one, on a session
spawn created. It sends the new turn to /v1/turn, which writes no leaf result record β
writeResult is called only from the /v1/runs handler β so the result a previous mocactl get
would collect survives the follow-up rather than being overwritten. Collect first anyway if you
want the files on disk before the session moves on.
workloadsβ
See Delegate with context and
docs/harness/how-to/workloads.md. The routes are on the harness and take the API
token. There is no list command: the harness has no list route.
createexit 2: no--context, a missing, empty or non-regular file, an invalid--name, a--sandboxesthat is not a whole number of at least 1, a--mountother thanread-onlyorwritable, or--mountwithout--sandboxes; all before any request.createexit 1 for a refusal, including a file larger than the grant'smaxBytesor an upload URL that is neither HTTPS nor loopback HTTP; a workload created before the failure is deleted.create --sandboxes: activation answersprovisioningwhile the workload's own sandboxes start;createpollsGET /workloads/{id}every 2 s for up to 5 minutes. Onseed_bundle_missing(the provisioner lost the bundle) it activates once more. Any other recordederror, the same error again, or the timeout exits 1 and deletes the workload.get/deleteexit 2 for an invalid id, exit 1 for404 workload_not_foundor another refusal.deleteon a workload that is already deleted exits 0: the workload is gone, which is what was asked for, so a cleanup script can delete every id it knows without telling "already done" from a real failure (#602). Only404 workload_already_deletedis treated this way βworkload_not_foundstill exits 1, because there the id may simply be wrong.--json:createβ{"workloadId","status","contextType","revision","files","bytes"}, plus"sandboxes":{"count","tier","ready"}and"mount"for a workload with sandboxes of its own.getβ{"workloadId","status","contextType","workspace","revision","sandboxes"}(nullwhen unset;workspace.mounton a mounted workload), plus"error"while provisioning has failed. The table addsSANDBOXES(ready/count) andMOUNTcolumns.deleteβ{"workloadId","status":"deleted"}, plus"alreadyDeleted":truewhen the workload was deleted before this call (absent otherwise, so the document reads the same either way).
bundles listβ
Answers "which config bundles do I own?", so a digest lost between promote returning and whatever
stored it is recoverable instead of holding your byte budget until it expires.
- Only your own bundles. Another subject's is indistinguishable from one that does not exist, and an admin sees their own listing like anyone else β this is not an audit command.
- Takes no
DIGEST(exit 2 if given): finding one is the point. - Newest first, by when it was promoted. A bundle from before the control plane recorded that time
prints
-and sorts last. - Columns
DIGEST BYTES PROMOTED (UTC) EXPIRES (UTC). The digest is printed in full becausebundles deletetakes exactly that string. BYTESis what the bundle is charged, not the size of your directory: the compressed upload, or a 4 KiB minimum if it is smaller.EXPIRESmoves: each session that uses a bundle extends its 30-day life.PROMOTEDdoes not.- With no bundles, stdout stays empty β the message goes to stderr β so
| wc -lanswers 0.--jsonprints{"bundles":[]}. - One unpaged response. No cursor: the index is ordered by expiry, which a concurrent use can move, so a cursor could skip or repeat a bundle. Your 16 MiB subject budget bounds the count.
- A bundle promoted by the harness's own
promotetool writes storage directly and keeps no budget entry, so it does not appear here (the same population only an admin can delete). - A charge whose stored bytes were already reaped is still listed: that charge is exactly what you
need
bundles deletefor. --jsonβ{"bundles":[{"digest","bytes","promotedAt","expiresAt"}]}, epoch milliseconds,promotedAtnullwhen unrecorded. Exit 1 if the control plane refuses, 2 if not logged in.
promote exit codesβ
| Code | Cause |
|---|---|
0 | Success, or a dry run |
1 | No .claude/skills or .claude/commands under DIR; nothing to promote; bundle too large; other |
2 | Wrong argument count; not logged in (not checked with --dry-run); preflight errors |
3 | A structural credential match; nothing was uploaded |
--json prints the whole result: {digest, configRoot, skills, dropped, prompts, report, warnings, uploaded},
plus dryRun: true for a dry run.
~ is expanded in DIR.
doctorβ
| # | Check | Calls |
|---|---|---|
| 1 | Control plane reachable | GET /healthz |
| 2 | Control plane ready | GET /readyz |
| 3 | Logged in | GET /v1/me |
| 4 | Inference credential present | GET /v1/credentials |
| 5 | Harness located | GET /v1/discovery, or the local override |
| 6 | Harness reachable | The harness GET /health |
| 7 | Harness trusts this control plane | See below |
Check 7 is not read-only: it creates a scratch session, probes the harness with a mismatched session
id, and deletes the session. --json is an array of {id,name,status,fix?,detail?}.
Environment and filesβ
| Name | Use |
|---|---|
XDG_CONFIG_HOME | Default ~/.config. Holds mocactl/config.json and auth.json (tokens, mode 0600) |
XDG_STATE_HOME | Default ~/.local/state. Holds mocactl/transcripts/ and mocactl/exports/ |
NO_COLOR | Any non-empty value turns colour off |
VISUAL, then EDITOR | External editor for /editor and /export; vi if neither is set |
config.json keys: controlPlaneUrl, harnessUrl, theme (system or dark), details,
thinking, reducedMotion, bell, keybinds (command id to chord), presets, lastUsed. A field of
the wrong type falls back to its default with a warning on stderr; unknown keys are preserved.
Interactive slash commands and keysβ
The leader key is ctrl+x, followed by a letter. Override a binding in config.json under keybinds
using the command id.
| Command id | Slash | Default key |
|---|---|---|
session.list | /sessions, /resume | ctrl+x l |
session.new | /new | ctrl+x n |
session.promote | /promote DIR, /promote --clear | none |
session.rename | /rename <title> | ctrl+x r |
session.model | /model [id|default] | ctrl+x m |
credentials | /credentials | ctrl+x k |
view.details | /details | ctrl+x d |
view.thinking | /thinking | ctrl+x t |
reply.copy | /copy | ctrl+x y |
transcript.export | /export | ctrl+x x |
input.editor | /editor | ctrl+x e |
view.theme | /theme | none |
doctor | /doctor | none |
help | /help | ? on an empty input |
palette | none | ctrl+p |
quit | /quit, /exit, /q | ctrl+x q |
Esc cancels the running turn (twice within a second also clears the queue); Enter sends;
alt+enter or shift+enter adds a newline; ctrl+c quits, asking first if a detachable turn would be
left behind. /promote DIR uploads the bundle and attaches it to the next session you create.
Known gapsβ
- The keys inside the Sessions, Credentials and Palette overlays are not listed here.
- Use mocactl states exit codes as
0, 1, 2, 130for every command and documentspromote's exit 3, but notauth token's exits 3 and 4 (onlyauth tokenuses 4).