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 -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 starts a fresh session in the current directory using your environment and settings.toml for everything else. Run kin --help to print the same flags from argparse.

-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). Only valid with -p.	—
--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 model wire. Default openai, unless a base URL is set and no provider is given, in which case the vLLM heuristic picks anthropic.	KIN_PROVIDER / provider
--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.	—
--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 a saved session by id. Works with -p for a headless continuation turn (e.g. answering a needs-human halt).	—
--continue	(flag)	Resume the newest saved session for this workdir. Works with -p; errors if no saved session exists for the workdir.	—
--no-save	(flag)	Run ephemerally — write no session journal (not resumable).	KIN_NO_SAVE / no_save
--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	First-party provider preset (built-ins: minimax, zai). Bundles wire + URL + default model + auth style. 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 you resume with --resume or --continue, the saved provider and model are reused unless you also pass a backend flag (--provider, --model, --base-url, or a sampling flag). A resumed session never re-reads a live settings.toml file, so a global default can't silently re-target a conversation you thought was frozen.

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).
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.
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.

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

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.