Non-interactive mode (veyyon --print)

Spec — not shipped: a veyyon exec subcommand. Non-interactive mode is the --print launch flag (short -p): veyyon -p "prompt". JSON output is --json, and resume is --resume / --continue. The veyyon exec resume / veyyon exec review subcommand forms and several flags (--output-schema, --oss) below are the target shape; run veyyon --help for the current flag set. The JSON event schema and the recipe shapes are accurate.

veyyon --print (short -p) runs Veyyon without the interactive cockpit: give it one prompt, it does the work and exits. It is how you drive Veyyon from scripts, CI, git hooks, and other programs.

$ veyyon -p "add a unit test for parse_config and run it"
$ echo "summarize the diff on this branch" | veyyon -p
$ veyyon -p - <<'EOF'
Review src/auth.rs for missing error handling.
EOF

The prompt can be an argument or read from stdin. If stdin is piped and a prompt argument is also provided, stdin is appended as a <stdin> block.

Run veyyon --help for the generated, always-current flag set. This page documents the intended integration surface and recipes.

Flag reference

Session and config

Model and local OSS

Sandbox and trust

Headless exec defaults approval policy to never (no TTY to answer). The sandbox is therefore your containment — set it explicitly in CI.

--full-auto is deprecated

--full-auto is a legacy compatibility trap. It still parses on veyyon --print, prints:

warning: `--full-auto` is deprecated; use `--sandbox workspace-write` instead.

and maps onto workspace-write sandbox behavior. Do not use it in new scripts:

# preferred
$ veyyon --print --sandbox workspace-write "run unit tests and fix failures"

# deprecated (warns)
$ veyyon --print --full-auto "run unit tests and fix failures"

Output

Combine them: --json for the full trace, --output-schema when you need a fixed answer shape, -o when you only care about the final text.

Subcommands

veyyon exec resume

Resume a previous session by id or pick the most recent.

$ veyyon exec resume <SESSION_ID> "continue from the failing test"
$ veyyon exec resume --last "try the next approach"
$ veyyon exec resume --last --all "…"        # do not filter sessions by cwd
$ veyyon exec resume --last -i shot.png "what is in this screenshot?"

veyyon exec review

Run a code review against the current repository (non-interactive).

$ veyyon exec review --uncommitted
$ veyyon exec review --base main
$ veyyon exec review --commit abcdef1 --title "fix auth timeout"
$ veyyon exec review "Focus on unsafe blocks and unwrap()"

For a richer interactive review workflow, see Review.

--json event schema

Events are JSON Lines (type tag). Top-level ThreadEvent variants:

Item payloads (item → type, snake_case) include:

Example lines:

{"type":"thread.started","thread_id":"01234567-89ab-cdef-0123-456789abcdef"}
{"type":"turn.started"}
{"type":"item.completed","item":{"id":"item_3","type":"file_change","changes":[{"path":"src/lib.rs","kind":"update"}],"status":"completed"}}
{"type":"item.completed","item":{"id":"item_4","type":"agent_message","text":"Done."}}
{"type":"turn.completed","usage":{"input_tokens":1200,"cached_input_tokens":800,"output_tokens":200,"reasoning_output_tokens":0}}

Pipe into jq:

$ veyyon --print --json "…" | tee run.jsonl \
    | jq -r 'select(.type=="item.completed" and .item.type=="agent_message") | .item.text'

Exit codes

veyyon --print follows the handbook exit code contract:

A failure is never reported as 0, so veyyon --print … && next-step is safe in a pipeline.

CI and automation recipes

1. Hermetic unit-test fix loop

$ veyyon --print --sandbox workspace-write \
    --ignore-user-config \
    --ephemeral \
    --skip-git-repo-check \
    -m gpt-5-mini \
    "Run cargo test -p mycrate. Fix compile and test failures only. Stop when green."

2. PR review bot with JSON artifact

$ veyyon exec review --base origin/main --json \
    | tee review.jsonl

$ jq -r 'select(.type=="item.completed" and .item.type=="agent_message") | .item.text' \
    review.jsonl > review.md

Or constrain the final message:

$ cat > /tmp/review-schema.json <<'EOF'
{
  "type": "object",
  "required": ["findings", "verdict"],
  "properties": {
    "verdict": { "enum": ["approve", "request_changes", "comment"] },
    "findings": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["severity", "path", "summary"],
        "properties": {
          "severity": { "enum": ["P0", "P1", "P2"] },
          "path": { "type": "string" },
          "summary": { "type": "string" }
        }
      }
    }
  }
}
EOF

$ veyyon --print --sandbox read-only --json \
    --output-schema /tmp/review-schema.json \
    -o review-out.json \
    "Review the staged diff; return JSON matching the schema."

3. Pre-commit hook (staged diff only)

#!/usr/bin/env bash
set -euo pipefail
veyyon --print --sandbox workspace-write --ephemeral --json \
  "Review the staged diff. Fail the turn if you find a P0 bug; otherwise summarize." \
  | tee /tmp/veyyon-pre-commit.jsonl \
  | jq -e 'select(.type=="turn.failed") | length == 0' >/dev/null

4. Batch refactor across a path

$ veyyon --print --sandbox workspace-write -C "$REPO" \
    --add-dir /tmp/veyyon-scratch \
    "Rename FooConfig -> AppConfig under src/config/. Update call sites. Run cargo check."

5. Resume a long CI job

$ THREAD=$(veyyon --print --json --ephemeral "start the migration plan" \
    | jq -r 'select(.type=="thread.started") | .thread_id')
# … later …
$ veyyon exec resume "$THREAD" "continue; finish applying the plan"

(Omit --ephemeral if you need the session on disk for resume.)

Safety notes for automation

• Prefer --sandbox workspace-write or read-only over bypass flags.
• Use --ignore-user-config / --ignore-rules when the runner’s home directory must not affect the job.
• --dangerously-bypass-approvals-and-sandbox is for outer jails only — prefer external-sandbox when you can express that cleanly (Sandbox).
• Never commit API keys into CI logs; use the runner secret store and env_key.

See also

• Sessions — resuming and branching.
• Sandbox and approvals — policies for CI.
• Exit codes
• ACP / SDK for programmatic control.
• CLI reference