Command-line interface reference

This page documents the Osprey 0.1.0 command-line interface (CLI). The audited source commit is 01dabf2fedd1826362162ead9757232e89d9bfa5.

Command map

Command	Purpose
osprey	Start the terminal user interface (TUI).
osprey agent	Run one headless agent task.
osprey setup	Configure storage, provider selection, and the default model.
osprey session	List, inspect, fork, switch, or delete sessions.
osprey process	Inspect or terminate preserved background process groups.
osprey completions	Write a shell completion script to standard output.
osprey extensions	Report extension layers, trust, and shadowing.
osprey help [COMMAND]	Print help for the root or a nested command.

Osprey has no installed optimize command. The optimization utility is a source-only Make target.

A successful command exits with status 0. An ordinary command failure exits with status 1. An argument parsing failure exits with status 2. An interrupt at the command boundary exits with status 130.

Root invocation

Run osprey without a subcommand to start the TUI.

Option	Input and default	Behavior
--verbose	Boolean, default false	Use debug-level logging. The option is global.
--yolo	Boolean, default false	Select the never approval policy. Native isolation still requires --sandbox.
--read-only	Boolean, default false	Approve trusted read-only tools and prompt for other tools.
--approval POLICY	Default on-request	Select never, on-request, on-failure, unless-trusted, or deny-untrusted.
--sandbox	Boolean, default false	Route tool calls through the platform isolation sidecar.
--max-turns COUNT	Default from config, otherwise unlimited	Require an integer of 1 or greater.
--effort LEVEL	Default from provider config	Select none, minimal, low, medium, high, xhigh, or max.
--ultracode	Boolean, default false	Prefer workflow authoring and request xhigh reasoning. Explicit --effort wins.
-h, --help	No input	Print help and exit.
-V, --version	No input	Print the package version and exit.

--yolo, --read-only, and --approval are mutually exclusive. Unsandboxed --yolo treats the environment as externally isolated. Osprey also prints a warning. Tools still run. Osprey blocks catastrophic Bash command shapes under every approval policy.

Place TUI launch options after osprey in an invocation with no subcommand. Place headless launch options after agent. Osprey rejects ambiguous root launch options before a subcommand. Only global --verbose works at every command level.

Headless agent

osprey agent requires one positional task prompt. The prompt can start with a hyphen.

TASK_PROMPT="Inspect the repository and report the test commands. Do not edit files."
osprey agent "$TASK_PROMPT"

Headless mode uses deny-untrusted approval by default. Trusted read-only tools run under that policy. Other tool calls return a denial result.

Persona and model options

Option	Default	Behavior and failures
--persona NAME	[agent].default_persona, then default	Load a project, user, or bundled persona. An unknown persona stops startup.
--toolset NAME	Persona toolset, then unrestricted inventory	Select a layered toolset. An unknown name stops startup and lists available sets.
--model MODEL	OSPREY_MODEL, provider config, then provider default	Select the action model.
--temperature NUMBER	OSPREY_TEMPERATURE, provider config, then provider default	Require a finite number. Anthropic omits the setting from requests.
--var KEY=VALUE	No variables	Add a persona template variable. Repeat the option for more variables.
--skill NAME	No forced skills	Load a discovered skill at startup. Repeat the option for more skills.
--skill-dir PATH	OSPREY_SKILL_DIR, then no extra path	Add a skill root. Repeat the CLI option for more roots.

--var rejects an empty key or a value without =. An unknown forced skill stops startup and lists available skills.

Execution and approval options

Option	Default	Behavior and failures
--yolo	False	Select never. Use --sandbox when Osprey must provide isolation.
--read-only	False	Run trusted read-only tools and deny other tools without a prompt.
--approval POLICY	deny-untrusted	Select an explicit approval policy.
--sandbox	False	Use Seatbelt on macOS or Landlock with seccomp on Linux.
--allowed-root PATH	Current directory only	Add a filesystem root. Repeat the option for more roots.
--immutable-runtime-surface	False	Reject prompt and tool-surface reloads after startup.

Osprey logs an allowed root that cannot be canonicalized. It skips that root. --sandbox fails when the platform cannot provide authoritative isolation. Linux sandboxing does not restrict network egress.

Headless on-request, on-failure, and unless-trusted policies fail before the task starts. Those policies require an interactive approver. Use deny-untrusted or --read-only for a restricted headless run.

Turn and retry options

Option	Default	Behavior and failures
--max-turns COUNT	150	Require an integer of 1 or greater.
--turn-timeout SECONDS	300	Set the wall-clock limit for one model turn. Require 1 or greater.
--stream-idle-timeout-secs SECONDS	60	Retry after no streaming delta. CLI zero is invalid.
--streaming-timeout-secs SECONDS	No transport timeout	Set the provider read timeout. Require 1 or greater.
--empty-completion-threshold COUNT	2	Fail after consecutive empty completions. Require 1 or greater.
--driver-max-retries COUNT	3	Set retries after a retryable driver error. Zero disables retries.
--retry-failure-threshold COUNT	2	Annotate repeated identical failures. Zero disables the signal.
--no-progress-family-threshold COUNT	3	Detect repeated failure families. Zero disables the signal.
--no-progress-family-window COUNT	10	Retain recent failure-family observations. Zero disables the signal.
--no-progress-artifact-threshold COUNT	10	Detect unchanged artifacts. Zero disables the signal.
--no-progress-suppression-window COUNT	30	Suppress a repeated no-progress signature. Zero disables suppression.
--max-subagents COUNT	8	Limit concurrent spawned children.
--llm-rpm COUNT	No limit	Limit model requests per minute across the parent and spawned children. Require 1 or greater.

OSPREY_TURN_TIMEOUT has lower priority than --turn-timeout. OSPREY_AGENT_TIMEOUT_SEC can limit the complete headless session. Neither variable adds a CLI option.

Tool-result options

Agent Trajectory Interchange Format (ATIF) is the trajectory output format.

Option	Default	Behavior
--compress-context[=BOOLEAN]	False	Compress large non-streaming results before context insertion.
--compress-min-bytes BYTES	2048	Set the minimum result size for compression.
--tool-result-cap BYTES	32768	Limit each result. Zero disables the byte cap.
--tool-result-head BYTES	12288	Retain bytes from the start of a truncated result.
--tool-result-tail BYTES	12288	Retain bytes from the end of a truncated result.
--tool-result-max-lines COUNT	0	Limit result lines. Zero disables the line cap.
--tool-result-raw-dir PATH	No directory. An ATIF output adds a sibling raw/ directory.	Store full truncated results in sidecar files. Headless mode ignores [tool_results].sidecar_dir for this purpose.

Without a raw directory or ATIF path, Osprey caps results without writing sidecar files.

The bash tool also accepts a per-call timeout. Its precedence is per-call timeout, then OSPREY_BASH_TIMEOUT, then 300 seconds. Osprey clamps the effective Bash timeout to 3600 seconds.

Output and session options

JavaScript Object Notation (JSON) is the structured output format. JSON Lines (JSONL) stores one JSON value per line.

Option	Default	Behavior and failures
--atif-output PATH	No trajectory file	Write the ATIF trajectory to the selected path.
--atif-system-prompt-plaintext[=BOOLEAN]	Digest only	Include the rendered system prompt text in ATIF metadata.
--events-jsonl	Automatic for nonterminal output	Force JSON Lines event output.
--resume SESSION_ID	New session	Append new turns to an existing session.
--fork-from SESSION_ID	New session	Create a branch from an existing session.
--output-schema PATH	No schema	Validate the final output against a JSON Schema file.
--effort LEVEL	Provider config	Override reasoning effort. Unsupported levels clamp to the model maximum.
--ultracode	False	Prefer workflow authoring and request xhigh effort. Explicit effort wins.

JSONL mode writes lifecycle events and a final session_end object to standard output. --resume and --fork-from are mutually exclusive. Both options use the configured session database.

An unusable tool-result sidecar directory stops startup. An ATIF write failure produces a warning and does not replace the task result.

Osprey reads and validates an output schema before it contacts a provider. The provider receives the schema with non-strict handling. Osprey performs the authoritative validation on the final text. Invalid final JSON or a schema mismatch fails the run.

Setup command

osprey setup has no command-specific options. Global --verbose remains available.

The command can read a remote model catalog. The command writes $OSPREY_HOME/config.toml with Unix mode 0600. The wizard preserves unrelated valid configuration keys and comments.

The wizard prompts for SQLite or PostgreSQL. It also prompts for a default model. The wizard detects provider keys in the environment. The wizard never prompts for or stores a provider key.

A failed database test does not prevent the configuration write. Correct database_url. Then run the command again. A malformed existing file prevents setup from overwriting the file.

Session commands

Session commands operate on sessions for the current working directory. Universally Unique Identifier (UUID) is the complete session identifier format. Each query accepts a session identifier, a UUID prefix, or a branch label.

Command	Inputs	Output or side effect
osprey session list	None	Print sessions for the current directory.
osprey session tree	None	Print the branch tree for the current directory.
osprey session fork QUERY --at SEQUENCE	Query and signed sequence number	Create a branch at the selected turn.
osprey session switch QUERY	Query	Mark the selected session active for the current directory.
osprey session delete QUERY	Query and confirmation input	Soft-delete a non-active session after full UUID confirmation.

Successful session commands exit with status 0. An unsuccessful operation exits with status 1. A canceled delete exits with status 130.

If a query matches no session, use session list to find an identifier. If a short prefix is ambiguous, use the complete UUID.

Process commands

Osprey records preserved process groups under $OSPREY_HOME/processes. The process commands verify process identity before they send a termination signal.

Command	Inputs	Output
osprey process list	Optional --json	Print a table or a stable JSON object.
osprey process terminate ID	Identifier and optional --json	Print terminated, already_exited, or a failure state.
osprey process clean	Optional --json	Print one result for each registry record.

process terminate sends a signal to one verified process group. The command removes the record after termination or confirmed exit.

process clean attempts to terminate every group in one registry snapshot. The command can terminate some groups before another record fails. Failed, unverifiable, or identity-mismatched records produce a nonzero result.

Use --json for automation. Human output uses tab-separated rows.

Completion scripts

osprey completions SHELL accepts bash, elvish, fish, powershell, or zsh. The command writes the completion script to standard output. The command does not modify a shell profile.

The next command changes only the current Bash process.

eval "$(osprey completions bash)"

Extension report

osprey extensions inspects extension artifacts visible from the current directory. The default output is a table. Use --json for a JSON report.

The report includes layer provenance, shadowing, trust state, and the workspace boundary. The command does not activate or modify an extension.

Operational sidecar

agent-runner is installed beside osprey. Osprey starts the sidecar when --sandbox is active. Users do not normally start agent-runner directly.

Option	Default	Behavior
--workspace PATH	Required	Select the workspace root.
--port PORT	0	Bind an operating-system-selected port. OSPREY_AGENT_RUNNER_PORT overrides the option.
--bind ADDRESS	Internet Protocol version 6 (IPv6) loopback plus resolved port	Override the complete bind address. AGENT_RUNNER_BIND supplies the value.
--confine MODE	none	Select none or Linux-only landlock.
-h, --help	No input	Print help and exit.
-V, --version	No input	Print osprey-sandbox 0.1.0 and exit.

An explicit bind address has priority over every port setting. --confine landlock fails on a non-Linux host.

Back to Osprey