Command Line

This page documents KnightCode's built-in command-line commands and options. Run knightcode --help or append --help to a command for the exact interface in your installed version. The top-level help also includes options registered by loaded extensions.

knightcode [options] [--] [@files...] [messages...]
knightcode install <source> [options]
knightcode remove <source> [options]
knightcode uninstall <source> [options]
knightcode update [target] [options]
knightcode list
knightcode config [options]
knightcode auth <check|print-api-key|print-bearer-token> [options]
knightcode mcp <add|remove|list|login|logout> [options]
knightcode app-server [-e <extension>]... [--session-dir <dir>]

Invocation and output

knightcode
knightcode --print "Summarize this repository"
git diff | knightcode --print "Review this change"
knightcode --mode json "Inspect this repository" > events.jsonl

With terminal stdin and stdout, KnightCode opens the terminal UI unless --print, --mode json, or --mode rpc selects another interface. When either stream is redirected and neither JSON nor RPC mode is selected, KnightCode uses print mode. See CLI Integration for choosing between interactive, print, JSON, RPC, and SDK integration.

KnightCode resolves @path from the current working directory. The working directory also controls project configuration, resource discovery, and session grouping.

--print controls whether KnightCode runs once and exits. --mode selects the output interface. --mode text does not force one-shot execution when stdin and stdout are terminals; use --print for that behavior.

RPC mode rejects @file arguments. JSON and RPC modes reserve stdout for protocol records. See JSON Event Stream and RPC Protocol.

Plan before implementing

knightcode --plan
knightcode -p --plan "Plan the authentication refactor"

The built-in --plan extension flag enters enforced plan mode only on initial startup, including when opening a saved session. Later reloads, new sessions, resumes, and forks follow their saved state rather than reapplying the flag. Print mode (-p) writes the submitted Markdown to stdout; implementation requires explicit /plan approve. Incompatible tool filters or active codemode only mode fail startup before any provider request. --no-extensions disables the built-in unless explicitly loaded with -e builtin:plan-mode.

Models

knightcode --model sonnet:high

See Choose a Model for model selection and Providers for credentials.

• --provider <name>
  Restricts --model lookup to one provider. It requires --model.
• --model <pattern>
  Selects by exact ID or fuzzy ID/name match. It accepts provider/id and an optional :<thinking> suffix. If several providers match, KnightCode prefers the one with credentials, otherwise it asks for --provider.
• --api-key <key>
  Uses a non-persistent API-key override. It requires a model selected through --model or --models. It does not choose between providers that offer the same model.
• --thinking <level>
  Sets off, minimal, low, medium, high, xhigh, or max. It overrides a --model suffix and is clamped to the model's capabilities.
• --models <patterns>
  Sets a comma-separated scope for startup and cycling. It accepts exact IDs, fuzzy matches, case-insensitive globs, and optional :<thinking> suffixes. A model offered by several providers is added for each, with a warning.
• --list-models [search]
  Lists available models, optionally filtered by a fuzzy search, then exits.

Sessions

knightcode --continue

See Sessions and Context for resuming, forking, naming, and storing sessions.

• -c, --continue
  Continues the most recent session for the current project.
• -r, --resume
  Opens the session selector.
• --session <path|id>
  Opens by file path, exact ID, or partial ID. KnightCode searches the current project first and offers to fork a cross-project match.
• --session-id <id>
  Opens the exact project session ID or creates it if absent. IDs accept letters, numbers, ., _, and -.
• --fork <path|id>
  Forks an existing session into a new session for the current project.
• --session-dir <dir>
  Overrides storage and lookup. It takes precedence over KNIGHTCODE_CODING_AGENT_SESSION_DIR and the sessionDir setting.
• --no-session
  Uses an in-memory session that is not persisted.
• -n, --name <name>
  Sets the session display name.

Constraints:

• Session IDs must start and end with a letter or number.
• --fork cannot be combined with --session, --continue, --resume, or --no-session.
• --session-id cannot be combined with --session, --continue, or --resume. Combine it with --fork to choose the new ID.

Tools

knightcode --tools read,grep,find,ls --print "Review this project"

See Settings for configuring the default tool selection.

• -t, --tools <list>
  Replaces the default selection with a comma-separated allowlist of built-in, extension, or custom tools. Entries are tool names or patterns where * matches any characters. MCP tools are kept unless an entry starts with mcp__ (see MCP tools). A list of only +name and -name entries is not an allowlist; it changes the default selection instead.
• -xt, --exclude-tools <list>
  Disables comma-separated tool names or patterns after all other selection options, MCP tools included.
• -nbt, --no-builtin-tools
  Disables default built-in tools while retaining extension and custom tools.
• -nt, --no-tools
  Starts with all built-in, extension, custom, and MCP tools disabled.

Default enabled tools are read, bash, edit, and write, unless defaultTools changes them. --tools with plain names replaces the whole selection, so name every tool you want. Like defaultTools, it also accepts a list of only +name and -name entries, which adds tools to or removes them from the default selection: knightcode --tools +codemode,-write keeps the other default tools, enables codemode, and disables write. These entries take exact tool names, not * patterns; use --exclude-tools to disable tools by pattern. Plain names and +name/-name entries cannot be mixed. /reload enables tools newly added to defaultTools, but a tool removed with -name stays removed.

--tools selects the tools declared to the model. It does not remove MCP tools, whose reach is set by their exposure: knightcode --tools read,codemode keeps every MCP tool callable from codemode scripts. An MCP tool that no entry names or matches is never declared directly, whatever its exposure; only tool_search, if listed, can load it. Once an entry starts with mcp__, --tools filters MCP tools too, so this keeps only the tools of the radius server:

knightcode --tools read,bash,codemode,'mcp__radius__*'

The MCP resource tools (list_mcp_resources, list_mcp_resource_templates, read_mcp_resource) count as MCP tools. To remove MCP tools, use --exclude-tools 'mcp__*' or --no-mcp.

The web tools webfetch and websearch and the question tool ask_user are off until enabled with /tools or named here. A tool excluded here stays off whatever /tools says, and one turned off with /tools stays off even when named here.

Built-in extensions add two more tools. They are off by default; the MCP extension turns them on when an MCP server needs them (see MCP). To enable them yourself, name them in --tools or defaultTools.

Enable codemode

To turn on codemode for every session, add it to the default tools in ~/.knightcode/agent/settings.json or a project's .knightcode/settings.json:

{
  "defaultTools": ["+codemode"]
}

This keeps read, bash, edit, and write and adds codemode. For one invocation, add it with --tools:

knightcode --tools +codemode

Codemode is useful without MCP: scripts can run several tool calls in parallel, filter large output before it reaches the model, call classifier models such as TypeSafe's Jev through models.classify() (see Classifier models), and generate images through models.generateImages() (see Image models).

How codemode works

Scripts run in a QuickJS sandbox and reach the other tools through tools.<name>(args). Codemode describes the script API, how tools are listed and found, the store() and models globals, and the limits.

Tool search

tool_search is off by default; enable it with "defaultTools": ["+tool_search"] or --tools. It uses the same ranking as searchTools() over tools that are not declared yet and declares the matches for the next model call. Loaded tools are recorded in the session like other tool changes, so they stay declared on that branch.

Resources

knightcode --extension ./review.ts

See Configuration for conventional directories and project trust, Settings for configured paths, and KnightCode Packages for package sources.

• -e, --extension <path>
  Loads an extension file or directory, or a built-in extension such as builtin:mcp, and is repeatable.
• -ne, --no-extensions
  Disables discovered, configured, and built-in extensions. Explicit -e paths still load, so knightcode -ne -e builtin:mcp keeps only the built-in MCP support.
• --no-mcp
  Disables the built-in MCP support for this run: no servers connect, and there are no MCP tools or /mcp. It does not affect an extension that replaces the built-in MCP support.
• --skill <path>
  Loads a skill file or directory and is repeatable.
• -ns, --no-skills
  Disables discovered and configured skills. Explicit --skill paths still load.
• --prompt-template <path>
  Loads a prompt-template file or directory and is repeatable.
• -np, --no-prompt-templates
  Disables discovered and configured templates. Explicit --prompt-template paths still load.
• --theme <path>
  Loads a theme file or directory and is repeatable.
• --use-theme <name[/name]>
  Selects the initial interactive theme for this run.
• --no-themes
  Disables discovered and configured themes. Explicit --theme paths still load.
• -nc, --no-context-files
  Disables AGENTS.md and CLAUDE.md discovery.

Resource paths apply only to the current process. Relative paths resolve from the current working directory.

Prompts and process

knightcode --append-system-prompt ./instructions.md

See Configuration for saved configuration, Security for project trust, and Environment Variables for process controls.

• --system-prompt <text|path>
  Replaces the default system prompt with text or the contents of an existing file.
• --append-system-prompt <text|path>
  Appends text or an existing file to the system prompt and is repeatable.
• --tui-mode <mode>
  Uses fullscreen (default) or regular terminal mode.
• --verbose
  Shows verbose interactive startup information, overriding quietStartup.
• -a, --approve
  Trusts project-local configuration and resources for this process.
• -na, --no-approve
  Ignores trust-gated project-local configuration and resources for this process.
• --offline
  Disables automatic network activity, including model catalog refreshes. Equivalent to KNIGHTCODE_OFFLINE=1.
• -h, --help
  Shows help, including flags registered by loaded extensions, then exits.
• -v, --version
  Shows the KnightCode version, then exits.

Extensions may register additional long-form options. Unknown short options are rejected.

Package commands

knightcode install npm:@scope/package

See KnightCode Packages for source formats, filtering, installation, and project scope.

Common tasks

Add --local or -l to install, remove, uninstall, or config to use project settings instead of global settings.

Update KnightCode or packages

Running knightcode update without a target updates KnightCode itself.

Interactive sessions check for updates at startup and hourly. Installer-managed installs, writable global package manager installs, and downloaded release binaries update in the background. A right-aligned line directly above the input shows Downloading vX.Y.Z, then Restart for vX.Y.Z in green. Errors are red; waiting for another terminal is yellow. Exit when convenient and relaunch; use the displayed restart command to continue the saved session. Active work is never restarted automatically.

The script installer stages and verifies a separate release before changing the launcher, retaining the version that open sessions use. Global package manager installs update in place, and the new version is started once to check it before the update reports success. A downloaded standalone binary is replaced from the matching GitHub release archive, checked against its SHA256SUMS, and smoke-tested before any file moves; files next to it that the release does not ship are left alone. These updates run in a separate process that can finish after you exit. Other open sessions keep running, but files on disk change under them; after an in-place update, a session warns you to restart if code it loads on demand fails. On Windows, automatic global updates support npm and pnpm. Source checkouts, non-writable installs, and package renames show manual update notices instead.

Failed background updates show a manual retry command and are retried on a later check. Automatic updates are on by default. To retain update notices without automatic downloads, open /settings and set Automatic updates to false, or add "autoUpdate": false to your user-level ~/.knightcode/agent/settings.json (Windows: %USERPROFILE%\.knightcode\agent\settings.json). Project settings cannot override this preference. See Disable automatic updates for a complete example and reload instructions.

Alternatively, set KNIGHTCODE_DISABLE_AUTO_UPDATE=1 in your shell or operating system environment before launching KnightCode; it overrides autoUpdate: true. KNIGHTCODE_SKIP_VERSION_CHECK=1 suppresses both automatic checks and downloads. Explicit knightcode update remains available regardless of the setting or either variable. Offline, print, JSON, and RPC sessions do not start background updates.

Add --force to reinstall KnightCode when the selected update includes KnightCode.

Aliases and command options

• knightcode uninstall <source> is an alias for knightcode remove <source>.
• knightcode update --self, knightcode update self, and knightcode update knightcode are aliases for knightcode update.
• knightcode update --extension <source> is an alias for knightcode update <source>.
• -a, --approve trusts project-local files for one command. -na, --no-approve ignores trust-gated project-local files.
• Append -h or --help to a command for its exact usage and option constraints.

Credential commands

knightcode auth check --provider openai --json

Authentication commands require --provider <provider> or --model <model>. See Providers for supported methods.

Credential-printing commands write secrets to stdout.

App server

knightcode app-server hosts many threads in one headless process. It reads newline-delimited JSON requests from stdin, writes protocol messages to stdout, and logs to stderr. It exits when stdin closes, unloading sessions and releasing their locks. See App Server for the handshake, threads, approvals, payload retrieval, and limits.

MCP commands

These commands work outside a session, so agents can run them through bash. See MCP Servers.

add and remove change ~/.knightcode/agent/mcp.json, or .knightcode/mcp.json in the current directory with --local (-l). add also takes --exposure <mode> (see Exposure) and --description <text> and does not connect; run knightcode mcp list to check the server.

Project .knightcode/mcp.json files are only read for projects that are already trusted.