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

ncode -p - < review-request.md
git diff | ncode -p - --model Anthropic/<model-id>

--model answers with another model for this run only; nothing is written to your providers or the conversation.

JSON output#

--json prints one JSON object at the end instead of the streamed answer:

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

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 needs the whole conversation id; the id is in the JSON output and in the summary printed when you quit a session.

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, and a line on stderr says what (in full access, the line says that nothing asks);
• a question from an agent stops the run.

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. 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 that the folder is not a project yet.

Exit codes#

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"
fi