CLI

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

Setup

staso setup --target claude-code --api-key ak_...
staso setup --target codex --api-key ak_...

Use --scope global for user settings or --scope project for project settings. The API key is stored in ~/.staso/credentials.json; target settings contain a credential reference. Treat that file as a plaintext secret.

Codex requires you to review and trust the generated commands in Settings -> Hooks.

Setup validates the API key, active plan, workspace access, trace capability, and optional Guard capability through a read-only backend check. It does not create a synthetic trace. When no real event has arrived yet, setup reports First ingestion: pending first real agent event.

When Guard is enabled, setup validates the key's guard:evaluate capability. Both Claude Code and Codex evaluate tool proposals during PreToolUse. A matching configured audit policy records a would-block finding and allows the proposal. A matching configured Enforce policy can block it before execution. Built-in templates remain inactive until attached to a policy. Use --no-guard to skip the Guard check during setup.

Existing JSON, TOML, and credential files must parse before setup changes anything. Setup stages and reparses every local change, then creates non-overwriting sibling backups named <file>.staso-backup-<UTC timestamp>. If a replacement, credential write, or final verification fails, setup restores the exact previous files and credential bytes.

A successful run reports these checks separately:

• Backend/key/workspace: validated
• Local configuration: verified
• Hook installation: verified
• Provider SDK patch: not applicable (CLI hook setup)
• First ingestion: observed or pending first real agent event

Maintenance

staso status
staso sync
staso update
staso uninstall
staso version

Run a command with --help for the current flags. Existing non-Staso hook entries are preserved during setup and sync.