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

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](/docs/kin/getting-started/configuration/).

<!-- SOURCE: src/kin/tui/cli.py, src/kin/tui/mux.py, src/kin/tui/mux_sessions.py, src/kin/tui/launch_picker.py, src/kin/harness/presets.py, src/kin/harness/headless.py, src/kin/harness/github_connection.py, src/kin/harness/cli/doctor.py, src/kin/harness/cli/connect.py, src/kin/harness/cli/settings_cli.py, src/kin/harness/settings/inspect.py -->

## Usage

```bash
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](/docs/kin/guide/headless/) 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](/docs/kin/guide/headless/#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](/docs/kin/guide/headless/#fleet-safety-the-per-run-token-budget). | `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](/docs/kin/guide/sessions/#background-sessions-detach-reattach): `/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](https://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](/docs/kin/guide/keybindings/) (`auto ↔ strict`), or use `/plan` for a read-only planning pass. See [Auto mode & the sandbox](/docs/kin/guide/auto-mode-and-sandbox/).

## `kin doctor`

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

```bash
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](https://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](/docs/kin/getting-started/install/#updating) has the full
flow, shapes, and fallbacks:

```bash
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:

```bash
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](/docs/kin/guide/models-and-providers/#model-routes) on the
same connection and assigns it the vision job — one command, one
transaction:

```bash
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](/docs/kin/guide/models-and-providers/#the-utility-job-housekeeping-side-calls)
(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](/docs/kin/guide/providers/#connections-in-models).
- **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":

```bash
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](https://github.com/kinra-ai/kin/blob/dev/PROTOCOL.md)
(see the [protocol index](/docs/kin/protocol/)); the related env vars
(`KIN_MASTER_KEY` / `KIN_OLD_MASTER_KEY`) are in
[Environment variables](/docs/kin/reference/environment-variables/).

For what each provider supports, see [Models & providers](/docs/kin/guide/models-and-providers/). For the modes themselves, see [Modes & permissions](/docs/kin/guide/modes-and-permissions/). For `--agent`, see [Agents](/docs/kin/concepts/agents/).