Overview
The Solwyn CLI — budget guardrails for coding agents and cost monitoring for humans, straight from the terminal.
The Solwyn CLI does two jobs. For coding agents, it is a pre-flight guardrail: an agent reserves budget before an un-instrumented provider call and settles it afterward, so autonomous spend stays inside a limit you set. For humans, it is a read-only monitor: budget usage, cost breakdowns, and provider health for any project, in your shell.
It is a standalone tool that talks to the Solwyn Cloud API — it does not import or depend on the Python SDK, and it never sits in the path of your LLM calls. Like the rest of Solwyn, it moves quantities and selectors, never content: budget dollars, token counts, and provider health, never a prompt or a response.
pip install solwyn-cliSee Installation for uv, requirements, and verification.
A first look
solwyn status renders one project's budget and per-provider health as a flat Field / Value table. Numbers below are illustrative.
$ solwyn --project proj_abc12345 status
Field Value
Project proj_abc12345
Budget limit 100.00
Current usage 23.47
Remaining budget 76.53
Budget period monthly (2026-07)
Budget mode alert_only
Utilization 23.47%
openai circuit closed
openai success 1202 / 1204 (99.83%)
openai latency 342.10 ms
openai errors / failovers 2 / 0
anthropic circuit closed
anthropic success 387 / 387 (100.00%)
anthropic latency 518.40 ms
anthropic errors / failovers 0 / 0Add --json to any command for a schema-bearing object instead of a table — see Scripting.
Commands
Setup and identity
Get a machine configured and confirm who it is acting as. solwyn init is the guided path; login and its siblings manage credentials.
| Command | Purpose |
|---|---|
solwyn init | Configure Solwyn safely for the current repository. |
solwyn login | Authenticate with Solwyn. |
solwyn logout | Clear all stored Solwyn credentials. |
solwyn whoami | Show the current Solwyn identity and project context. |
Monitoring
Read what a project has spent and how its providers are behaving. See status and costs.
| Command | Purpose |
|---|---|
solwyn status | Show project budget and provider health. |
solwyn costs | Show aggregate project costs. |
Budget guardrails
solwyn budget inspects budgets and runs pre-flight guardrail checks. Poll with status, check immediately before un-instrumented spend, and confirm only a non-null reservation. Full reference: budget.
| Command | Purpose |
|---|---|
solwyn budget status | Read current project budget status without authorizing spend. |
solwyn budget check | Reserve budget immediately before one un-instrumented provider call. |
solwyn budget confirm | Settle one reservation after an un-instrumented provider call. |
solwyn budget set | Update selected budget settings while preserving all other configuration. |
Keys
solwyn keys helps you recover from leaked or expired project keys — metadata and rotation only, never revealing existing key material. Full reference: keys.
| Command | Purpose |
|---|---|
solwyn keys show | Show active project-key metadata without revealing key material. |
solwyn keys rotate | Rotate the active key and reveal its replacement exactly once. |
solwyn keys revoke | Hard-revoke a project key without minting a replacement. |
Projects
solwyn projects inspects the projects your account can see and creates new ones. Full reference: projects.
| Command | Purpose |
|---|---|
solwyn projects list | List projects available to the logged-in user. |
solwyn projects create | Create a project and capture its first API key exactly once. |
solwyn projects show | Show the project selected by the global project context. |
Configuration
solwyn config inspects and updates local configuration — an allowlisted set of keys, stored on your machine. Full reference: config.
| Command | Purpose |
|---|---|
solwyn config list | Print every allowlisted configuration value in deterministic order. |
solwyn config get | Print one configuration value. |
solwyn config set | Validate and persist one configuration value. |
Agent integration
Two commands exist for coding agents rather than humans. Both run locally — agent-context needs no credentials at all, and mcp resolves stored credentials only when a tool is invoked. See Agents.
| Command | Purpose |
|---|---|
solwyn agent-context | Print safe Solwyn budget guidance for coding agents. |
solwyn mcp | Serve Solwyn tools over local MCP stdio. |
Global options
Every command accepts these root options. Each falls back to an environment variable, then to a stored configuration value, where one exists.
| Flag | Env var | Config key | Description |
|---|---|---|---|
--version | — | — | Show the installed version and exit. |
--project, -p | SOLWYN_PROJECT_ID | default_project | Project ID for this invocation. |
--api-url | SOLWYN_API_URL | api_url | Solwyn API base URL. |
--format | SOLWYN_FORMAT | format | Output format: table (default) or json. |
--json | — | — | Emit schema-bearing JSON output. |
--no-color | NO_COLOR | — | Disable terminal color. |
Credentials are never a flag. The CLI reads a project key from SOLWYN_API_KEY or the OS keychain — see Authentication.