Staso CLI reference
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 Staso 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 prodFlags
| Flag | Default | Description |
|---|---|---|
--target {claude-code,codex} | claude-code | Which CLI tool to configure. |
--api-key KEY | $STASO_API_KEY | Staso API key (ak_...). Required if no TTY. |
--base-url URL | https://api.staso.ai | Override backend URL. |
--workspace SLUG | default | Workspace slug for the traces. |
--environment ENV | default | Environment name (e.g. prod, staging). |
--agent-name NAME | — | Display name shown on the dashboard. |
--scope {global,project} | global | Write to user-level or project-level settings. |
--guard / --no-guard | --guard | Toggle Guard evaluation on tool calls. |
--auto-sync | off | Re-sync the hook config on every session start. |
What it does
Writes hook entries for every relevant event (PreToolUse, PostToolUse, Stop, etc.) into ~/.claude/settings.json for Claude Code or ~/.codex/hooks.json for Codex. For Codex, it also enables codex_hooks = true in ~/.codex/config.toml. Existing non-Staso hooks are preserved.
See Claude Code integration and Codex integration.
staso sync
Re-sync an already-installed hook config. Use this after upgrading the SDK or if hook events drift.
staso sync
staso sync --target claude-code
staso sync --enable-auto-syncFlags
| Flag | Default | Description |
|---|---|---|
--target {claude-code,codex} | all configured | Only sync one agent. |
--enable-auto-sync | off | Turn on auto-sync for the target. |
--disable-auto-sync | off | Turn off auto-sync for the target. |
What it does
Updates the Python interpreter path, migrates legacy env vars (e.g. STASO_AGENT_ID → STASO_AGENT_NAME), and adds any hook events introduced in newer SDK versions. Reports already up to date when nothing changes.
staso status
Print the current hook configuration for each configured agent.
staso status
staso status --target codexFlags
| Flag | Default | Description |
|---|---|---|
--target {claude-code,codex} | all agents | Only show one agent. |
What it does
Prints the SDK version, then for each agent: number of hook events registered, path to the settings file, and key env values (workspace, environment, guard, auto-sync). Unconfigured agents show as not configured.
staso update
Upgrade staso via pip, then run staso sync across every configured agent.
staso updateEquivalent to pip install --upgrade staso && staso sync. Fails loudly if pip cannot upgrade.
staso uninstall
Remove Staso hooks and state files.
staso uninstall
staso uninstall --target claude-codeFlags
| Flag | Default | Description |
|---|---|---|
--target {claude-code,codex} | all configured | Only uninstall one agent. |
What it does
Strips every Staso hook entry and STASO_* env var from the target settings file, preserving unrelated keys. For Codex, also removes the codex_hooks feature flag. Deletes state files under ~/.staso/<agent>/.
staso version
Print the installed SDK version and check PyPI for newer releases.
staso version
staso --versionIf a newer version exists, the output includes a pip install --upgrade staso hint.