Print, JSON and RPC modes
Run venom without the TUI, in scripts, CI and other programs, with one printed answer, a JSON event stream or an RPC loop, plus piped stdin, approvals and --json output from subcommands.
venom runs the same agent without a terminal UI in three ways:
| Mode | Flag | Output |
|---|---|---|
-p, --print |
The final answer as text on stdout, then exit. | |
| JSON | --mode json |
Every event as one JSON line on stdout, then exit. |
| RPC | --mode rpc |
Reads JSON commands on stdin and writes responses and events on stdout until shut down. |
When stdin or stdout is not a terminal and no --mode is given, venom uses print mode.
venom -p "summarise the README" # one answer on stdout
cat notes.md | venom -p "summarise" # piped stdin goes before the prompt
git diff | venom -p - "review this" # '-': the prompt (or its first part) is on stdin
venom -p /context # a slash command's output on stdout
venom --mode json /cost # JSON events, plus {"type":"notice",...} lines
venom -p --permission-mode accept-edits "fix the lint errors in src/"For a long-lived integration over HTTP, venom serve exposes the same sessions with Server-Sent Events (the server API section of these docs); venom acp speaks the Agent Client Protocol for editors.
Piped stdin
When stdin is not a terminal, venom waits 150 ms for its first byte. If data arrives, it reads to the end and puts it before the prompt; if not, it goes on without stdin, so a pipe nobody closes (a CI runner, another agent's harness) never makes venom -p hang. A - among the prompt arguments means the prompt is on stdin: venom then waits for the end of stdin however long it takes. Use - for a slow producer. RPC mode never reads stdin as a prompt; stdin is its protocol.
Permissions without a terminal
There is nobody to answer a prompt, so an action that would ask is denied, and the model is told which allow rule would let it run. Pick the mode the job needs (--permission-mode accept-edits, --yolo) or add allow rules for the commands it runs. In plan mode the plan cannot be approved, so the run ends with the plan written. The project's hooks, MCP servers and allow rules load only if the project is trusted (venom trust --yes, or --approve for one run).
Slash commands and notices
Slash commands that report something (/context, /cost, /usage, /undo, /redo, /checkpoints, /routes, /init and others) print their report: as text in print mode, as {"type":"notice","level":"info","message":"…"} lines in JSON mode. In print mode, warnings and errors (project config ignored as untrusted, a blocked sandbox host) go to stderr, so venom -p … > answer.txt keeps only the answer.
Sounds, the HUD, the meter and the other TUI parts are off in these modes; hooks still run.
The JSON event stream
--mode json writes pi's events as JSON lines: the session header, each message start and end, tool calls with their arguments and results, and the end of the run, plus venom's notice lines. Each line is one JSON object with a type. Reserve stdout for the stream: anything else venom has to say goes to stderr.
--json on subcommands
Every subcommand that prints a result takes --json and prints one JSON document on stdout; progress and diagnostics stay on stderr. Newer commands share one shape:
{"ok":true,"...":"command-specific fields"}
{"ok":false,"error":{"code":"session_not_found","message":"no session matches abc"}}The exit code is the same with or without --json: 0 success, 1 failure, 2 usage error. Some older commands (venom cost, venom usage, venom routes, venom review, venom triage) print their own documented objects, named by a type or object field.
In CI
export VENOM_BASE_URL=https://cloud.usevenom.dev/v1
export VENOM_API_KEY=vck_…
venom doctor --json --only environment,orchestrator
venom -p --permission-mode accept-edits --output-budget 30000 \
"run the tests, fix what fails, and summarise the changes" > summary.mdUse --no-session if the job should leave no session file behind, and --offline to keep the run from fetching web pages or starting MCP servers.
Troubleshooting
| Symptom | Cause and fix |
|---|---|
| The prompt from a pipe was ignored | The producer started writing after 150 ms. Add - as a prompt argument. |
| The run stops with a denied action | Nobody could approve it. Use a wider --permission-mode, or an allow rule for that command. |
| Project hooks or MCP servers didn't load | The project isn't trusted: venom trust --yes, or --approve for one run. |
| Extra text in a captured answer | It came from stderr; redirect only stdout (> answer.txt). |