SOLWYN

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.

Terminal
solwyn init [--agents] [--run-cap <usd>] [--budget <usd>] [--period daily|weekly|monthly] [--mode alert_only|hard_deny]
OptionTypeDefaultPurpose
--agentsbooleanfalseAlso write Claude, Cursor, and AGENTS.md guidance into the repository.
--run-capUSD, whole cents, ≤ 1,999,999.99noneOn a newly created project, add a hard per-run spend cap that applies to every run.
--budgetUSD100.0Budget when init creates the project.
--perioddaily | weekly | monthlymonthlyBudget period when init creates the project.
--modealert_only | hard_denyalert_onlyEnforcement mode when init creates the project.
Contract
Autha login (a browser login when none is stored); an API key only for an existing project
Exit codes0 success · 1 generic/API · 2 usage or project mismatch · 3 auth · 5 not found · 6 approval or login pending
JSON schemasolwyn.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 projectWhat init does
.solwyn.env names one, and --project or SOLWYN_PROJECT names anotherExits 2 with project_mismatch. No project is created and no file is written.
.solwyn.envUses 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.envUses 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_IDExits 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 repositoryCreates 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 repositoryExits 2 with project_required: Outside a git repo, init needs a project.
Nothing, with only an API keyExits 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.env
# 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.

Terminal
$ 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:

SituationCodeExit
No credential is stored and the browser login is still waitinglogin_pending6
Creating a project, or adding the run cap, is waiting for a browser approvalapproval_pending6
Nothing selects a project, and init can't create one (outside a git repository, or with only an API key)project_required2
Only the retired SOLWYN_PROJECT_ID is setusage_error2
.solwyn.env names one project and --project or SOLWYN_PROJECT anotherproject_mismatch2
--project, SOLWYN_PROJECT or .solwyn.env names a project your login cannot seeproject_not_found2
.solwyn.env is not a valid repo filerepo_file_invalid2
--run-cap is not whole cents in range, or the project was not newly createdinvalid_run_cap, run_cap_requires_creation2
The credential store refused to store a credential, or the credentials file is readable by other userscredential_storage_failed3
--agents could not write, or had to roll back around a concurrent editagent_artifact_write_failed, agent_artifact_recovery_required1

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

Terminal
$ 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:

FileFor
.claude/skills/solwyn/SKILL.mdClaude Code
.cursor/rules/solwyn.mdcCursor
AGENTS.mdA 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 init follows
  • Choosing the project: how .solwyn.env, SOLWYN_PROJECT and --project select a project
  • Agents — wiring Solwyn's guardrails into agent loops
  • budget rules — the runaway-run cap --run-cap creates, and how to add one to an existing project
  • Privacy — why detection and wiring never expose your prompts or keys

On this page