init
One command that authenticates, selects a project, writes config, 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 a project, writes your configuration, 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 — every provider credential stays on your own client.
$ solwyn initRun 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 precedence order. If none is stored and you are on an interactive terminal, it prompts you to authenticate — either a project key or an email/password login. With no credential and no terminal to prompt, it reports interactive_auth_required and exits 3.
Resolve a project. A project key already names its project, but it cannot discover it on its own — pass --project (or set SOLWYN_PROJECT_ID) so the CLI knows which one the key belongs to. Under a user login, the CLI auto-selects when your account has exactly one project; otherwise it prompts you to choose one (or create a new one) on a terminal. If a project cannot be resolved without prompting, it reports project_required and exits 2.
Persist configuration. The selected project is written to config.toml as default_project; a non-default API URL is recorded alongside it, and the default is left implicit. Every later command reads this file, so you stop repeating --project.
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. If nothing is detected, it prints a generic snippet you can adapt.
Verify the budget. Finally 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. It emits its machine-readable result under the schema solwyn.init.v1.
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.
from openai import OpenAI
from solwyn import Solwyn
client = Solwyn(OpenAI(api_key="<OPENAI_API_KEY>"))from anthropic import Anthropic
from solwyn import Solwyn
client = Solwyn(Anthropic(api_key="<ANTHROPIC_API_KEY>"))from google import genai
from solwyn import Solwyn
client = Solwyn(genai.Client(api_key="<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, but it cannot prompt there, so both interactive steps have a non-interactive failure mode:
| Situation | Code | Exit |
|---|---|---|
| No credential resolves and no terminal to prompt | interactive_auth_required | 3 (auth) |
| A project cannot be resolved without prompting | project_required | 2 (usage) |
Provide SOLWYN_API_KEY and --project (or SOLWYN_PROJECT_ID) and init runs straight through with no prompts. These exit codes are drawn from the frozen set: 0 success, 1 generic or API error, 2 usage, 3 auth, 4 budget denied, 5 not found.
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.
The guidance is safe by construction: it tells agents to keep Solwyn credentials in the OS keychain, 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
- Authentication — credential types, storage, and the precedence
initfollows - Configuration — what lands in
config.tomland how to change it - Agents — wiring Solwyn's guardrails into agent loops
- Privacy — why detection and wiring never expose your prompts or keys