SOLWYN

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.

Terminal
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.

Terminal
pipx install 'solwyn-cli>=0.5.1'
Terminal
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:

Terminal
uv tool install --python 3.11 'solwyn-cli>=0.5.1'
Terminal
pipx install --force 'solwyn-cli>=0.5.1'
Terminal
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.

Terminal
solwyn --version

Source 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:

Terminal, from the authorized solwyn-cli checkout
uv tool install --force --python 3.11 .
solwyn --help

Verify 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 0600 file, ~/.local/share/solwyn/credentials.json, on Linux. No keychain is needed on Linux, in containers or in CI, and SOLWYN_TOKEN and SOLWYN_API_KEY work 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, set SOLWYN_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:

Terminal
solwyn --version

It 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:

Terminal
solwyn --help

If both commands print without error, the CLI is installed correctly.

Log in through your browser, then run the diagnostics:

Terminal
solwyn login
Terminal
solwyn doctor

doctor 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.

PackageInstall commandWhat it does
solwyn-clipip install 'solwyn-cli>=0.5.1'Terminal client that talks to the Solwyn Cloud API.
solwynpip install solwynPython SDK that wraps your LLM provider client.

They have no dependency on each other — installing or upgrading one never pulls in the other.

Next steps

On this page