CLI flags

Every command-line flag the kin launcher accepts. Flags are the highest-precedence configuration layer — they override environment variables and both settings files. For the full precedence model, see Configuration.

Usage

kin [options]                 # interactive TUI session
kin --new [options]           # force a fresh interactive process/conversation
kin --bg "prompt" [options]   # start fresh background work and return
kin -p "prompt" [options]     # headless one-shot: print the answer, exit
echo "context" | kin -p       # headless, prompt (or extra context) via stdin

With no options, kin reattaches the only unattended persistent process in the current directory, opens a chooser when several are available, or creates a fresh one when none is available. Use --new when “fresh” is the intent. Run kin --help to print the same flags from argparse.

When a saved interactive session exits cleanly, Kin prints the exact kin --resume <id> command needed to continue it. The handoff follows the final active conversation after an in-session switch and is omitted when no resumable journal survived shutdown. On the default managed path the surviving outer launcher prints it after the inner UI pane has exited, so the command lands in shell-visible scrollback; --no-detach uses the same validator directly.

-p/--print runs one turn with no UI at all and exits with a contract code — 0 ok, 1 error, 2 needs-human. See Headless runs for the permission envelope, the exit codes, and cron examples.

Flags

Flag	Argument	What it does	Env / settings.toml
-p, --print	(flag)	Headless one-shot: run the positional PROMPT (and/or piped stdin) with no UI, print the final assistant text to stdout, exit 0 / 1 / 2. The session still journals (resume it in the TUI) unless --no-save. Combinable with --resume / --continue to continue a saved session headlessly — see Resuming headless by continuation. NOT combinable with --agent (a profile launch has no TTY to resolve an approval/ask modal).	—
(positional)	PROMPT	The prompt for a -p run (- forces stdin; piped stdin is prepended as context when both are given), or the work for --bg. Only valid with -p or --bg.	—
--output	file	(With -p.) Also write a markdown run report — prompt, model, mode, duration, needs-human items, final text — to this path (parents created).	—
--token-budget	int	(With -p.) Cap the run’s cumulative prompt+completion tokens. A budget hit stops cleanly at the next model-round boundary and exits 1 (reason token_budget). 0 disables. See Fleet safety.	KIN_TOKEN_BUDGET / token_budget
--max-turns	int	(With -p.) Cap the run’s model↔tool round-trips. A cap hit stops with reason turn_cap (exit 1). 0 = unlimited (the default — the doom-loop guard is the real backstop).	KIN_MAX_TURNS / max_turns
--provider	openai | anthropic	Selects the provider family. Default openai, unless a base URL is set and neither identity axis is given, in which case the vLLM heuristic picks anthropic. Explicit openai without --wire-api means Chat.	KIN_PROVIDER / provider
--wire-api	chat | responses	Selects the OpenAI wire shape and implies provider=openai, bypassing the bare-URL Anthropic heuristic. Responses is explicit opt-in; Chat remains the compatibility default.	KIN_WIRE_API / wire_api
--model	model id	The model to call.	KIN_MODEL / model
--base-url	URL	OpenAI-compat endpoint URL (a trailing /v1 is trimmed for the Anthropic wire).	KIN_BASE_URL / base_url
--workdir	path	Working directory for the session. Default: the current directory; if that directory is gone or unreadable (deleted — or Finder-moved to the Trash — while the terminal was open), kin prints a notice and starts in your home directory, or / if home cannot be entered. An explicit absolute path always wins; a relative path requires a live current directory to anchor it.	—
--temperature	float	Sampling temperature (OpenAI-compat wire only).	KIN_TEMPERATURE / temperature
--top-p	float	Nucleus sampling top_p (OpenAI-compat wire only).	KIN_TOP_P / top_p
--top-k	int	top_k via extra_body (OpenAI-compat wire only).	KIN_TOP_K / top_k
--resume	ID	Resume an exact conversation by id. If a managed process already owns it, attach to that process; otherwise start a managed process from the saved journal. Works with -p for a headless continuation turn (e.g. answering a needs-human halt).	—
--continue	(flag)	Continue the newest saved conversation for this workdir, attaching its live owner when one exists. Works with -p; errors if no saved session exists for the workdir.	—
--new	(flag)	Force a fresh conversation/process even when the workspace already has live or unattended sessions. Respects the detach preference: --new --detach forces persistence and --new --no-detach stays unwrapped. Mutually exclusive with --resume / --continue; harmlessly redundant for fresh headless, agent, and background launches.	—
--no-save	(flag)	Run ephemerally — write no session journal and no durable prompt history (not resumable; ↑/↓ and ++ctrl+r++ remain memory-only for this process).	KIN_NO_SAVE / no_save
--detach	(flag)	Run this launch as a persistent session: /detach leaves only its issuing terminal while the process keeps running, and bare kin in the same folder recovers one available process or opens the launch chooser. Interactive TTY launches only (never -p, never inside your own tmux); degrades to a plain launch with one notice if tmux ≥ 3.2 isn’t on PATH.	KIN_DETACH / detach
--no-detach	(flag)	Force a plain, non-persistent launch — the escape hatch that overrides --detach, KIN_DETACH, and the detach settings key. With --new, it is fresh but unwrapped.	—
--bg	PROMPT (positional)	Create another unique fresh persistent process, submit PROMPT, and return to the shell without opening the UI. Repeated calls in one workspace create siblings; the confirmation includes the sibling count. Mutually exclusive with -p, --resume, and --continue.	—
--mode	auto | strict	Permission mode at launch (the legacy default / accept-edits / plan are still accepted and alias onto the pair, with a deprecation note). Default: auto. Cycle in-session with ++shift+tab++; use /plan for a read-only planning pass.	KIN_MODE / mode
--preset	preset id	Provider preset (built-ins: direct openai / anthropic, plus curated minimax, zai). Bundles wire + endpoint/auth identity; curated presets also supply a default model. CLI > KIN_PRESET > file.	KIN_PRESET / provider_preset
--agent	profile name	Run the main session as the named profile (e.g. researcher, coder); the profile’s tool allow-list + persona become the thread. TTY-only (refuses when stdin is not a tty).	—
--version	(flag)	Print kin <version> and exit 0 (before any TUI import — the get.kinra.ai installer’s success gate).	—

Resume reuses the saved endpoint

When a conversation is saved-only, --resume or --continue reuses its provider and model unless you pass an explicit backend flag (--provider, --wire-api, --model, --base-url, or a sampling flag). A resumed session never re-reads a live settings.toml file, so a global default cannot silently re-target a frozen conversation.

When the conversation is already live, launch-only overrides are refused instead of ignored: attach without them, change configuration in-session, or /fork. A legacy live process with no published conversation identity must first be attached with bare kin; Kin will not risk opening its journal twice.

auto is the default — safe autonomy

--mode auto is the launch default and is safe autonomy: edits and shell run without per-call prompts, but shell goes through a kernel OS sandbox. You toggle to strict (ask-first) and back in-session with the ++shift+tab++ keybinding (auto ↔ strict), or use /plan for a read-only planning pass. See Auto mode & the sandbox.

kin doctor

Verifies an install — the check the get.kinra.ai installer points you at, and the first thing to run on any new machine:

kin doctor              # full checklist
kin doctor --offline    # skip the endpoint reachability probe

Like kin service, it’s a subcommand dispatched before the flag parser (none of the flags above apply; implemented in kin.harness.cli.doctor). Three chunks, one checklist line per check (✓ pass / ✗ critical fail / • info):

1. install — uv, kin, and git on PATH; ~/.local/bin in PATH; task reported info-only (it runs the dev gates — not a consumer prerequisite). GitHub API + Git transport readiness is also info-only: whether gh is on PATH and, unless --offline, whether it has a healthy active login. Inherited GH_* / GITHUB_* tokens are ignored; only a token-free account/source projection crosses from gh; and a missing login points to /github connect. The structured Git data plane uses that account over authenticated HTTPS even when the saved remote uses SSH.
2. config — ~/.kin/settings.toml parses (a TOML error is critical, with the line/column; a missing file is only a warning since env vars can carry a full config), and a provider resolves. The walk mirrors the backend factory’s exact chains and names which source supplies the model endpoint and the key (preset / [[providers]] row / provider_keys / KIN_BASE_URL / API-key env vars / top-level api_key). No endpoint and no key from any source is critical. It also reports whether the masked Outpost live-gate credential is configured. That line is informational for ordinary installs and points AI-peer development machines to task live-beam-setup; the token is never printed.
3. network (skipped by --offline) — one GET against {base_url}/models with a 5s timeout. Any HTTP response — 401 and 404 included — counts as reachable (auth is not doctor’s job); connection/timeout errors are critical.

After the chunks, one info-only update line (never critical): whether a newer release is published on get.kinra.ai — cache-first (the TUI’s 24h check shares the cache), and under --offline it reports a cached answer or says it can’t tell.

Exit code: 0 when every critical check passes, 1 otherwise (the final line names the verdict and the first fix to try).

kin update

Updates this install to the published release — Install → Updating has the full flow, shapes, and fallbacks:

kin update              # detect the install shape and apply the update
kin update --check      # report only; exit 1 when an update is available

Same pre-parser dispatch as doctor (implemented in kin.harness.cli.update). A checkout install gets git pull --ff-only + uv sync + a tool-venv refresh; a wheel install gets uv tool upgrade with a pinned-index --reinstall fallback. Exit code: 0 success / already up to date / status unknown, 1 the update failed (--check: 1 means an update is available).

kin connect

Connects a custom OpenAI-compatible provider in one command — creates (or updates) its global [[providers]] row, collects the API key through a masked prompt, and makes the provider’s model the active selection:

kin connect kinra-api \
  --base-url https://api.kinra.ai/v1 \
  --wire-api responses \
  --model deepseek-v4-flash \
  --label "Kinra hosted inference"

Same pre-parser dispatch as doctor (none of the flags above apply; implemented in kin.harness.cli.connect). --base-url, --wire-api (chat | responses), and --model are required; --label names the row in the pickers and defaults to the id.

When the provider hosts a separate vision model beside its main model, the optional --vision-route family also creates a named model route on the same connection and assigns it the vision job — one command, one transaction:

kin connect kinra-api \
  --base-url https://api.kinra.ai/v1 \
  --wire-api responses \
  --model deepseek-v4-flash \
  --label "Kinra hosted inference" \
  --vision-route kinra-vision \
  --vision-model qwen3.6-35b-a3b \
  --vision-description "Kinra hosted vision on Kloud" \
  --vision-max-tokens 1024 \
  --vision-reasoning-profile qwen-llamacpp \
  --vision-effort thinking-512 \
  --utility-route kinra-vision

--vision-route names the [model_routes.<id>] entry (--vision-model is then required; --vision-description, --vision-max-tokens, --vision-reasoning-profile, and --vision-effort are optional). The effort flag requires the profile flag; the profile is a closed qwen-llamacpp choice and effort is one of default, off, or thinking-128/512/1024/2048. The route is created with vision = true and assigned as [model_assignments].vision; the main model stays --model — the vision route never displaces it. The flags are a closed schema on purpose: there is no raw-TOML or JSON passthrough.

--utility-route <id> additionally assigns an existing route — the one --vision-route stages in the same command, or one already saved — as [model_assignments].utility, kin’s housekeeping job (session auto-titles), which keeps tiny side-calls off the main model’s prompt cache. It is assignment-only: it never creates a route, a vision route is never treated as a utility route implicitly, and an id matching no route refuses without writing anything.

The key is prompt-only, by design. There is no --api-key flag and no environment fallback — a key on the command line lands in shell history and process listings, so a literal --api-key argument is refused (without echoing its value). Everything is written to the global ~/.kin/settings.toml through the same locked transaction the /models hub uses; a project’s .kin/settings.toml never holds a credential.

Re-running the command is safe:

• Absent id — the connection is created, keyed, and activated.
• Same endpoint/wire/model — the stored key is rotated and the provider re-activated (pass --label to also rename it).
• Conflicting id (a row with the same id but a different endpoint, wire, or model) — the command refuses without changing anything and points at the fix: pick a different id, or edit the existing connection in the /models hub.
• Existing --vision-route id — an identical route is a no-op; a route pointing at a different provider, model, or vision = false refuses without changing anything (description and max-tokens update in place). If the vision job was assigned to another route, the command reassigns it and says so.
• --utility-route — re-assigning is always safe; if the utility job was bound to another route, the command reassigns it and says so.

Everything — provider row, key, vision route, and the vision/utility assignments — lands in one locked save; a refused or failed run writes nothing (no provider-only half-state).

Exit code: 0 connected / 1 refused or failed / 2 usage error.

kin settings

Shows the effective configuration with provenance — the answer to “why isn’t this setting applying”:

kin settings                    # effective keys, env overrides, lint (for cwd)
kin settings --workdir <path>   # overlay a different project's .kin/settings.toml

Same pre-parser dispatch as doctor (implemented in kin.harness.cli.settings_cli; the projection is shared with kin doctor). Read-only, and secret values render as set — never bytes. Three blocks:

1. effective configuration — every key set in any file layer, its value, and the layer that wins (~/.kin/settings.toml, credentials.toml, grants.toml, or the project .kin/settings.toml), with shadowed lower layers named.
2. env overrides — active KIN_* (plus vendor key) variables, which outrank every file at launch.
3. lint — unknown keys (typos), global-only keys ignored in a project file, keys pending migration to their sibling file, weak credentials.toml permissions, and files that fail to parse. The same rows appear in kin doctor as advisory lines.

Exit code: always 0 — lint is advisory; kin doctor owns the critical checks.

Service registry CLI (kin service …)

kin service create / list / disable / enable / rekey manages the service registry behind Outpost’s /api/v1/ machine door — registering a service prints its Bearer token and whsec_ webhook secret once, rekey rotates the encryption key. It’s a separate subcommand family dispatched before the flag parser (so none of the flags above apply), implemented in kin.harness.cli.service. The full contract lives in PROTOCOL.md (see the protocol index); the related env vars (KIN_MASTER_KEY / KIN_OLD_MASTER_KEY) are in Environment variables.

For what each provider supports, see Models & providers. For the modes themselves, see Modes & permissions. For --agent, see Agents.