ncode CLI Automation
Headless runs
ncode -p runs one turn without the full screen: it sends your prompt, prints the answer as it streams, and exits. Use it from scripts, shell aliases and editor tasks.
One prompt#
ncode -p "summarise the open TODOs in lib/" > todos.mdThe project is the current folder, or the one you name: ncode ~/dev/app -p "…". -p also has the long forms --prompt and --print.
Each -p run starts a new conversation, so it does not carry the context of the one you were working in. The conversation is saved like any other, and you can open it later in the full screen.
Reading the prompt from stdin#
-p - reads the prompt from standard input:
ncode -p - < review-request.md
git diff | ncode -p - --model Anthropic/<model-id>Text in any language works whatever LANG or LC_ALL says (even LC_ALL=C): the prompt is read as UTF-8 and the answer is written as UTF-8. A prompt that is empty, is not valid UTF-8, or is over 256 KiB is refused with exit code 2 and a one-line reason: the prompt on stdin is empty., the prompt on stdin is not UTF-8. or the prompt on stdin is over 256 KiB.
--model answers with another model for this run only; nothing is written to your providers or the conversation.
A prompt and piped text#
When you give a prompt and pipe text in, both are used. The piped text follows the prompt, inside a <stdin> block:
git diff | ncode -p "review this change for bugs"sends your sentence, a blank line, then <stdin>, the diff and </stdin>. The prompt and the piped text together may be at most 256 KiB (the prompt and its piped stdin are over 256 KiB., exit code 2). Only a pipe or a file counts: a terminal, /dev/null or a socket is never read, so a script run from an idle terminal does not wait for input.
JSON output#
--json (the same as --output-format json) prints one JSON object at the end instead of the streamed answer:
| Field | Meaning |
|---|---|
conversation_id | the conversation the run belongs to |
run_id | the run |
state | how the run ended |
text | the answer |
error | what went wrong, if anything |
denied | the approvals that were denied because nobody could give them |
exit_code | the same code the command exits with |
text is the model's answer exactly, with any control characters JSON-escaped; the streamed text of a normal run has terminal control sequences removed. A run that cannot start (a usage mistake, a refused startup) also prints an object, with "state": "not_started", "conversation_id": null, "run_id": null, "text": "", the sentence in error, and the exit_code, so a script that parses stdout always gets JSON. The same sentence goes to stderr.
ncode -p "run the tests and fix what fails" --json | jq -r '.state, .text'Output formats#
--output-format picks the shape of stdout:
| Value | Prints |
|---|---|
text | the streamed answer (the default) |
json | the one object above; --json is the same |
stream-json | one JSON object per line as the run goes, ending with the --json object as {"type":"summary",…} |
Limits for a run#
--max-turns N(1 to 200) stops the run when its lead agent passes N turns: it endsstoppedwithncode: stopped after N turns.and exit code1.--max-budget-usd X(more than 0) does the same when the run's cost passes X dollars. If the provider reports no cost, the run is never stopped by it, and stderr says oncencode: the provider reports no cost; --max-budget-usd is not enforced.--approval read-only|auto|fullsets the approval mode for this run only. See below.
Continuing a conversation#
Add -c (--continue) to continue the project's latest conversation, or --resume <conversation-id> for a given one:
ncode -p "now add a test for the empty case" -c--resume takes a conversation id, any prefix of one that is at least 6 hex characters and names a single conversation, or an exact title; an ambiguous value exits 2 and lists up to five matches as id title. The id is in the JSON output and in the summary printed when you quit a session. In the full screen, --resume with no value opens the conversation picker.
Approvals and questions#
A headless run has nobody to ask, so the project's approval mode decides everything:
- whatever the mode allows runs;
- anything that would still need a person is denied: in a Read-only project that is every file write and every command;
- a question from an agent stops the run.
After the run, one line on stderr says what was denied and, for a Read-only project, how to allow it:
ncode: 2 tool call(s) were denied (approval mode read_only): <what>, <what>.
It names up to five calls, then and K more. The same calls are listed in denied of --json. A run that keeps hitting denials stops after 8. A tool call that a project hook or rule blocked counts as denied too.
A script that must not carry on when something was denied adds --fail-on-denied: a run that finished but had denials then exits 1 ("exit_code": 1 in --json). Without it the exit code is unchanged.
A new project is Read-only until you trust it, so in a project you have never opened, a headless run can read but not change anything, and says so on stderr instead of finishing silently. Open it once with ncode and type /trust first. From a script, ncode config set project.trusted on --project ~/dev/app does the same, once ncode has opened the folder at least once (a -p run counts); before that, config answers ncode has not opened <DIR> yet. Open it once (ncode <DIR>), then run this again.
To allow more for one run without changing the project, add --approval:
ncode -p "format the sources and run the tests" --approval autoThe mode lasts for this run only and is never saved. An untrusted project refuses auto and full with exit code 3.
Exit codes#
| Code | Meaning |
|---|---|
0 | the run finished |
1 | the run failed or was stopped, or (with --fail-on-denied) had denials |
2 | usage: a flag or value the command does not accept |
3 | startup refused: another session or the desktop app holds the database, no provider is set up, or the database is from an incompatible version; one line on stderr says which |
129, 143 | the process got SIGHUP or SIGTERM; the run was stopped and the session closed cleanly first |
A run that cannot start leaves no empty conversation behind. ncode config uses code 4 for "changed elsewhere" (see ncode config).
Usage mistakes are caught before anything starts: --json goes only with -p, -p and --plain do not go together, and -p needs a prompt that is not empty.
A script example#
#!/bin/sh
cd ~/dev/app || exit 1
if ncode -p "update CHANGELOG.md for the commits since the last tag" --json > run.json; then
jq -r .text run.json
else
code=$?
echo "the run did not finish (exit $code)" >&2
exit "$code"
fiNote The database is shared with the desktop app and with interactive sessions, so a headless run exits with code 3 while either of them is open. See Works with the desktop app.