CLI & Configuration

The SteerPlane SDK ships with a CLI (built on Click) for inspecting runs, managing API keys, and streaming telemetry from the terminal.

pip install "steerplane[cli]"
steerplane --version

Health check

steerplane status   # confirms the API server is reachable and reports its version

Runs

steerplane runs list                      # recent runs
steerplane runs list --limit 50 --status running
steerplane runs inspect <run_id>          # steps, cost, and status for one run
steerplane runs kill <run_id> --reason "manual stop"

API keys

steerplane keys list
steerplane keys create --name "prod-bot" --max-cost 100 --max-rpm 60
steerplane keys revoke <key_id>

Live telemetry

steerplane logs            # recent telemetry events
steerplane logs --tail     # continuously poll for new events
steerplane logs --tail --interval 2

Configuration file

Project-level defaults live in a .steerplane.yml at your repo root. Values merge with decorator arguments and environment variables.

# .steerplane.yml
api_url: http://localhost:8000   # your SteerPlane API (self-hosted)
agent_name: support_bot

defaults:
  max_cost_usd: 10.0
  max_steps: 50
  enforcement: alert
  loop_window_size: 8
  model: gpt-4o

policy:
  denied_actions: ["delete_*", "drop_*"]
  allowed_actions: ["search_*", "read_*"]
  require_approval: ["refund_*"]

alerts:
  email: ops@example.com
  webhook_url: https://hooks.slack.com/services/...
  threshold: 0.8
  timeout_sec: 1800

Programmatic configuration

For connection settings (as opposed to per-run guardrail limits), configure() sets the global SDK config in code instead of via environment variables or a YAML file:

from steerplane import configure, get_config

configure(api_url="https://api.mycompany.com", api_key="sk_sp_...", agent_id="support_bot")

config = get_config()
print(config.api_url)

Environment variables

Variable	Purpose
`STEERPLANE_API_URL`	Control-plane base URL (defaults to `http://localhost:8000`).
`STEERPLANE_API_KEY`	API key used by the SDK and CLI.
`STEERPLANE_AGENT_ID`	Default agent identifier if none is passed explicitly.
`STEERPLANE_CONFIG`	Explicit path to a `.steerplane.yml`/`.yaml` file, overriding auto-discovery.

Two separate resolution chains: connection settings (api_url, api_key, agent_id) follow configure() → environment variables → built-in default. Per-run guardrail limits (max_cost_usd, max_steps, policy rules, etc.) follow decorator/constructor arguments → .steerplane.yml → built-in default — environment variables do not override these directly.