init, completions, auth

Three small subcommands that get you from a clean checkout to a working shell session.

kanros init

Scaffold a new kanros.yaml from a template, or write a runnable example bundled in the binary.

kanros init [PATH] [--force] [--template <NAME> | --example <NAME>]
kanros init --list-examples

Flag	Default	Meaning
positional	`./kanros.yaml`	Destination path.
`--force`	off	Overwrite an existing file without prompting.
`--template <NAME>`	`default`	Template to scaffold from: `default` or `redteam`.
`--example <NAME>`	none	Write a bundled example instead of a template (conflicts with `--template`).
`--list-examples`	off	List the bundled examples and exit.

Bundled examples run offline (no API key, no network), so this passes on a fresh install:

kanros init --example smoke && kanros run

Example	What it is
`smoke`	The quickstart suite on the `echo` provider: 2 tests, 5 deterministic assertions.

Each template ships as a built-in string in crates/kanros-cli:

default — a minimal eval suite against openai:gpt-4o-mini (needs OPENAI_API_KEY, or swap the provider for echo:identity to try it offline).
redteam — refusal tests plus a red_team: plugin/strategy block, a starting point for red teaming. Swap the echo provider for your real target when you are ready.

kanros init                              # scaffold ./kanros.yaml
kanros init configs/regression.yaml      # custom path
kanros init --force                      # overwrite without prompting
kanros init --template redteam           # offline red-team starter suite
kanros init --example smoke              # bundled offline smoke test
kanros init --list-examples              # what --example accepts

After scaffolding, run kanros validate to confirm the file parses, then kanros run to see it execute.

kanros completions

Print a shell completion script to stdout.

kanros completions <SHELL>

Supported shells: bash, zsh, fish, powershell, elvish.

Bash

kanros completions bash > ~/.local/share/bash-completion/completions/kanros

Restart the shell. The completions cover every subcommand, every flag, and the --format enum values.

Zsh

If fpath is configured for completion:

kanros completions zsh > "${fpath[1]}/_kanros"

Otherwise, drop the script in any directory and add it to fpath:

mkdir -p ~/.zfunc
kanros completions zsh > ~/.zfunc/_kanros

…then add to ~/.zshrc:

fpath=(~/.zfunc $fpath)
autoload -Uz compinit && compinit

Fish

kanros completions fish > ~/.config/fish/completions/kanros.fish

Fish picks up completions automatically on the next prompt.

PowerShell

kanros completions powershell | Out-String | Invoke-Expression

Persist by appending the above line to $PROFILE.

Elvish

kanros completions elvish > ~/.config/elvish/lib/kanros.elv

Then use kanros in ~/.config/elvish/rc.elv.

kanros auth

Manage provider credentials in the system keyring. Keys are stored under service name kanros, account name equal to the provider family (e.g. openai, anthropic).

kanros auth <SUBCOMMAND>

The subcommands are:

Subcommand	Description
`set <FAMILY>`	Store an API key for a provider family. Prompts for the value.
`set <FAMILY> --key X`	Store the literal value `X` (less safe — appears in shell history).
`get <FAMILY>`	Print the stored key (or a "no entry" message).
`delete <FAMILY>`	Remove the key.
`list`	List provider families with stored keys.

Examples

kanros auth set openai           # interactive prompt; the value is not echoed
kanros auth set anthropic --key sk-ant-…
kanros auth list
kanros auth delete openai

Lookup order

When a network provider needs an API key, kanros checks:

config.api_key in the provider's inline YAML block.
The provider-specific environment variable (OPENAI_API_KEY, ANTHROPIC_API_KEY, GROQ_API_KEY, …).
The system keyring under the provider family.

If none of the three resolve, the provider returns a ProviderError::Unauthorized and the cell records the failure.

Platform support

The keyring is provided by the keyring crate:

macOS — Keychain.
Windows — Credential Manager.
Linux — the kernel keyring (keyutils), so the static musl build needs no D-Bus. Keys last for your login session and are gone after a reboot; run kanros auth set again, or use environment variables. kanros auth set reminds you with a one-line note on stderr:
```
note: stored in the kernel keyring for this login session; use `OPENAI_API_KEY` for persistent setups
```

Environment variables always work on every platform and always take precedence over the keyring, so they are the right choice for servers, containers and anything that must survive a reboot.

On headless CI servers where no keychain is configured, fall back to environment variables.

Why these three live together

They are the "developer ergonomics" commands. init gets you a config, completions makes the CLI fast to type, and auth keeps credentials out of shell history and out of YAML. They have no overlap with the run / redteam / diff evaluation pipeline.