ncode CLI Automation
Plain mode (experimental)
Plain mode drives a saved session one line at a time: you write commands on standard input, and it writes what happens as plain, append-only lines on standard output. It is meant for pipes, SSH sessions, CI logs and terminals where the full-screen view cannot draw.
Note Plain mode is experimental in 0.3.0. Its commands and output may change; for scripts, prefer headless runs (ncode -p), whose --json output is one documented object.
When it is used#
ncode --plainstarts it on purpose.- It is chosen by itself when standard input or standard output is not a terminal, or
TERMisdumb.ncodethen says so on stderr:not a terminal, so the plain presenter answers (--plain).
It opens the same saved conversation the full screen would: the project's latest, unless you add --new or --resume <conversation-id>. A conversation's earlier turns are printed once at the start, not twice. A consumer that reads output slowly (a pager, a slow SSH link) is waited for, up to 30 seconds per batch; a closed pipe ends the session at once. --fail-on-denied makes the session exit 1 if any approval was denied during it. The ! shell escape and the full screen's keys are not part of plain mode; a leading ! is ordinary text.
Commands#
One command per line. help prints the list with its arguments.
| Command | Does |
|---|---|
send -- <text> | send a message; send -- /swarm … sends a slash command |
queue -- <text> | queue a message behind the running turn |
answer <id>@<rev> <option> | answer a waiting question |
approve, deny, deny-stop, approve-run, always-allow, always-prefix <id>@<rev> | answer a waiting approval: allow once, deny, deny and stop the run, allow for the run, or always allow (always-prefix for a command family). A card that does not offer a verb refuses it; a Read-only card offers only approve, deny and deny-stop |
pause <run> / continue <run> | pause or continue a run |
stop <run> | stop a run |
retry <run>@<rev> | retry a failed run |
stop-agent <run> <agent>@<rev> | stop one agent |
go conversation <id> | switch to another conversation |
activity | the activity view |
inspect <run> [overview|agents|timeline|changes] | one view of a run |
detail <ref>, detail next, detail retry | the full text of an item |
back | back from a detail view |
detach | leave the session |
help | the command list |
Holding stdin open#
The session ends when standard input ends, but it first waits for the turn it started and for every queued message to finish, for up to 10 minutes. A command list that ends right after send therefore still prints the answer. If a run is waiting for an approval when input ends, the session says ncode: the run was waiting for an approval and was stopped when input ended. Answer it before closing stdin (approve or deny), or allow it with /approval auto, then rerun. A message that was refused, or a queued prompt that failed to send, makes the exit code 1. Keep stdin open for as long as you want to see output, or end the list with detach once you have what you need:
printf 'send -- inspect this project\ndetach\n' | ncode --plain{ echo 'send -- list the failing tests'; sleep 120; echo detach; } | ncode --plainNDJSON output#
--ndjson (only with --plain) prints one JSON object per output record instead of text lines:
ncode --plain --ndjson < commands.txt > session.ndjsonThe record format is not documented yet and may change between releases.
