Overview

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 monitor and control surface: budget usage, cost breakdowns, forecasts, provider health, agent runs, alerts, and the rules and channels behind them, 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, model and provider names, your own tags, and provider health, never a prompt or a response.

uv tool install solwyn-cli==0.3.0

See Installation for the verified v0.3.0 release, Python requirements, executable aliases and installation checks.

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_0123456789abcdef01234567 status
Field                                     Value
Project                             proj_0123456789abcdef01234567
Budget limit                               100.00
Current usage                               37.50
Remaining budget                            62.50
Budget period                   monthly (2026-07)
Budget mode                             hard_deny
Utilization                                37.50%
Provider health window                24h (fixed)
openai circuit                             closed
openai circuit source                    reported
openai success                  98 / 100 (98.00%)
openai latency                          245.50 ms
openai errors / failovers                   2 / 1
openai model failovers                          1
openai provider failovers                       0

Add --json before the command for a schema-bearing object instead of a table — see Scripting, which also lists the handful of commands that print plain text or stream raw bytes instead.

Commands

The CLI has three front doors: getting a machine set up, watching spend, and guarding spend the SDK does not see. Customers also manage their own account, subscription and team through the command reference. Core enforces owner, admin and member permissions.

Setup and identity

solwyn init is the guided path — it authenticates, selects a project, writes configuration, detects your providers, and verifies your budget in one pass. login and its siblings manage credentials, and doctor diagnoses a setup that misbehaves.

Monitoring

Read what a project has spent, where it is heading, and how its providers are behaving.

Budget guardrails

Calls made through the Solwyn SDK are already enforced and attributed. For everything else — a curl, another language, a coding agent's own tool call — solwyn budget provides the reserve → spend → settle loop, and solwyn record attributes a call that ran with no reservation. See Metering un-instrumented calls for the walkthrough.

Agent integration

Three commands exist for coding agents rather than humans. All run locally — agent-context and mcp-config need no credentials at all, and mcp resolves stored credentials only when a tool is invoked. See Agent integration and the mcp reference.

Account management

Customers manage their own account through alert rules, delivery activity, channels and routing, webhooks, keys, projects, account settings and recovery, team membership, invitations, tags, audit, attestations, subscription and billing, and local configuration. Each page states the credential, role, confirmation, exit-code and schema contract.

Global options

Every command accepts these root options, placed before the subcommand. Each falls back to an environment variable, then to a stored configuration value, where one exists.

The config, agent-context, and mcp commands accept these flags but ignore them. Credentials are never a flag. The CLI reads a project key from SOLWYN_API_KEY or the OS keychain, or a stored login — see Authentication, including what a key's full or read_only scope allows.

Next steps