← Reference

Command line

The kcode binary: bare launch opens the Mission Control window; flags and subcommands cover headless runs, resumes, and admin.

Full notes from the app

These mixes are refused rather than ignored: a launch flag with a subcommand, --resume or -c with -p, --output-format or --json-schema without -p, and --print with a bare --resume, --model, --permission-mode or --bypass-permissions.

16 entries · kcode 0.6.5097

16 shown
CommandArgumentsWhat it does
kcodeOpen the GPU Mission Control window (the default frontend). Sessions live in the per-app daemon, which starts on demand and exits with the app.
kcode -p <prompt>--output-format text|json|ndjson [--json-schema <file>] [--resume <id> | -c]Headless one-shot: run a prompt non-interactively and print the agent's last reply. Text that starts with a /name runs the skill, markdown command or plugin command it names, as the composer runs it: kcode -p "/review src" runs /review on src. Text that starts with a file path, such as /etc/hosts what is this, is a prompt. A skill's or command's own model is used when a connected provider serves it, else the session's model, with a note on stderr saying why. A plugin command prints its handler's answer and starts no turn, so it makes no session (the json session_id is null unless --resume names one) and takes no --json-schema. kcode's own commands (/compact, /version, …) run only in the app, and a name nothing holds is refused before a session is made (exit 2). It starts a new session, or with --resume <id> or -c runs the prompt as that session's next turn: the turn sees the session's history and runs in its folder, on its model, effort, goal, subagent pool, compaction budget and permission mode, --permission-mode and --bypass-permissions still apply, for that run only. --model becomes the session's model, as a /model pick does in the app, so a later -c continues on it. A session open in the app, or in use by another kcode -p run, is refused until it is let go (and the app won't open a session while a kcode -p run uses it) and so is a session whose folder is gone or an id that names no session (exit 2). --resume with no id and --print are refused with -p. --output-format ndjson streams one versioned JSON line per turn event (text/thinking deltas, tool start/finish, control-plane emissions, usage) with the final envelope last: built for scripting and CI. A control line carries the channel's tag text as the model reads it (rendered, escaped) and, beside it, the channel's attrs and body as written, so a script need not undo the escaping. The usage line (and the usage object --output-format json prints beside final_text) names the model the turn ended on (model: the one picked, or the fallback a plugin switched to), its active time (elapsed_ms: wall time less the time spent waiting on your answers) and its provider rounds, beside the turn's tokens and the context it left. Its cost_usd is what the session has cost so far in US dollars, each provider call priced from the live models.dev catalog at the prices of the provider it went to: a model the catalog does not price counts $0, and so does a call a subscription covers, a ChatGPT sign-in, Kimi For Coding. --json-schema <file> requires the final answer to validate against the given JSON Schema: the turn gains a synthetic submit_result tool, concludes only on a valid payload (5 invalid attempts fail the turn), and --output-format json and the ndjson final envelope carry it as structured_output (text output prints it as JSON). The answer is that tool call's arguments, which are one JSON object, so the schema must describe an object ("type": "object"); a file that cannot be read, is not JSON, holds a schema for anything else or holds one that is not valid JSON Schema is refused before the run starts (exit 2, the error names the file and the problem). A kcode -p run has no app behind it, so it is not offered the tools that need the app: set_timer, cancel_timer, fork_session, set_activity, spawn_worktree_session, manage_session and the built-in notify; its run_command takes only compact and prompt commands, its send_message and check_inbox reach only the session's own agents, and its system prompt leaves out the lines for the rest. While this Mac isn't signed up, or its trial or subscription has ended, a run starts nothing: it prints why and exits 3 (kcode license signs up and buys). A check-in with kcode.sh that falls due goes first, so a payment made since lets the run go. A build made for development needs no license. Once it has printed its answer it exits within ten seconds, even when a git or file call it started is stuck.
kcode --resume [id] / -c--printResume a session and open the window in it: maximized, or selected in the Sidebar and Tabbed layouts. A session that has stopped, the usual case since the daemon exits with the app, is brought back as it opens; in a project you haven't trusted, the launch's trust question comes first and the resume waits for your answer. -c/--continue-last resumes the session created most recently. --resume with no id opens Mission Control, where ⌘K lists every session. --model and --permission-mode / --bypass-permissions apply to the session it opens, as /model and /permissions would, and to the sessions the window spawns. Add --print to print the conversation to stdout and exit instead of opening the window: the Markdown /share writes, your prompts, the replies with their reasoning, tool calls and notices, from before any compaction too, without the context kcode adds for the model. It needs a session to print, so a bare --resume --print is refused, and it opens no session, so --model, --permission-mode and --bypass-permissions are refused with it. With -p <prompt>, the prompt runs as the session's next turn and no window opens (see kcode -p).
--model <id>Override the model for the run (any keyed provider: resolution, not relaunch). In the window it is the model of each session the window spawns and of the session a --resume <id> or -c launch opens, which keeps it as it keeps a /model pick.
--permission-mode / --bypass-permissionsdefault|accept-edits|auto|planSet the permission mode of the sessions this window spawns and of the session a kcode --resume <id> or -c launch opens, or of a kcode -p run. --bypass-permissions (or --yolo) is the same as --permission-mode auto: tool calls run without a permission prompt, except calls that read or write a secret location (permissions.secret_paths), and deny rules still apply; given with another --permission-mode, the launch is refused. A session given the mode in the window keeps it when it is resumed later. A kcode -p run uses the mode for that run only, a resumed session included, and leaves the session's own mode as it was.
--config <path>Layer an extra config file over the usual stack: compiled defaults → user → trusted project → --config <path> → KCODE_* environment → command-line flags. Forwarded to re-exec'd children (shell host).
--data-dir <dir>Keep kcode's data (config, credentials, sessions, logs, snapshots, themes, plugins) under this directory instead of the build's own data folder in your home folder. Each data directory runs its own daemon, so a second kcode can run beside your real one (make fresh in the repo launches a fresh-user instance this way). The directory is created if missing, and kcode keeps it readable by you alone (a folder other users could open loses their access at launch); a relative path is against the current directory; an unusable path fails the launch. Accepted before or after a subcommand (kcode doctor --data-dir <dir> checks that data dir). Same as setting KCODE_DATA_DIR, and it is published as that variable so the daemon and shell host follow. The welcome card's tips, /help and the palette name files under this directory.
kcode doctor[--json]Advisory local health reports for the app and current project, using the same engine and text formatter as the GPU reports. Run in the home folder, a folder above it, /, or the folder that holds the data folder, it reports only the app, since those folders are not projects. Reads saved ignores without creating or migrating stores. Untrusted project contributions are skipped. Does not start a session, connect to the daemon, probe DNS, call providers, run hooks or repair files. Remote credentials and availability remain unverified. It lists only the checks that didn't pass (a settings section with nothing saved passes, since its defaults apply) and its last line totals the active findings of every report it printed (Overall: 1 active finding (1 error).). Exit 0 for reports without active Error findings (warnings and reviews are advisory), 1 for active errors, and 2 for total collection failure. Each saved setting kcode can't use is named: a misspelled name with the nearest one kcode reads, a value of the wrong type with the type it needs. Output includes build identity, scope, timestamps and ignored findings; local paths may appear, but credentials and the text of a config line that doesn't parse do not; such a file is named with its line and column. It exits within ten seconds of printing its report, even when a check is stuck. --json prints one JSON document in place of the text: its version v, exit_code, error, the counts, and each report's scope, findings (with ignored) and checks, passed ones too. The exit codes stay the same.
kcode authlogin <provider> [--sign-in [--device]] | logout <provider> [--key | --sign-in] | statusConnect model providers from the command line, writing the same auth.toml in the data folder that Settings › Providers writes. login <provider> reads the provider's API key at a terminal prompt that hides what you type; with no terminal it reads the key from standard input (kcode auth login groq < key.txt). login <provider> --sign-in signs in with a subscription plan instead (today openai, with a ChatGPT plan, whose name it reports) opening the sign-in page in your browser; --device shows a code to type on the provider's page instead, for a machine with no browser. When kcode is running, it takes the key or the sign-in and starts using it at once; otherwise the next launch reads it. kcode auth login --help lists every provider kcode connects, and names the ones with a sign-in; a provider you added in config.toml ([providers.<id>]) takes a key by its id too, and status lists it. logout <provider> removes the provider's saved key and its sign-in, --key or --sign-in only the one named; a running kcode stops using them at once. It says when there was nothing to remove, and names any credential kcode still reads: a key in an environment variable stays until you unset it. status lists every provider with a key or a sign-in, the one in use first and where each is read from. Ctrl+C at the prompt or during a sign-in stops without saving.
kcode licenselogin | status | refresh | logout | buy [monthly|yearly]Sign this Mac up for kcode, and see or change its license, from the command line. login prompts for your name and email, emails you a code, and prompts for the code: after a wrong one it prompts again, and pressing Enter with nothing typed sends a new one. While the code is on its way it shows Help improve kcode: what product analytics kcode sends and the privacy page's address, then the question whether to include your account: y includes it, n keeps them anonymous, Enter answers later; the answer goes with the code. Once the code is checked, kcode runs on the account: a new account starts its free trial. Signing up under another email moves this Mac to that account. status says whether kcode may run on this Mac and, when it can't, what to do, then names the account, the free trial or the subscription with when it ends or renews, how many of the account's Macs are in use, when this Mac last checked in with kcode.sh, and whether product analytics are sent with the account. refresh checks in now, to pick up a payment or another change to the account. logout frees this Mac's place on the account and deletes its license. buy opens kcode.sh in your browser, signed in as this Mac's account: buy monthly or buy yearly goes straight to checkout, and with no plan the account page offers both. When kcode is running, it runs the command, so its windows and its lock follow at once; otherwise the command reads and writes the license itself. A build made for development needs no license, and every command says so. Questions go to standard error, so standard output holds only the answer. Ctrl+C stops a sign-up.
kcode mcplist [--no-probe] | add <name> <url> [--transport http|sse] [--replace] | remove <name> | reconnect <name> [--session <title>] | login <name> [--session <title>]Manage MCP servers (stdio, HTTP, SSE: remote entries take optional headers for API keys/auth). list enumerates the user ~/.kcode/mcp.json + project .mcp.json servers and probes each (connect → initialize → tool count, bounded per server by mcp_protocol.probe_timeout_secs, default 8s; --no-probe prints config only). A project you haven't trusted, or that changed since you trusted it, has its servers listed as not started with a line saying why: probing a server runs its command. add/remove edit the user-scope file (written 0600: headers can hold keys). add registers a remote server over streamable HTTP, or over HTTP with server-sent events with --transport sse. Its name takes lowercase letters, digits, - or _, since kcode loads each server as a plugin of that name, and its URL must be http:// or https://; otherwise nothing is written. A name already in the file is kept, and the refusal names its address, unless --replace is given, which says what it replaced. reconnect dials the daemon and bounces the server's live connection on the target session (unload + fresh connect, tools re-register in place): the recovery path after restarting a local server or rotating a token; it exits 1, printing why, when the reconnect fails (the server is left disconnected) or no session is open in the current folder, or none has the --session title. login <name> signs in to an OAuth-gated remote server: the daemon sends the server a request without a token and reads the protected-resource metadata (RFC 9728) from the URL its 401 names in WWW-Authenticate, else from the well-known URI at the server's path, else at its root, then the authorization server's metadata (RFC 8414), whose endpoints must be HTTPS (plain HTTP only to this machine) or the sign-in stops; it registers kcode via RFC 7591 dynamic client registration when the server offers it, and opens a browser PKCE flow on an ephemeral loopback port, requesting the scope the server's 401 names, else every scope its protected-resource metadata lists, else none (the order the MCP specification sets), with offline_access and a consent prompt added when the authorization server lists it, so the login gets a refresh token, and naming the server as the RFC 8707 resource (the one the server's protected-resource metadata declares when it covers the server's URL, else that URL; metadata declaring another server stops the sign-in); tokens persist under [oauth."mcp.<server>"] in auth.toml, every (re)connect injects the bearer (an explicit authorization header in the config always wins), a stale token refreshes single-flight against the persisted token endpoint, naming the same resource, and the connection bounces so the login takes effect at once. Cancel a running login with the generic OAuth cancel (mcp.<server> key). A connected server that pushes notifications/tools/list_changed re-lists live and the diff lands as <cp:mcp-tools-changed>. Remote (HTTP/SSE) connections are supervised: a dropped connection reconnects with backoff (5 attempts, 1s doubling to 30s) and re-registers in place, registered tools always invoke the current connection; on exhaustion the server's tools leave the registry (announced), and /mcp and /plugins list it as not connected, until a manual reconnect. Servers can also send the user questions (elicitation/create → the stock question prompt, headed MCP server <name>) and read the project root (roots/list → file://<project root>): both declared at initialize. A question is asked as the agent whose tool call the server is answering: the call whose HTTP reply carries it, or over stdio and SSE the one agent with calls running on the server, so Esc on the session's turn closes only the turn's own; one kcode can't tie to one agent is asked as the server and stays open. kcode requests MCP protocol and works with a server that answers, or; a server answering with any other version has its connection closed. Over HTTP, a reply that is cut off before the answer is picked up where it stopped when the server numbers its events, within the request timeout.
kcode pluginslist | search [<words>…] | install <folder|name> [--approve] [--trust-author] | remove <name> [--yes] | scaffold | validate | test <folder> [--timeout-secs <n>]Plugin management and authoring from the CLI, no session needed: list prints each installed plugin (built-in, user, project and linked scope, plus MCP servers) with its source, loads once for the app for an app plugin, its capabilities and [events] table, or that it declares none, and the hosts your [plugin_grants] lets it fetch from, a plugin you switched off is marked (off), a linked plugin whose folder is gone (missing), a plugin folder whose plugin.toml does not read is named under Problems, and a project you haven't trusted, or that changed since you trusted it, has its plugins and servers marked not loaded, with a line saying why; search <words> and install <name> report that there is no public kcode marketplace and point to install <folder>; install <folder> links a local plugin folder (or the plugin.toml in it) as Settings › Plugins does: the folder stays where it is, config.toml gains its [plugin_links] entry, and a running kcode loads it into its sessions at once, else kcode loads it at its next start, a plugin whose capabilities the install review flags is shown and links only with --approve; remove <name> removes a plugin as Settings › Plugins does: a linked plugin's link goes and its folder stays, and a plugin in a plugins folder is deleted once you answer yes to the question, typed or piped (--yes skips it); its settings and off switch leave config.toml, a running kcode unloads it from its sessions, and a built-in plugin is refused; scaffold emits a working skeleton; validate pre-flights a plugin directory with the same checks a session load runs, the manifest, [capabilities], [events] (including a registration outside the table), schedules, content bundle, and each Lua tool a session would leave out (a name or an argument schema no model accepts), which the check names; test <folder> runs a Lua plugin's own test_*.lua files in kcode's own Lua against a stand-in host and exits 1 when a test fails (Plugin Runtimes, Testing CLI).
kcode configdefaults | check [FILE]kcode config defaults prints every deep-lib [section] with its compiled defaults: the complete power-user config surface, drift-tested against the code. kcode config check [FILE] checks a config file the way kcode reads it, config.toml in the data dir when no file is named: where its TOML stops parsing, each name kcode doesn't read (with the nearest name it does), each value of the wrong type (with the type it needs), and each [keymap] entry that can't be used. It names every problem without quoting the file and exits 1 when it finds one.
kcode upgradeCheck for a newer kcode and download it. With the app running, the app checks: its notification center posts the update and offers the restart, and the command prints the app's answer once the download is done. With no app running, the command checks itself and puts the update in place at once, or, while a kcode process still runs from the install, keeps it for kcode's next start. It reads the signed release index at https://api.kcode.sh/v1/release-index, which must be signed with the release key compiled into the build; the download must be signed by the same developer as the running kcode, or it is refused and nothing is kept. An app install takes the release's app, ~/.cargo/bin/kcode its program. An install your user can't replace prints the download page instead. A debug or dev-release build prints that it doesn't update itself. Exits 0 with an answer, 1 when the check or the swap failed.
kcode trigger <name> <text>[--project <dir>] [--session <title>]Fire an external trigger into a running session: the integration point for CI, cron(8), and sidecars. Dials the daemon socket and injects text as the target session's next turn (queued at the turn boundary when the session is busy): shown in the chat under a trigger · <name> label, never as your message or a hook's, stamped origin="trigger" with the trigger's name for the agent, named in both session exports, and recorded in /control as a <cp:external-trigger> row; prints the daemon's outcome line. When the project declares webhook:<name> hooks, those run instead, each given the text: a hook's prompt takes it in place of {{text}}, or as its own paragraph after a prompt without one, and a run line takes it as its arguments, as /name <text> would. A trigger starts the project's hooks, or loads one saved since they started, when they may run, and while they can't: project hooks turned off, the project untrusted, the hook new or changed since you trusted the project, or no session open in the project; it runs nothing and the outcome line says why, naming the switch when hooks are off. A fire a hook's rate cap drops runs nothing too, and the outcome line names the hook, the limit and its setting; so does a fire whose hooks have no open session to run in, or are concurrency = "drop" hooks still running an earlier fire. Otherwise the outcome line names the hooks that fired. --session <title> runs the trigger in the open session with that title (its hooks too, in place of their own session) and a title no open session has fails the trigger. The command exits 1 when the trigger ran nothing (refused, dropped by a rate cap, or reaching no session) printing why. --project names the project's folder (default: the current folder); a relative path counts from the current folder, and a path through a symlink reaches the same project. Trust is the socket's same-UID boundary: no TCP listener, no auth.
kcode trust [folder][--yes]Trust a project's content from the command line, as Trust & remember does in the app. It trusts the project that holds the folder (the current folder when none is named) lists what the project holds (or, for a project trusted before, what was added or changed since, each change marked) under the trust dialog's headings, shows Trust this project? [y/N], and saves the grant in ~/.kcode/trusted-projects.toml over those items, so the question returns when one is added or changed later. --yes (-y) trusts without a prompt and prints the list; with no terminal for the prompt and no --yes, it lists the items, trusts nothing and exits 1. A project that holds nothing that needs trust, or is already trusted, says so. In the home folder, a folder above it, /, or the folder that holds the data folder, it says there is no project to trust. When the kcode app is running, it takes the grant: its trust questions about the project close and code it held runs. The kcode -p notice and the kcode mcp list and kcode plugins list notes name this command with the project's folder.