init
One command that logs in, selects or creates the repository's project, writes .solwyn.env, detects your providers, and verifies your budget end to end
solwyn init takes a repository from nothing to a working, budget-verified setup in one pass. It resolves a credential, picks or creates the repository's project, writes .solwyn.env, detects which provider SDKs your code imports, prints the exact wiring for each, and confirms the whole chain by reading your budget back from Solwyn Cloud. It never asks for or stores a provider API key. The wiring it prints reads each provider key from its environment variable, such as OPENAI_API_KEY.
solwyn init [--agents] [--run-cap <usd>] [--budget <usd>] [--period daily|weekly|monthly] [--mode alert_only|hard_deny]| Option | Type | Default | Purpose |
|---|---|---|---|
--agents | boolean | false | Also write Claude, Cursor, and AGENTS.md guidance into the repository. |
--run-cap | USD, whole cents, ≤ 1,999,999.99 | none | On a newly created project, add a hard per-run spend cap that applies to every run. |
--budget | USD | 100.0 | Budget when init creates the project. |
--period | daily | weekly | monthly | monthly | Budget period when init creates the project. |
--mode | alert_only | hard_deny | alert_only | Enforcement mode when init creates the project. |
| Contract | |
|---|---|
| Auth | a login (a browser login when none is stored); an API key only for an existing project |
| Exit codes | 0 success · 1 generic/API · 2 usage or project mismatch · 3 auth · 5 not found · 6 approval or login pending |
| JSON schema | solwyn.init.v2 |
Run it from anywhere inside your repository. Provider detection and — with --agents — the files it writes are anchored at your Git root, so the location within the repo does not matter.
What it does, in order
Resolve authentication. The CLI resolves a credential in the usual order. With none stored, it runs the same browser login as solwyn login. On a terminal it first asks whether to log in or store an API key. Without a terminal it starts the browser login, so agents and SSH sessions don't get stuck. If the wait ends first, it exits 6 with login_pending: approve in the browser, run solwyn login --continue, then run solwyn init again. Signup and email verification happen on that browser page.
Resolve the repository's project. Init uses the same project selection as every command (--project, SOLWYN_PROJECT, then .solwyn.env; see Choosing the project), and nothing is created or written until it has decided:
| What names a project | What init does |
|---|---|
.solwyn.env names one, and --project or SOLWYN_PROJECT names another | Exits 2 with project_mismatch. No project is created and no file is written. |
.solwyn.env | Uses that project. It must exist, else project_not_found. The file is left as it is. |
--project or SOLWYN_PROJECT, and there is no .solwyn.env | Uses that project, which must already exist (init never creates a project from a flag or variable), and writes .solwyn.env naming it, as the last step after the budget was read, so a project that doesn't exist or can't be read is never recorded. |
Only the retired SOLWYN_PROJECT_ID | Exits 2 with usage_error before anything is created: SOLWYN_PROJECT_ID was replaced by SOLWYN_PROJECT (a project name or proj_ id). |
| Nothing, with a login, inside a git repository | Creates a project named after the repository (with --budget, --period and --mode), stores its first key on this computer for that project, and writes .solwyn.env. |
| Nothing, outside a git repository | Exits 2 with project_required: Outside a git repo, init needs a project. |
| Nothing, with only an API key | Exits 2 with project_required: An API key cannot create a project. Select the key's project, or run solwyn login. |
The repository's name is its folder name, with characters other than letters, digits, spaces, ., _ and - replaced by -. If an active project already has that name, init tries <name>-2, <name>-3, and so on. Creating a project needs a login and one browser approval. If the wait ends first, init exits 6; approve, then run the retry command it printed. Init no longer prompts for a project, a name or a budget.
.solwyn.env names the project and holds no secret. Commit it, so everyone working in the repository, and every coding agent, uses the same project:
# Solwyn project for this repo. Not a secret: commit this file.
SOLWYN_PROJECT="checkout-bot"Optionally cap every run. With --run-cap, and only when the previous step created a project, the CLI adds a runaway_run rule in hard_deny mode at that amount, so no single agent run can exceed it. Selecting an existing project with --run-cap is a usage error, run_cap_requires_creation, with a hint to use budget rule add --type runaway_run instead. The cap is validated locally before anything else runs.
Detect providers. The CLI walks the .py files under your Git root and AST-parses each one, looking only for imports of openai, anthropic, google-genai (google.genai), and boto3. It records which provider modules are imported — never any source content. The scan is bounded: it skips virtualenvs, .git, cache directories, node_modules, build, dist, symlinks, binary files, and nested Git repositories, and it stops after 2,000 files, 1 MB per file, or 10 MB in total.
Print SDK wiring. For each detected provider, the CLI prints the one-line snippet that wraps your client with Solwyn. The SDK reads SOLWYN_API_KEY and SOLWYN_PROJECT from the environment, which solwyn keys env provides. If nothing is detected, it prints a generic snippet you can adapt.
Verify the budget. It reads your project's budget status back from Solwyn Cloud — an end-to-end check that the credential, project, and network path all work — and prints the limit, remaining budget, and utilization.
Write agent guidance. With --agents, and only after the budget verified, it writes the three agent files described below. Then it emits its machine-readable result under the schema solwyn.init.v2, which carries project_id, project_name, project_created, key_stored, repo_file (the path, or null outside a git repository) and repo_file_written. key_stored ("Key stored" in the table) says whether a key for the project is stored on this computer, whether this run stored it or an earlier one did. In 0.5.0 it meant stored by this run, so a repository whose key was already stored read no.
$ solwyn init
Field Value
Project proj_0123456789abcdef01234567
Project name checkout-bot
Created yes
Key stored yes
Repo file /home/alice/checkout-bot/.solwyn.env
Providers openai
SDK wiring import os, openai; from solwyn import Solwyn; client =
Solwyn(openai.OpenAI(api_key=os.environ["OPENAI_API_KEY"]))
Budget verification verified
Budget remaining 75.00
Utilization 25.00%The wiring it prints
Each snippet wraps the client you already construct — Solwyn is a wrapper, not a proxy, so your calls still go directly to the provider. The CLI prints each snippet as a single line; they are expanded here for readability.
import os
from openai import OpenAI
from solwyn import Solwyn
client = Solwyn(OpenAI(api_key=os.environ["OPENAI_API_KEY"]))import os
from anthropic import Anthropic
from solwyn import Solwyn
client = Solwyn(Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"]))import os
from google import genai
from solwyn import Solwyn
client = Solwyn(genai.Client(api_key=os.environ["GOOGLE_API_KEY"]))import boto3
from solwyn import Solwyn
bedrock = boto3.client("bedrock-runtime", region_name="<AWS_REGION>")
client = Solwyn(bedrock)from solwyn import Solwyn
client = Solwyn(<YOUR_PROVIDER_CLIENT>)For OpenAI and Anthropic, the CLI matches the snippet to how your code already imports the SDK — module-style (import openai) or symbol-style (from openai import OpenAI).
Running non-interactively
init is safe to run in CI and from an agent, but it cannot prompt there, so its interactive steps have a non-interactive failure mode. The other ways it can stop are listed alongside:
| Situation | Code | Exit |
|---|---|---|
| No credential is stored and the browser login is still waiting | login_pending | 6 |
| Creating a project, or adding the run cap, is waiting for a browser approval | approval_pending | 6 |
| Nothing selects a project, and init can't create one (outside a git repository, or with only an API key) | project_required | 2 |
Only the retired SOLWYN_PROJECT_ID is set | usage_error | 2 |
.solwyn.env names one project and --project or SOLWYN_PROJECT another | project_mismatch | 2 |
--project, SOLWYN_PROJECT or .solwyn.env names a project your login cannot see | project_not_found | 2 |
.solwyn.env is not a valid repo file | repo_file_invalid | 2 |
--run-cap is not whole cents in range, or the project was not newly created | invalid_run_cap, run_cap_requires_creation | 2 |
| The credential store refused to store a credential, or the credentials file is readable by other users | credential_storage_failed | 3 |
--agents could not write, or had to roll back around a concurrent edit | agent_artifact_write_failed, agent_artifact_recovery_required | 1 |
Provide a login, and run it in a repository whose .solwyn.env names the project, or with none to create one, and init runs straight through with no prompts. These exit codes are drawn from the frozen set. If --run-cap fails after the project was created, the project and its stored key survive, and stderr tells you to review the new project's rules before retrying. If the run cap is waiting for its approval, re-running init can't finish the job; the retry command the CLI prints adds only the run cap to the created project.
Writing agent guidance with --agents
$ solwyn init --agents--agents additionally writes agent-facing guidance so coding assistants use Solwyn's guardrails correctly. It writes exactly three files, all carrying the same canonical guidance:
| File | For |
|---|---|
.claude/skills/solwyn/SKILL.md | Claude Code |
.cursor/rules/solwyn.mdc | Cursor |
AGENTS.md | A marked section between <!-- BEGIN SOLWYN AGENT CONTEXT --> and <!-- END SOLWYN AGENT CONTEXT --> |
The write is transactional — all three files land together or none does, and a failure rolls back to the prior state. It is idempotent — re-running replaces the marked AGENTS.md section in place rather than appending a second copy, and refreshes the two standalone files. Your existing AGENTS.md content outside the markers is left untouched, byte for byte. If another process edits one of the targets mid-write, the CLI preserves that edit rather than clobbering it, rolls back its own changes, and exits 1 with agent_artifact_recovery_required naming the retained backups. The atomic-exchange primitives it relies on exist on Linux and macOS only; on Windows, --agents fails with agent_artifact_write_failed.
The guidance is the same document solwyn agent-context prints. It opens with the changes only a human makes: never raise a cap, weaken enforcement, pause or remove rules, rotate or revoke keys, or change billing, and ask the human instead. Then it covers what Solwyn meters, polling and reservations, run identity and termination, tags and attribution, the machine contract, and the trust boundary. It says the repository's project is set in .solwyn.env (SOLWYN_PROJECT) and must not be changed to reach another project's budget. It hands the key to an SDK only through one command in a subshell, (solwyn_env="$(solwyn --format table keys env)" && eval "$solwyn_env" && exec <command>), and tells agents never to eval that output in their own shell or print it. Guidance written by 0.5.0 told agents to run a bare eval instead; run solwyn init --agents again with 0.5.1 to replace it. It tells agents to keep Solwyn credentials in the CLI's credential store or in environment variables from a secret manager, never to read the credentials file, never to wrap SDK-instrumented calls with budget check, and never to collect or proxy provider keys, prompts, or responses. No provider credentials are read or written. Agents covers the deeper integration story.
Next steps
- Scoped login: the browser login, approvals, and the credential order
initfollows - Choosing the project: how
.solwyn.env,SOLWYN_PROJECTand--projectselect a project - Agents — wiring Solwyn's guardrails into agent loops
budget rules— the runaway-run cap--run-capcreates, and how to add one to an existing project- Privacy — why detection and wiring never expose your prompts or keys
Installation
Install the Solwyn CLI, check the version you have, and configure Python and MCP requirements.
Agent integration
How coding agents use Solwyn — the agent-context guardrails brief, the MCP server and its two profiles, the check/confirm/record loop, run identity, and how to wire and verify a client