Installation
Install the Solwyn CLI, check the version you have, and configure Python and MCP requirements.
The Solwyn CLI ships as the solwyn-cli package on PyPI. It is a standalone terminal client for the Solwyn Cloud API — a different package from the solwyn Python SDK, with no dependency between them.
Install
This is the CLI and MCP reference for solwyn-cli 0.5.1. 0.5.0 stores API keys per project and names the project with SOLWYN_PROJECT and the repository's .solwyn.env. 0.4.0 added browser login, approvals and CLI login management.
0.5.1 changes how the stored key reaches your app. Hand it to one command in a subshell, as keys env shows, and keys env prints JSON only when --json or --format json is on its own command line. If you set up a repository with 0.5.0, run solwyn init --agents again to replace its agent guidance, which told agents to run a bare eval.
CLI 0.4.x stored one sk_proj_ project key, which no longer works. 0.5.0 removes it on its first credential write; then run solwyn keys create --project <name> --store-key for each repository. See Upgrading from CLI 0.4.x.
CLI 0.3.0 and earlier log in with an email and password, and the API no longer accepts that. If you have one of them, see Upgrade from 0.3.0.
uv tool install --python 3.11 'solwyn-cli>=0.5.1'uv tool install puts the CLI on your PATH in its own isolated environment. uv tool dir --bin shows the executable directory.
pipx install 'solwyn-cli>=0.5.1'python -m pip install 'solwyn-cli>=0.5.1'Use a dedicated virtual environment when installing with pip.
Upgrade from 0.3.0
Earlier docs installed solwyn-cli==0.3.0, and later ones >=0.4.0. uv tool upgrade keeps that pin and leaves you on 0.3.0, and pipx install refuses to replace an installed package without --force. Install again with the new requirement, using the installer you used before:
uv tool install --python 3.11 'solwyn-cli>=0.5.1'pipx install --force 'solwyn-cli>=0.5.1'python -m pip install --upgrade 'solwyn-cli>=0.5.1'Then check that solwyn --version prints 0.5.1 or newer. If it doesn't, another solwyn earlier on your PATH is still the old one: command -v solwyn shows which.
Run solwyn login again: a 0.3.0 login no longer works, and 0.4.0 doesn't read it. A key stored by 0.3.0 isn't read either, and old sk_proj_ keys no longer work: create one with solwyn keys create --project <name> --store-key. solwyn logout deletes the old 0.3.0 entries. See Where credentials are stored.
solwyn --versionSource checkout
This reference was verified against the v0.5.1 release tag, commit 37bf38a86434ffdfe6cd4bf4d102674b300a662b. For development, you can also install from an authorized CLI checkout at that commit:
uv tool install --force --python 3.11 .
solwyn --helpVerify your installed version and help; MCP clients should inspect tools/list. This reference's inventory is 33 read tools / 37 guardrails tools.
MCP availability
MCP is included in solwyn-cli; no extra package or install extra is required. The CLI requires Python 3.11+ and pins mcp==2.1.1. Use an isolated installation to avoid conflicts with another MCP SDK version. The server is local stdio; there is no hosted MCP endpoint.
PyPI publication is separate from the unpublished MCP Registry draft. Its proposed ai.solwyn/solwyn namespace is unverified. A working local server or a valid descriptor does not establish Registry publication or namespace ownership. Use the installed executable and client setup.
Requirements
- Python 3.11 or newer. The package declares
requires-python >=3.11; older interpreters are refused at install time. Releases are tested on 3.11, 3.12, and 3.13, and the built package is smoke-tested on Linux, macOS, and Windows. - Somewhere to store credentials, which every platform has. The CLI keeps your login and API keys in the OS keychain on macOS and Windows, and in a private
0600file,~/.local/share/solwyn/credentials.json, on Linux. No keychain is needed on Linux, in containers or in CI, andSOLWYN_TOKENandSOLWYN_API_KEYwork with no store at all. On macOS and Windows the keychain must be usable where the CLI runs, since there is no fallback; on a CI runner or over SSH, setSOLWYN_CREDENTIAL_STORE=file. See Where credentials are stored for the tradeoffs.
The CLI pins one dependency exactly — the mcp package that backs solwyn mcp. Installing into an environment that already holds a different mcp version will conflict, which is one more reason to prefer uv tool install or pipx over a shared pip install.
Two names, one command
Installing exposes two entry points — solwyn and solwyn-cli. They resolve to the same program; use whichever reads better in your shell or scripts. This documentation uses solwyn.
No phone-home
The CLI does not report anything about you or your usage back to Solwyn. There is no telemetry, no update checks, and no phone-home — the only network traffic it originates is the API calls a command explicitly makes on your behalf, using credentials you supplied. It never collects provider keys, prompts, or responses.
Verify your installation
Confirm the version:
solwyn --versionIt prints solwyn and the version number. Browser login needs 0.4.0 or newer, and the API keys described here need 0.5.1 or newer.
List the available commands:
solwyn --helpIf both commands print without error, the CLI is installed correctly.
Log in through your browser, then run the diagnostics:
solwyn loginsolwyn doctordoctor checks the config file, the credential store, API readiness, your stored credential, and the bundled API snapshot, and exits 0 when everything passes.
Separate package from the SDK
The CLI and the SDK are distinct packages that do different jobs. You can install both in one environment.
| Package | Install command | What it does |
|---|---|---|
solwyn-cli | pip install 'solwyn-cli>=0.5.1' | Terminal client that talks to the Solwyn Cloud API. |
solwyn | pip install solwyn | Python SDK that wraps your LLM provider client. |
They have no dependency on each other — installing or upgrading one never pulls in the other.