ncode

CLI docs Headless runs

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#

sh
ncode -p "summarise the open TODOs in lib/" > todos.md

The 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:

sh
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:

sh
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:

FieldMeaning
conversation_idthe conversation the run belongs to
run_idthe run
statehow the run ended
textthe answer
errorwhat went wrong, if anything
deniedthe approvals that were denied because nobody could give them
exit_codethe 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.

sh
ncode -p "run the tests and fix what fails" --json | jq -r '.state, .text'

Output formats#

--output-format picks the shape of stdout:

ValuePrints
textthe streamed answer (the default)
jsonthe one object above; --json is the same
stream-jsonone 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 ends stopped with ncode: stopped after N turns. and exit code 1.
  • --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 once ncode: the provider reports no cost; --max-budget-usd is not enforced.
  • --approval read-only|auto|full sets 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:

sh
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:

sh
ncode -p "format the sources and run the tests" --approval auto

The mode lasts for this run only and is never saved. An untrusted project refuses auto and full with exit code 3.

Exit codes#

CodeMeaning
0the run finished
1the run failed or was stopped, or (with --fail-on-denied) had denials
2usage: a flag or value the command does not accept
3startup 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, 143the 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#

sh
#!/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"
fi

Note 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.