CodeNeterHeadless use
Run a single prompt from scripts or other tools with codeneter run, read text or JSON output, and control approvals.
codeneter run sends one prompt, lets the agent work until it's done, and exits without opening the interactive interface. Use it in scripts and other automation on a machine where you've signed in with codeneter login.
Run a prompt
Pass the prompt with --prompt, or -p:
codeneter run --mode ask --prompt "List the main modules in this project and what each one does"Without --prompt, the CLI reads the prompt from standard input:
codeneter run < task.mdSaved commands work too, with any extra text after them:
codeneter run --prompt "/review-branch focus on the authentication changes"--mode, --model, and --workspace work as they do in interactive sessions.
Output and exit codes
--output-format sets what the run prints to standard output:
| Format | Output |
|---|---|
text | The agent's reply as plain text, streamed as it's written. This is the default. |
json | One JSON object when the run finishes. --json does the same. |
stream-json | One JSON event per line while the run is in progress |
--json can't be combined with a different --output-format.
The json object includes:
| Field | Contents |
|---|---|
ok | true if the run finished without an error or usage limit |
response | The agent's final reply |
model | The selected model, or auto when Auto is selected |
error | Error message, if the run failed |
limit | Details of the usage limit, if one was reached |
sessionId | ID of the saved session, for --resume |
The exit code is 0 when the run finishes and 1 when it fails or reaches a usage limit. With json and stream-json, a run that fails partway still prints its result, with ok set to false. With text, the error message goes to standard error.
Problems that stop a run before it starts, such as not being signed in, a missing prompt, or an unknown conversation ID, are printed to standard error with exit code 1. In that case json prints nothing to standard output. stream-json still prints a closing result event with ok set to false, unless the options themselves are invalid.
Stream events
With stream-json, each line of standard output is one JSON object with a type:
| Event | Fields | Meaning |
|---|---|---|
init | sessionId, resumed, workspaceRoot, model, mode | The run has started and the conversation is saved |
assistant_delta | text | Part of the reply, as it's written |
assistant_message | text | A completed assistant message |
tool_start | toolCallId, tool, args | The agent called a tool |
tool_result | toolCallId, tool, ok, result, error | The tool call finished. error is present when ok is false. |
retry_reset | None | The request is being retried |
result | The same fields as the json object | The run is over. Always the last line. |
An assistant_message can repeat text already received as deltas. Use deltas for live display or completed messages, rather than appending both. After retry_reset, discard the deltas received since the last assistant_message. Read the outcome from result, not from the events before it.
Continue a conversation
Headless runs save their conversation history. --resume <sessionId> sends the next prompt to a saved conversation, with its earlier messages as context. Replace SESSION_ID below with the sessionId from the first run's result:
codeneter run --json --prompt "Summarize the test coverage in this project"
codeneter run --resume "SESSION_ID" --prompt "Which gaps should I address first?"The ID also appears in the init event of stream-json. Text output doesn't print it. Interactive sessions use the same saved conversations, so the ID also works with codeneter --resume.
A resumed run works in the conversation's saved folder, with its saved model and mode. --model and --mode override the saved values. --workspace isn't needed, and a run is refused if it points to a different folder. An unknown ID is an error, not a new conversation.
Run one prompt at a time on a conversation. Runs that write to the same conversation at once aren't coordinated.
Approvals
A headless run can't stop to ask for approval. Unless auto-approval is on, actions that need approval are refused, and the agent continues without them: terminal commands other than the few exempt inspection commands, file deletions, and MCP tool calls when confirmMcp is on. File edits don't need approval, so they go ahead in every mode. Ask and Plan guide the agent; they don't block changes.
--auto, or autoApprove: true in your configuration, approves these actions without asking. Resuming a conversation that had /yolo on doesn't turn auto-approval on. Plan mode still can't ask clarifying questions in a headless run.
With auto-approval on, the agent can run commands and delete files without asking. Keep a recoverable copy of your work. Commands can also affect files and services outside the project.
Trusted folders
Project rules, skills, and MCP servers load only in folders you've trusted. If a headless run should use them, open the folder once in an interactive session and trust it.