CLI exit codes
On this page
dctx map, dctx pack, dctx context, dctx doctor, dctx rpc, dctx languages, dctx cache, dctx template, a bare dctx without a terminal, an unknown command and a non-UTF-8 argument follow one contract:
Pack and map use the current directory unless a project root is specified,
including a directory named fixtures; paths are relative to that root. dctx read is an alias
for dctx map read, with the same flags and exit codes.
| Code | Meaning | Examples |
|---|---|---|
| 0 | ok: the command answered | a find page, including one with no hits; --help |
| 1 | no result: the command ran, but the named target or input has no answer | map read m:nope.py (an id not in the index); map read logo.png (a binary file); pack of a directory with no packable file |
| 2 | usage: the arguments are wrong | an unknown command or flag; a missing target (dctx context with no TARGET); --depth 9; an empty find query; a stale --cursor; m:../outside; a non-UTF-8 argument; cache purge without --root/--all or --yes; a template that does not compile; a bare dctx whose stdin or stdout is not a terminal |
| 3 | index error: the place, source, cache or index could not be opened, read, built or written | --place /no/such/dir; a corrupt or busy cache; a source over DCTX_MAX_SOURCE_BYTES; an --output file that cannot be written; template build /no/such/file (the message names the path) |
Every failure prints two lines on stderr: Error: <what went wrong> (prefixed with the command, as map: …), then hint: <what to do next>. No input should reach a Rust panic; crates/dctx-cli/tests/cli_errors.rs and <repo>/scripts/checks/V1-5.zsh run twelve bad inputs and assert the code, the message, the hint and the absence of panicked.
Details#
- An id the index does not hold is a facade outcome (
gone), not an error.dctx mapprints thegonepage on stdout, then exits 1 with the hint. - An empty
findorgreppage is an answer and exits 0. Exit 1 is for a named target that is not there. - A binary target is detected before the scan: a NUL byte in the first 8 KiB of the file named by
map,skeleton,explainorread(path orm:id).neighborsandpathstill accept such a module, since source files can import it. dctx packexits 1 only when no view filter is set (--ext,--include,--exclude,--binary,--empty,--non-empty,--large,--small,--hidden,--debug-ignored). A filter that matches nothing still prints an empty page and exits 0. The page (stdout) and thepack bytes=…status line (stderr) are printed before the exit-1 message.packexit 3 covers source, scan, render and output failures.- A reader that closes stdout early (
dctx pack . | head -1) ends the run with exit 0 and no message, ascatdoes; every other failure keeps its code. dctx pack --for <TEXT>exits 1 when no name in TEXT matched the index (the page is printed first), 2 for a bad flag or a--budgetoutside 100..100000 (or--budgetwithout--for), and 3 when PATH is not a directory or the index fails.- A facade refusal of the query (
InvalidRequest,BudgetTooSmall,StaleContinuation,Stale,UnsupportedCapability,UnsupportedVersion) is 2;PolicyDeniedandPolicyUnavailableare 1; every other facade error, and every error of the snapshot build, is 3. The mapping isdctx_cli::exit::from_facade. map hubs,map pathandmap exportreport their facade errors as text: anunknown idend ofmap pathis 1, anything else 3.dctx contextwith no TARGET is 2;dctx context --helpprints usage and exits 0. A TARGET that names nothing prints its empty page, then exits 1.dctx cacheexits 2 for a bad flag or value, a purge without--root PATH/--allor--yes, and a--max-bytesthat would loosen the cap; 1 for a--rootid the ledger does not hold; 3 when the cache directory, policy or ledger cannot be read or written (the message names the directory).dctx templateexits 2 for a bad flag and for a template that does not compile, and 3 when the template, the--dirdirectory or the--outputfile cannot be read or written (the message names the path).--outputnever writes through a symbolic link and refuses a target that is not a regular file.dctxwith no command opens the interactive menu only when stdin and stdout are terminals; otherwise it prints the short usage as a hint and exits 2.dctx doctorfollows the contract;dctx rpckeeps exit 0 at end of input (see Engine RPC below).
Outside the contract#
dctx plugin … and dctx git … return the plugin host's own codes.
Engine RPC#
dctx rpc uses the same operation paths and numeric taxonomy over
versioned NDJSON. Each reply carries engine_version
and echoes its request id. An error contains the CLI code, diagnostic, hint and
any stdout emitted before failure (including gone pages). Protocol/framing
refusals use code 2 and leave the session usable. Cache status replies carry
the same codes and hints as dctx cache status. An error reply does not change the server's process exit
status: normal EOF exits 0, transport I/O errors exit 3, and broken stdout exits
quietly with 0. The server performs no piggyback auto-clean.
pack --for TEXT --json now emits the facade's context JSON page; its text
member contains the same budgeted context page as plain pack --for TEXT.