CLI

The staso CLI installs and maintains trace hooks for Claude Code and Codex.

pip install staso
staso setup --target claude-code --api-key ak_...

Every subcommand accepts --help.

staso setup

Install hooks into a CLI agent's settings file. Without --api-key, launches an interactive wizard on a TTY.

staso setup --target claude-code --api-key ak_... --scope global
staso setup --target codex --api-key ak_... --workspace acme --environment prod

Flag	Default	Description
`--target {claude-code,codex}`	`claude-code`	Which CLI tool to configure.
`--api-key KEY`	`$STASO_API_KEY`	Required if no TTY.
`--base-url URL`	`https://api.staso.ai`	Override backend.
`--workspace SLUG`	`default`	Workspace slug.
`--environment ENV`	`default`	Environment name.
`--agent-name NAME`	—	Display name on the dashboard.
`--scope {global,project}`	`global`	User-level or project-level settings file.
`--guard` / `--no-guard`	`--guard`	Toggle Guard on tool calls.
`--auto-sync`	off	Re-sync hook config on every session start.

Writes hook entries for every relevant event into ~/.claude/settings.json (Claude Code) or ~/.codex/hooks.json (Codex). For Codex, also enables codex_hooks = true in ~/.codex/config.toml. Existing non-Staso hooks are preserved.

staso sync

Re-sync an installed hook config. Use after upgrading the SDK or if hook events drift.

staso sync
staso sync --target claude-code
staso sync --enable-auto-sync

Flag	Default	Description
`--target {claude-code,codex}`	all configured	Only sync one agent.
`--enable-auto-sync`	off	Turn on auto-sync.
`--disable-auto-sync`	off	Turn off auto-sync.

Updates the Python interpreter path, migrates legacy env vars, and adds new hook events from newer SDK versions. Reports already up to date when nothing changes.

staso status

staso status
staso status --target codex

Prints the SDK version, then for each agent: hook events registered, settings file path, and key env values. Unconfigured agents show as not configured.

staso update

staso update

Equivalent to pip install --upgrade staso && staso sync.

staso uninstall

staso uninstall
staso uninstall --target claude-code

Strips every Staso hook entry and STASO_* env var from the target settings file. For Codex, also removes the codex_hooks flag. Deletes state under ~/.staso/<agent>/.

staso version

staso version
staso --version

Prints the installed SDK version and checks PyPI for newer releases.

CLI