@knightcodeai/cli 0.17.3 → 0.18.0

package/docs/providers.md

@@ -0,0 +1,282 @@
+# Providers
+
+Most hosted providers support one or both of these authentication methods:
+
+- Sign in through a browser or device flow backed by OAuth.
+- Provide an API key.
+
+Use `/login [provider]` to see the methods supported by a provider. Amazon Bedrock and Google Vertex AI can also use ambient cloud credentials.
+
+## Authenticate interactively
+
+Run `/login` and select a provider. KnightCode guides you through its OAuth or API-key flow and saves the resulting credential in [`auth.json`](configuration.md#agent-directory).
+
+On a remote or headless machine, an OAuth callback may not reach the local process. When prompted, paste the final redirect URL or authorization code back into KnightCode.
+
+Run `/logout` and select a provider to remove its stored credential. This does not unset environment variables, remove authentication from `models.json`, or revoke the credential at the provider.
+
+`auth.json` can contain API keys and OAuth tokens. Keep it private and do not commit it.
+
+## Check subscription usage
+
+Run `/usage` in the interactive terminal to see remaining allowance and reset
+times reported by connected Claude (`anthropic`), OpenAI Codex (legacy)
+(`openai-codex`) and Grok (`xai`) subscription sign-ins. For Grok, run `/login xai`
+and choose "Sign in with SuperGrok or X Premium". The figures cover the whole
+account, not just the current KnightCode session. Other subscription sign-ins,
+including the current `openai` ChatGPT sign-in, are listed as unsupported.
+
+Claude shows extra usage first. KnightCode draws from extra usage rather than
+Claude's plan limits. The extra-usage percentage is account-wide and includes
+usage outside KnightCode; it does not measure this client's consumption alone.
+The plan windows are shown only for reference. Codex windows describe the plan
+allowance. Accounts with purchased credits can keep working at 0% remaining.
+
+Grok shows the weekly or monthly credit pool and, when reported, the Grok Build
+and API shares. These product lines are shares of the same pool, not separate
+allowances. Accounts with purchased credits or pay-as-you-go can keep working
+at 0% remaining. An xAI API key is billed separately and is not shown.
+
+`unavailable` means the provider did not report a valid value. A window whose
+reset has passed asks you to run `/usage` again instead of assuming the allowance
+has refilled. Each opening fetches once; there is no polling or Refresh key.
+Rate-limited providers are not requested again until their cooldown expires.
+
+The panel is read-only: it never buys credits or changes provider settings.
+It is available only in the interactive terminal, not RPC, print, JSON, or IDE
+engine sessions. It uses your configured credential store and the existing
+OAuth refresh path. Usage requests go only to the providers' fixed usage
+endpoints, not a configured model endpoint.
+
+Disable it with `"extensions": ["-builtin:usage"]` in settings, or disable all
+extensions with `--no-extensions`.
+
+## Use an API key from the environment
+
+Environment variables are useful in CI and anywhere KnightCode should not store the key. Set the variable before starting KnightCode:
+
+```bash
+export ANTHROPIC_API_KEY=sk-ant-...
+knightcode
+```
+
+This table covers providers with a single primary API-key variable. Providers that need additional configuration or support ambient credentials are covered under [Provider Specific Config](#provider-specific-config).
+
+| Provider | Environment variable |
+|---|---|
+| Anthropic | `ANTHROPIC_API_KEY` |
+| AgentRouter | `AGENTROUTER_API_KEY` |
+| Ant Ling | `ANT_LING_API_KEY` |
+| OpenAI | `OPENAI_API_KEY` |
+| DeepSeek | `DEEPSEEK_API_KEY` |
+| NVIDIA NIM | `NVIDIA_API_KEY` |
+| Google Gemini | `GEMINI_API_KEY` |
+| GitHub Copilot | `COPILOT_GITHUB_TOKEN` |
+| Mistral | `MISTRAL_API_KEY` |
+| Groq | `GROQ_API_KEY` |
+| Cerebras | `CEREBRAS_API_KEY` |
+| xAI | `XAI_API_KEY` |
+| OpenRouter | `OPENROUTER_API_KEY` |
+| Vercel AI Gateway | `AI_GATEWAY_API_KEY` |
+| ZAI Coding Plan (Global) | `ZAI_API_KEY` |
+| ZAI Coding Plan (China) | `ZAI_CODING_CN_API_KEY` |
+| OpenCode Zen and Go | `OPENCODE_API_KEY` |
+| Radius | `RADIUS_API_KEY` |
+| TypeSafe ([classifier models](models.md#use-classifier-models)) | `TYPESAFE_API_KEY` |
+| Hugging Face | `HF_TOKEN` |
+| Fireworks | `FIREWORKS_API_KEY` |
+| Together AI | `TOGETHER_API_KEY` |
+| Baseten | `BASETEN_API_KEY` |
+| Kimi For Coding | `KIMI_API_KEY` |
+| Meta | `META_API_KEY` |
+| MiniMax | `MINIMAX_API_KEY` |
+| MiniMax (China) | `MINIMAX_CN_API_KEY` |
+| Moonshot AI (Global and China) | `MOONSHOT_API_KEY` |
+| Qwen Token Plan and Individual | `QWEN_TOKEN_PLAN_API_KEY` |
+| Qwen Token Plan (China) | `QWEN_TOKEN_PLAN_CN_API_KEY` |
+| Xiaomi MiMo | `XIAOMI_API_KEY` |
+| Xiaomi MiMo Token Plan (China) | `XIAOMI_TOKEN_PLAN_CN_API_KEY` |
+| Xiaomi MiMo Token Plan (Amsterdam) | `XIAOMI_TOKEN_PLAN_AMS_API_KEY` |
+| Xiaomi MiMo Token Plan (Singapore) | `XIAOMI_TOKEN_PLAN_SGP_API_KEY` |
+
+Anthropic also recognizes `ANTHROPIC_OAUTH_TOKEN` as an API credential and `ANTHROPIC_AUTH_TOKEN` as bearer authentication.
+
+With no key or token set, Anthropic uses workload identity federation when `ANTHROPIC_FEDERATION_RULE_ID`, `ANTHROPIC_ORGANIZATION_ID` and `ANTHROPIC_IDENTITY_TOKEN_FILE` are set: the Anthropic SDK exchanges the identity token for a short-lived access token and refreshes it itself (re-reading the identity token file, so keep that file fresh for long sessions). `ANTHROPIC_SERVICE_ACCOUNT_ID` and `ANTHROPIC_WORKSPACE_ID` are passed through when set.
+
+## Load an API key from a command
+
+To use a secret manager without writing the resolved key to disk, set a provider's `key` in `auth.json` to a command prefixed with `!`:
+
+```json
+{
+  "anthropic": {
+    "type": "api_key",
+    "key": "!security find-generic-password -ws 'anthropic'"
+  }
+}
+```
+
+KnightCode runs the command when the key is first needed and caches its standard output for the process lifetime. Empty output, a timeout, or a nonzero exit leaves the key unresolved until KnightCode restarts.
+
+## Provider Specific Config
+
+The providers below have additional setup, need additional settings, or can use credentials supplied by their platform.
+
+A stored API-key credential can include an `env` object. Its values take priority over the process environment for that provider:
+
+```json
+{
+  "cloudflare-workers-ai": {
+    "type": "api_key",
+    "key": "...",
+    "env": {
+      "CLOUDFLARE_ACCOUNT_ID": "account-id"
+    }
+  }
+}
+```
+
+### Radius
+
+Radius is a service crafted for KnightCode by the builders of KnightCode, Earendil Works. It provides a customizable AI gateway with organization-level controls and analytics built in, and artifacts for sharing what you create with KnightCode.
+
+To get started, run `/login radius` in KnightCode. This adds Radius as a provider, and its models appear in `/model` like any other provider's.
+
+Radius also has an MCP server, so KnightCode can manage Radius for you.
+
+Radius is currently in early alpha and evolving quickly. See [radius.earendil.com](https://radius.earendil.com) for more.
+
+Radius authentication uses its gateway catalog and caches refreshed model metadata for later offline startup. A custom Radius gateway configured in `models.json` uses its own catalog rather than inheriting the public `radius.pi.dev` catalog.
+
+### OpenRouter
+
+Authenticate with `/login openrouter` or `OPENROUTER_API_KEY`.
+
+With a key, KnightCode lists only the OpenRouter chat models that key may use, with the key's context size, max output, and prices. These come from OpenRouter's `/models/user` endpoint and reflect guardrails and provider restrictions set in OpenRouter. Image and classifier models are not filtered.
+
+KnightCode refreshes the list in the background at startup in interactive mode, when `/model` opens, after `/login`, and on `knightcode update --models`. The last list is saved and used offline and in `knightcode -p` and RPC mode. After switching keys outside `/login`, the previous key's list stays until the next refresh.
+
+Regional endpoints filter models to their region. To use one, set the base URL in [`models.json`](models.md#configure-a-compatible-endpoint):
+
+```json
+{
+  "providers": {
+    "openrouter": { "baseUrl": "https://us.openrouter.ai/api/v1" }
+  }
+}
+```
+
+If the base URL rejects the key at `/models/user` or does not have that endpoint, for example a proxy configured as the OpenRouter base URL, KnightCode lists every OpenRouter model.
+
+### Azure OpenAI
+
+The provider ID is `azure` (formerly `azure-openai-responses`). Use it as the key in `auth.json`, `models.json`, and `settings.json`, and in model references such as `--model azure/gpt-5.4`.
+
+The `azure` provider serves OpenAI models through the Responses API and Microsoft Foundry models through Chat Completions, such as `azure/deepseek-v4-pro`.
+
+Set an API key plus either a base URL or resource name:
+
+```bash
+export AZURE_OPENAI_API_KEY=...
+export AZURE_OPENAI_BASE_URL=https://your-resource.ai.azure.com
+# Or:
+export AZURE_OPENAI_RESOURCE_NAME=your-resource
+```
+
+Resource root URLs under `ai.azure.com`, `cognitiveservices.azure.com`, and `openai.azure.com` are normalized to the OpenAI API path.
+
+KnightCode sends the model ID as the deployment name. If a deployment has a different name, map it with `AZURE_OPENAI_DEPLOYMENT_NAME_MAP`. The map applies to both the Responses API and Foundry Chat Completions:
+
+```bash
+export AZURE_OPENAI_DEPLOYMENT_NAME_MAP=gpt-5.4=my-gpt-deployment,deepseek-v4-pro=my-deepseek
+```
+
+`AZURE_OPENAI_API_VERSION` overrides the API version for OpenAI models (default `v1`).
+
+To use a Foundry model that KnightCode does not include, add it under `azure` in [`models.json`](models.md#configure-a-compatible-endpoint) with `api: "openai-completions"`. Custom models require a `baseUrl`; `AZURE_OPENAI_BASE_URL` and `AZURE_OPENAI_RESOURCE_NAME` take priority over it when set:
+
+```json
+{
+  "providers": {
+    "azure": {
+      "baseUrl": "https://your-resource.services.ai.azure.com",
+      "models": [
+        { "id": "your-deployment", "api": "openai-completions" }
+      ]
+    }
+  }
+}
+```
+
+### Amazon Bedrock
+
+Bedrock can use a bearer token or an ambient AWS credential source:
+
+```bash
+# Named profile
+export AWS_PROFILE=your-profile
+
+# IAM keys
+export AWS_ACCESS_KEY_ID=AKIA...
+export AWS_SECRET_ACCESS_KEY=...
+# Required for temporary credentials
+export AWS_SESSION_TOKEN=...
+
+# Bedrock bearer token
+export AWS_BEARER_TOKEN_BEDROCK=...
+
+# Region, when not supplied by the profile or AWS SDK configuration
+export AWS_REGION=us-west-2
+# AWS_DEFAULT_REGION is also supported
+```
+
+KnightCode also supports ECS task credentials and IRSA through the standard `AWS_CONTAINER_CREDENTIALS_*` and `AWS_WEB_IDENTITY_TOKEN_FILE` variables.
+
+### Cloudflare AI Gateway
+
+The gateway requires a token, account ID, and gateway ID:
+
+```bash
+export CLOUDFLARE_API_KEY=...
+export CLOUDFLARE_ACCOUNT_ID=...
+export CLOUDFLARE_GATEWAY_ID=...
+```
+
+The account and gateway IDs can come from the process environment or the credential's `env` object in `auth.json`.
+
+`CLOUDFLARE_API_KEY` authenticates KnightCode to the gateway. Upstream access can use Cloudflare unified billing, credentials stored in the gateway, or an `Authorization` header configured for the provider in `models.json`.
+
+### Cloudflare Workers AI
+
+Workers AI requires a token and account ID:
+
+```bash
+export CLOUDFLARE_API_KEY=...
+export CLOUDFLARE_ACCOUNT_ID=...
+```
+
+The account ID can also be stored in the credential's `env` object.
+
+### Google Vertex AI
+
+Use a Google Cloud API key:
+
+```bash
+export GOOGLE_CLOUD_API_KEY=...
+```
+
+To use Application Default Credentials, configure a project and location:
+
+```bash
+export GOOGLE_CLOUD_PROJECT=your-project
+# GCLOUD_PROJECT is also supported
+export GOOGLE_CLOUD_LOCATION=us-central1
+```
+
+Then authenticate:
+
+```bash
+gcloud auth application-default login
+```
+
+To use a service-account key file instead, set `GOOGLE_APPLICATION_CREDENTIALS` along with the project and location.

package/docs/quickstart.md

@@ -0,0 +1,128 @@
+# Quickstart
+
+KnightCode runs in your terminal and works with files on your machine. To use it, you need access to a model through a supported provider. This can be a subscription, an API key, or a local model.
+
+For native Windows setup, read [Windows Setup](windows.md). For Android, read [Termux Setup](termux.md).
+
+## 1. Install KnightCode
+
+On macOS or Linux, you can use the installer. It installs Node.js 22.19 or newer if Node is missing or older, then installs KnightCode for your user:
+
+```bash
+curl -fsSL https://knightcode.dev/install.sh | sh
+```
+
+Alternatively, install KnightCode from npm. This requires Node.js 22.19 or newer:
+
+```bash
+npm install -g --ignore-scripts @knightcodeai/cli
+```
+
+KnightCode does not require dependency lifecycle scripts for a normal npm installation.
+
+Verify the installation:
+
+```bash
+knightcode --version
+```
+
+Supported installations download updates in the background during interactive
+sessions. When the green **Restart for vX.Y.Z** notice appears above the input,
+exit and relaunch when convenient. You can also run `knightcode update` manually. See
+[Updating KnightCode](cli.md#update-knightcode-or-packages) for supported installs
+and how to disable automatic downloads.
+
+## 2. Start KnightCode
+
+Change to the folder you want KnightCode to work with, then start it:
+
+```bash
+cd /path/to/folder
+knightcode
+```
+
+The working folder helps KnightCode discover relevant files, instructions, and configuration. KnightCode also uses it to group saved sessions.
+
+<p align="center"><img src="images/interactive-mode.png" alt="KnightCode running in a terminal with a conversation, input editor, and status footer" width="750"></p>
+
+The interface shows your conversation, an editor for prompts and commands, and a footer with the current folder, model, and session status. See [Use KnightCode in the terminal](usage.md) to learn how to add files, run commands, direct ongoing work, and manage results.
+
+## 3. Choose a model
+
+A **model** generates KnightCode's responses. A **provider** is the service or account KnightCode uses to access that model.
+
+In KnightCode, run:
+
+```text
+/login
+```
+
+Choose a provider, then follow the prompts to use a subscription or store an API key. Run `/model` afterward if you want to select a different available model.
+
+See [Choose a model and provider](models.md) for supported providers, environment-variable authentication, local models, and custom endpoints.
+
+## 4. Give KnightCode a task
+
+KnightCode shows each file read, search, command, and edit it performs. It does not ask before every tool call.
+
+Enter a task that matches your work, for example:
+
+```text
+Summarize @meeting-notes.md and save the action items to action-items.md.
+```
+
+```text
+Explain how this repository is structured and how to run its checks.
+```
+
+```text
+Compare @previous.csv with @current.csv and summarize the important changes.
+```
+
+Type `@` in the editor to search for a file instead of entering its full path. When KnightCode finishes, review its response and any changed files. Use version control or backups for important work. For untrusted or unattended work, use a container or another sandbox. See [Security](security.md).
+
+## Continue later
+
+KnightCode saves sessions automatically. Exit KnightCode, then resume the most recent session for the same working folder with:
+
+```bash
+knightcode --continue
+```
+
+Use `/resume` to choose another saved session. See [Continue or branch a session](sessions.md) for session naming, branching, compaction, export, and sharing.
+
+## Next steps
+
+- [Use KnightCode interactively](usage.md) to learn input, commands, shortcuts, and queued messages.
+- [Add instructions](configuration.md#context-files) that KnightCode should follow whenever it works in a folder.
+- [Choose a model and provider](models.md).
+
+### Choose how to customize KnightCode
+
+Start with the least powerful mechanism that meets your need:
+
+| Need | Start with |
+|---|---|
+| Give KnightCode persistent instructions for a folder | [`AGENTS.md`](configuration.md#context-files) |
+| Reuse a prompt from the `/` menu | [Prompt template](prompt-templates.md) |
+| Add task-specific instructions and supporting files | [Skill](skills.md) |
+| Add executable tools, commands, or event handlers | [Extension](extensions.md) |
+| Build a custom terminal component | [Terminal UI](tui.md) |
+| Connect an unsupported model service | [Custom provider](custom-provider.md) |
+| Install or distribute several resources | [KnightCode package](packages.md) |
+
+## Uninstall KnightCode
+
+If you installed KnightCode with npm, run:
+
+```bash
+npm uninstall -g @knightcodeai/cli
+```
+
+If you used the installer, run it again and choose **Uninstall KnightCode**:
+
+```bash
+curl -fsSL https://knightcode.dev/install.sh | sh
+```
+
+Neither method removes configuration, credentials, sessions, or installed KnightCode packages from `~/.knightcode/agent/`.

package/docs/remote.md

@@ -0,0 +1,87 @@
+# Remote sessions
+
+`/remote` publishes the session running in your terminal to the web, so you can
+watch it and reply from another device. The terminal keeps working normally.
+
+## Getting started
+
+Run `/remote`. The first time, a sign-in screen opens your browser on the
+approval page and shows an eight-character code: sign in with GitHub, check the
+page shows the same code, and approve. Escape cancels. The credential is stored
+in `~/.knightcode/remote-auth.json` and reused afterwards, and the screen also
+prints the URL for a headless box where nothing launched. Once the browser
+approves, the screen confirms it and continues on enter, or by itself a few
+seconds later.
+
+Once signed in, `/remote` prints a link. You do not have to copy it: open
+<https://remote.knightcode.dev> on your phone and the session appears in the
+list.
+
+## The web app
+
+The list shows every session you have published, newest first, with its state:
+**Working** while a turn is running in the terminal, **Connected** while the
+terminal is attached and idle, **Disconnected** once it has gone. Filter it to
+active or past sessions from the menu on the right.
+
+Open a session to read the transcript. Runs of tool calls are folded into one
+line such as _Ran 2 commands, created a file_; tap it to list the calls, and
+tap a call to see what it did — the command and its output, the file and its
+content, the diff an edit made.
+
+The composer sends replies to the terminal. Type `/` to list the slash commands
+the terminal can run from a message: extension commands, skills and prompt
+templates. Built-in commands that open a terminal UI, such as `/model`, are not
+offered.
+
+The menu in the session's top-right corner copies the link or deletes the
+session from the relay.
+
+## Commands
+
+| Command | Effect |
+| --- | --- |
+| `/remote` | Toggle publishing: start and print the link, or pause. Pausing keeps the room readable, and the next `/remote` resumes the same link |
+| `/remote status` | Show the link and how many viewers are connected |
+| `/remote stop` | Stop publishing and delete the room |
+| `/remote logout` | Revoke the stored account credential and delete it locally |
+
+`/remote` runs in the interactive terminal only. In `--print`, RPC and JSON
+modes it reports that and does nothing.
+
+## What the remote can and cannot do
+
+A viewer can read the transcript, send prompts, run the slash commands listed
+above, and stop the current turn. Prompts arrive as ordinary user messages and
+appear in your terminal; `/remote` itself is never offered to a viewer.
+
+A viewer cannot end your session, quit KnightCode, switch sessions, or change
+model. Closing the browser tab, losing signal, or losing the relay does nothing
+to the terminal. Your session ends only when you end it.
+
+If the relay becomes unreachable the command does not fail: it reconnects with
+backoff indefinitely, the footer shows `remote retrying`, and the agent carries
+on working.
+
+## Privacy and retention
+
+Room contents pass through and are briefly stored by the relay so a device that
+reconnects can catch up. That includes tool output, which can contain secrets if
+a command prints them. Nothing is redacted: anything visible in your terminal is
+visible in the room while it lives. Only the account that created a room can
+read it.
+
+A room stays readable as a past session for 30 days after the terminal
+disconnects, and is deleted then, on `/remote stop`, or when you delete it from
+the web app. Stored history is capped at 8 MB per room; older content is
+dropped as the session grows. Images are not mirrored in either direction — an
+image in the transcript appears as a placeholder recording its type and size.
+
+## Configuration
+
+| Environment variable | Default | Effect |
+| --- | --- | --- |
+| `KNIGHTCODE_REMOTE_RELAY` | `https://remote.knightcode.dev` | Relay origin to publish to |
+| `KNIGHTCODE_REMOTE_CONFIG_DIR` | `~/.knightcode` | Directory holding `remote-auth.json` |
+
+`/remote` refuses to start when `KNIGHTCODE_OFFLINE` is set.