@knightcodeai/cli-linux-x64 0.9.1 → 0.9.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (45) hide show
  1. package/bin/CHANGELOG.md +50 -0
  2. package/bin/README.md +52 -19
  3. package/bin/docs/cli-integration.md +106 -0
  4. package/bin/docs/cli.md +270 -0
  5. package/bin/docs/compaction.md +56 -37
  6. package/bin/docs/configuration.md +46 -0
  7. package/bin/docs/containerization.md +86 -54
  8. package/bin/docs/custom-provider.md +132 -785
  9. package/bin/docs/docs.json +143 -103
  10. package/bin/docs/environment-variables.md +5 -4
  11. package/bin/docs/extensions.md +134 -2956
  12. package/bin/docs/how-knightcode-works.md +49 -0
  13. package/bin/docs/index.md +24 -69
  14. package/bin/docs/json.md +193 -65
  15. package/bin/docs/keybindings.md +56 -101
  16. package/bin/docs/llama-cpp.md +3 -3
  17. package/bin/docs/message-types.md +261 -0
  18. package/bin/docs/models.md +64 -547
  19. package/bin/docs/packages.md +66 -167
  20. package/bin/docs/prompt-templates.md +31 -68
  21. package/bin/docs/providers.md +103 -241
  22. package/bin/docs/quickstart.md +61 -106
  23. package/bin/docs/rpc-commands.md +854 -0
  24. package/bin/docs/rpc-extension-ui.md +200 -0
  25. package/bin/docs/rpc.md +129 -1556
  26. package/bin/docs/sdk.md +76 -1160
  27. package/bin/docs/security.md +70 -32
  28. package/bin/docs/session-format.md +25 -216
  29. package/bin/docs/sessions.md +38 -143
  30. package/bin/docs/settings.md +111 -389
  31. package/bin/docs/shell-aliases.md +85 -5
  32. package/bin/docs/skills.md +51 -189
  33. package/bin/docs/slash-commands.md +63 -0
  34. package/bin/docs/terminal-setup.md +107 -79
  35. package/bin/docs/termux.md +74 -83
  36. package/bin/docs/themes.md +68 -280
  37. package/bin/docs/tmux.md +31 -39
  38. package/bin/docs/tui.md +69 -923
  39. package/bin/docs/usage.md +79 -286
  40. package/bin/docs/windows.md +43 -17
  41. package/bin/export-html/template.js +6 -1
  42. package/bin/knightcode +2 -2
  43. package/bin/package.json +6 -6
  44. package/package.json +1 -1
  45. package/bin/docs/development.md +0 -71
package/bin/docs/providers.md CHANGED
@@ -1,326 +1,188 @@
1
- # Providers
1
+ # Provider Authentication
2
2
 
3
- KnightCode supports subscription-based providers via OAuth and API key providers via environment variables or auth file. Built-in catalogs ship with knightcode; configured providers may refresh newer catalogs and cache them in `~/.knightcode/agent/models-store.json` for offline use.
3
+ Most hosted providers support one or both of these authentication methods:
4
4
 
5
- ## Table of Contents
5
+ - Sign in through a browser or device flow backed by OAuth.
6
+ - Provide an API key.
6
7
 
7
- - [Subscriptions](#subscriptions)
8
- - [API Keys](#api-keys)
9
- - [Auth File](#auth-file)
10
- - [Cloud Providers](#cloud-providers)
11
- - [llama.cpp](#llamacpp)
12
- - [Custom Providers](#custom-providers)
13
- - [Resolution Order](#resolution-order)
8
+ Use `/login [provider]` to see the methods supported by a provider. Amazon Bedrock and Google Vertex AI can also use ambient cloud credentials.
14
9
 
15
- ## Subscriptions
10
+ ## Authenticate interactively
16
11
 
17
- Use `/login` in interactive mode, then select a provider:
12
+ 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).
18
13
 
19
- - ChatGPT Plus/Pro (Codex)
20
- - Claude Pro/Max
21
- - GitHub Copilot
22
- - xAI (Grok/X subscription)
23
- - Meta (Muse subscription)
24
- - OpenRouter (OAuth-minted API key billed from OpenRouter credits)
25
- - Radius
14
+ 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.
26
15
 
27
- Use `/logout` to clear credentials. Tokens are stored in `~/.knightcode/agent/auth.json` and auto-refresh when expired. OpenRouter instead mints a user-controlled API key that does not expire automatically.
16
+ 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.
28
17
 
29
- ### OpenAI Codex
18
+ `auth.json` can contain API keys and OAuth tokens. Keep it private and do not commit it.
30
19
 
31
- - Requires ChatGPT Plus or Pro subscription
32
- - Officially endorsed by OpenAI: [Codex for OSS](https://developers.openai.com/community/codex-for-oss)
20
+ 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.
33
21
 
34
- ### Claude Pro/Max
22
+ ## Use an API key from the environment
35
23
 
36
- Anthropic subscription auth is active for Claude Pro/Max accounts. Third-party harness usage draws from [extra usage](https://claude.ai/settings/usage) and is billed per token, not against Claude plan limits.
37
-
38
- ### GitHub Copilot
39
-
40
- - Press Enter for github.com, or enter your GitHub Enterprise Server domain
41
- - If you get "model not supported", enable it in VS Code: Copilot Chat → model selector → select model → "Enable"
42
-
43
- ### xAI (Grok/X subscription)
44
-
45
- - Run `/login xai`, then select **Use a subscription**
46
- - `XAI_API_KEY` remains available through **Use an API key**
47
-
48
- ### Meta (Muse subscription)
49
-
50
- - Run `/login meta`, then select **Sign in with Meta** to open the device authorization flow
51
- - The login mints a Model API key that is re-minted automatically about once a day
52
- - `META_API_KEY` remains available through **Use an API key**
53
-
54
- ### OpenRouter
55
-
56
- - Run `/login openrouter`, then select **Sign in with OpenRouter** to open the OpenRouter PKCE authorization flow
57
- - The authorization creates a user-controlled OpenRouter API key billed from your OpenRouter credits
58
- - On remote/headless machines (e.g. over SSH) the browser cannot reach the loopback callback; paste the final redirect URL (or the authorization code) into the login prompt instead
59
- - `OPENROUTER_API_KEY` remains available through **Use an API key**
60
-
61
- ### Radius
62
-
63
- Radius is a `knightcode-messages` gateway. KnightCode ships the public Radius model catalog for immediate and offline model lookup, then overlays it with the effective gateway catalog after authentication. `/login radius` stores OAuth tokens in `auth.json`; refreshed catalogs are cached in `models-store.json`. Custom Radius gateways can be declared in `models.json` with `"oauth": "radius"` and a gateway `baseUrl`; they do not inherit the public `radius.pi.dev` catalog.
64
-
65
- ## API Keys
66
-
67
- ### Environment Variables or Auth File
68
-
69
- Use `/login` in interactive mode and select a provider to store an API key in `auth.json`, or set credentials via environment variable:
24
+ Environment variables are useful in CI and anywhere KnightCode should not store the key. Set the variable before starting KnightCode:
70
25
 
71
26
  ```bash
72
27
  export ANTHROPIC_API_KEY=sk-ant-...
73
28
  knightcode
74
29
  ```
75
30
 
76
- | Provider | Environment Variable | `auth.json` key |
77
- |----------|----------------------|------------------|
78
- | Anthropic | `ANTHROPIC_API_KEY` | `anthropic` |
79
- | AgentRouter | `AGENTROUTER_API_KEY` | `agentrouter` |
80
- | Ant Ling | `ANT_LING_API_KEY` | `ant-ling` |
81
- | Azure OpenAI Responses | `AZURE_OPENAI_API_KEY` | `azure-openai-responses` |
82
- | OpenAI | `OPENAI_API_KEY` | `openai` |
83
- | DeepSeek | `DEEPSEEK_API_KEY` | `deepseek` |
84
- | NVIDIA NIM | `NVIDIA_API_KEY` | `nvidia` |
85
- | Google Gemini | `GEMINI_API_KEY` | `google` |
86
- | Amazon Bedrock | `AWS_BEARER_TOKEN_BEDROCK` | `amazon-bedrock` |
87
- | Mistral | `MISTRAL_API_KEY` | `mistral` |
88
- | Groq | `GROQ_API_KEY` | `groq` |
89
- | Cerebras | `CEREBRAS_API_KEY` | `cerebras` |
90
- | Cloudflare AI Gateway | `CLOUDFLARE_API_KEY` (+ `CLOUDFLARE_ACCOUNT_ID`, `CLOUDFLARE_GATEWAY_ID`) | `cloudflare-ai-gateway` |
91
- | Cloudflare Workers AI | `CLOUDFLARE_API_KEY` (+ `CLOUDFLARE_ACCOUNT_ID`) | `cloudflare-workers-ai` |
92
- | xAI | `XAI_API_KEY` | `xai` |
93
- | OpenRouter | `OPENROUTER_API_KEY` | `openrouter` |
94
- | Vercel AI Gateway | `AI_GATEWAY_API_KEY` | `vercel-ai-gateway` |
95
- | ZAI Coding Plan (Global) | `ZAI_API_KEY` | `zai` |
96
- | ZAI Coding Plan (China) | `ZAI_CODING_CN_API_KEY` | `zai-coding-cn` |
97
- | OpenCode Zen | `OPENCODE_API_KEY` | `opencode` |
98
- | OpenCode Go | `OPENCODE_API_KEY` | `opencode-go` |
99
- | Radius | `RADIUS_API_KEY` | `radius` |
100
- | Hugging Face | `HF_TOKEN` | `huggingface` |
101
- | Fireworks | `FIREWORKS_API_KEY` | `fireworks` |
102
- | Together AI | `TOGETHER_API_KEY` | `together` |
103
- | Baseten | `BASETEN_API_KEY` | `baseten` |
104
- | Kimi For Coding | `KIMI_API_KEY` | `kimi-coding` |
105
- | Meta | `META_API_KEY` | `meta` |
106
- | MiniMax | `MINIMAX_API_KEY` | `minimax` |
107
- | MiniMax (China) | `MINIMAX_CN_API_KEY` | `minimax-cn` |
108
- | Qwen Token Plan (existing catalog) | `QWEN_TOKEN_PLAN_API_KEY` | `qwen-token-plan` |
109
- | Qwen Token Plan (Individual) | `QWEN_TOKEN_PLAN_API_KEY` | `qwen-token-plan-individual` |
110
- | Qwen Token Plan (China) | `QWEN_TOKEN_PLAN_CN_API_KEY` | `qwen-token-plan-cn` |
111
- | Xiaomi MiMo | `XIAOMI_API_KEY` | `xiaomi` |
112
- | Xiaomi MiMo Token Plan (China) | `XIAOMI_TOKEN_PLAN_CN_API_KEY` | `xiaomi-token-plan-cn` |
113
- | Xiaomi MiMo Token Plan (Amsterdam) | `XIAOMI_TOKEN_PLAN_AMS_API_KEY` | `xiaomi-token-plan-ams` |
114
- | Xiaomi MiMo Token Plan (Singapore) | `XIAOMI_TOKEN_PLAN_SGP_API_KEY` | `xiaomi-token-plan-sgp` |
115
-
116
- Reference for environment variables and `auth.json` keys: [`const envMap`](https://github.com/KnightCodeAI/knightcode/blob/main/packages/ai/src/env-api-keys.ts) in [`packages/ai/src/env-api-keys.ts`](https://github.com/KnightCodeAI/knightcode/blob/main/packages/ai/src/env-api-keys.ts).
117
-
118
- #### Auth File
119
-
120
- Store credentials in `~/.knightcode/agent/auth.json`:
31
+ This table covers providers with a single primary API-key variable. Providers that need additional configuration or support ambient credentials are covered under [Cloud providers](#cloud-providers).
32
+
33
+ | Provider | Environment variable |
34
+ |---|---|
35
+ | Anthropic | `ANTHROPIC_API_KEY` |
36
+ | AgentRouter | `AGENTROUTER_API_KEY` |
37
+ | Ant Ling | `ANT_LING_API_KEY` |
38
+ | OpenAI | `OPENAI_API_KEY` |
39
+ | DeepSeek | `DEEPSEEK_API_KEY` |
40
+ | NVIDIA NIM | `NVIDIA_API_KEY` |
41
+ | Google Gemini | `GEMINI_API_KEY` |
42
+ | GitHub Copilot | `COPILOT_GITHUB_TOKEN` |
43
+ | Mistral | `MISTRAL_API_KEY` |
44
+ | Groq | `GROQ_API_KEY` |
45
+ | Cerebras | `CEREBRAS_API_KEY` |
46
+ | xAI | `XAI_API_KEY` |
47
+ | OpenRouter | `OPENROUTER_API_KEY` |
48
+ | Vercel AI Gateway | `AI_GATEWAY_API_KEY` |
49
+ | ZAI Coding Plan (Global) | `ZAI_API_KEY` |
50
+ | ZAI Coding Plan (China) | `ZAI_CODING_CN_API_KEY` |
51
+ | OpenCode Zen and Go | `OPENCODE_API_KEY` |
52
+ | Radius | `RADIUS_API_KEY` |
53
+ | Hugging Face | `HF_TOKEN` |
54
+ | Fireworks | `FIREWORKS_API_KEY` |
55
+ | Together AI | `TOGETHER_API_KEY` |
56
+ | Baseten | `BASETEN_API_KEY` |
57
+ | Kimi For Coding | `KIMI_API_KEY` |
58
+ | Meta | `META_API_KEY` |
59
+ | MiniMax | `MINIMAX_API_KEY` |
60
+ | MiniMax (China) | `MINIMAX_CN_API_KEY` |
61
+ | Moonshot AI (Global and China) | `MOONSHOT_API_KEY` |
62
+ | Qwen Token Plan and Individual | `QWEN_TOKEN_PLAN_API_KEY` |
63
+ | Qwen Token Plan (China) | `QWEN_TOKEN_PLAN_CN_API_KEY` |
64
+ | Xiaomi MiMo | `XIAOMI_API_KEY` |
65
+ | Xiaomi MiMo Token Plan (China) | `XIAOMI_TOKEN_PLAN_CN_API_KEY` |
66
+ | Xiaomi MiMo Token Plan (Amsterdam) | `XIAOMI_TOKEN_PLAN_AMS_API_KEY` |
67
+ | Xiaomi MiMo Token Plan (Singapore) | `XIAOMI_TOKEN_PLAN_SGP_API_KEY` |
68
+
69
+ Anthropic also recognizes `ANTHROPIC_OAUTH_TOKEN` as an API credential and `ANTHROPIC_AUTH_TOKEN` as bearer authentication.
70
+
71
+ ## Load an API key from a command
72
+
73
+ 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 `!`:
121
74
 
122
75
  ```json
123
76
  {
124
- "anthropic": { "type": "api_key", "key": "sk-ant-..." },
125
- "ant-ling": { "type": "api_key", "key": "..." },
126
- "openai": { "type": "api_key", "key": "sk-..." },
127
- "deepseek": { "type": "api_key", "key": "sk-..." },
128
- "nvidia": { "type": "api_key", "key": "nvapi-..." },
129
- "google": { "type": "api_key", "key": "..." },
130
- "opencode": { "type": "api_key", "key": "..." },
131
- "opencode-go": { "type": "api_key", "key": "..." },
132
- "together": { "type": "api_key", "key": "..." },
133
- "qwen-token-plan": { "type": "api_key", "key": "sk-sp-..." },
134
- "qwen-token-plan-individual": { "type": "api_key", "key": "sk-sp-..." },
135
- "qwen-token-plan-cn": { "type": "api_key", "key": "sk-sp-..." },
136
- "xiaomi": { "type": "api_key", "key": "..." },
137
- "xiaomi-token-plan-cn": { "type": "api_key", "key": "..." },
138
- "xiaomi-token-plan-ams": { "type": "api_key", "key": "..." },
139
- "xiaomi-token-plan-sgp": { "type": "api_key", "key": "..." }
77
+ "anthropic": {
78
+ "type": "api_key",
79
+ "key": "!security find-generic-password -ws 'anthropic'"
80
+ }
140
81
  }
141
82
  ```
142
83
 
143
- `qwen-token-plan-individual` uses the same international endpoint and `QWEN_TOKEN_PLAN_API_KEY` as
144
- `qwen-token-plan`, but limits the picker to the models documented for Individual subscriptions. The existing
145
- provider keeps its broader catalog for backward compatibility. When using `auth.json`, store the
146
- credential under the provider you select; an environment variable is shared by both international providers.
84
+ 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.
85
+
86
+ ## Cloud Providers
147
87
 
148
- The file is created with `0600` permissions (user read/write only). Auth file credentials take priority over environment variables.
88
+ The providers below need additional settings or can use credentials supplied by their cloud platform.
149
89
 
150
- API key credentials can also include provider-scoped environment values. These values are used before process environment variables when resolving the credential key, provider/model headers, and provider configuration such as Cloudflare account IDs, Azure OpenAI settings, Vertex project/location, Bedrock settings, `KNIGHTCODE_CACHE_RETENTION`, and `HTTP_PROXY`/`HTTPS_PROXY`.
90
+ A stored API-key credential can include an `env` object. Its values take priority over the process environment for that provider:
151
91
 
152
92
  ```json
153
93
  {
154
- "cloudflare-ai-gateway": {
94
+ "cloudflare-workers-ai": {
155
95
  "type": "api_key",
156
- "key": "$CLOUDFLARE_API_KEY",
96
+ "key": "...",
157
97
  "env": {
158
- "CLOUDFLARE_API_KEY": "...",
159
- "CLOUDFLARE_ACCOUNT_ID": "account-id",
160
- "CLOUDFLARE_GATEWAY_ID": "gateway-id"
98
+ "CLOUDFLARE_ACCOUNT_ID": "account-id"
161
99
  }
162
100
  }
163
101
  }
164
102
  ```
165
103
 
166
- Use this when knightcode should use different provider settings than the project shell environment.
167
-
168
- ### Key Resolution
169
-
170
- The `key` field supports command execution, environment interpolation, and literals:
171
-
172
- - **Shell command:** `"!command"` at the start executes the whole value as a command and uses stdout (cached for process lifetime)
173
- ```json
174
- { "type": "api_key", "key": "!security find-generic-password -ws 'anthropic'" }
175
- { "type": "api_key", "key": "!op read 'op://vault/item/credential'" }
176
- ```
177
- - **Environment interpolation:** `"$ENV_VAR"` or `"${ENV_VAR}"` uses the value of the named variable. Interpolation works inside larger literals.
178
- ```json
179
- { "type": "api_key", "key": "$MY_ANTHROPIC_KEY" }
180
- { "type": "api_key", "key": "${KEY_PREFIX}_${KEY_SUFFIX}" }
181
- ```
182
- `$FOO_BAR` is the variable `FOO_BAR`; use `${FOO}_BAR` when `BAR` is literal text. Missing environment variables make the value unresolved.
183
- - **Escapes:** `"$$"` emits a literal `"$"`; `"$!"` emits a literal `"!"` without triggering command execution.
184
- ```json
185
- { "type": "api_key", "key": "$$literal-dollar-prefix" }
186
- { "type": "api_key", "key": "$!literal-bang-prefix" }
187
- ```
188
- - **Literal value:** Used directly. Plain uppercase strings such as `MY_API_KEY` are literals; use `$MY_API_KEY` for environment variables.
189
- ```json
190
- { "type": "api_key", "key": "sk-ant-..." }
191
- { "type": "api_key", "key": "public" }
192
- ```
193
-
194
- OAuth credentials are also stored here after `/login` and managed automatically.
195
-
196
- ## Cloud Providers
197
-
198
104
  ### Azure OpenAI
199
105
 
106
+ Set an API key plus either a base URL or resource name:
107
+
200
108
  ```bash
201
109
  export AZURE_OPENAI_API_KEY=...
202
110
  export AZURE_OPENAI_BASE_URL=https://your-resource.ai.azure.com
203
- # also supported: https://your-resource.cognitiveservices.azure.com
204
- # also supported: https://your-resource.openai.azure.com
205
- # root endpoints are auto-normalized to /openai/v1
206
- # or use resource name instead of base URL
111
+ # Or:
207
112
  export AZURE_OPENAI_RESOURCE_NAME=your-resource
208
-
209
- # Optional
210
- export AZURE_OPENAI_API_VERSION=2024-02-01
211
- export AZURE_OPENAI_DEPLOYMENT_NAME_MAP=gpt-4=my-gpt4,gpt-4o=my-gpt4o
212
113
  ```
213
114
 
115
+ Resource root URLs under `ai.azure.com`, `cognitiveservices.azure.com`, and `openai.azure.com` are normalized to the OpenAI API path.
116
+
214
117
  ### Amazon Bedrock
215
118
 
216
- Use `/login amazon-bedrock` to store a Bedrock API key, or configure one of the ambient AWS credential sources below:
119
+ Bedrock can use a bearer token or an ambient AWS credential source:
217
120
 
218
121
  ```bash
219
- # Option 1: AWS Profile
122
+ # Named profile
220
123
  export AWS_PROFILE=your-profile
221
124
 
222
- # Option 2: IAM Keys
125
+ # IAM keys
223
126
  export AWS_ACCESS_KEY_ID=AKIA...
224
127
  export AWS_SECRET_ACCESS_KEY=...
128
+ # Required for temporary credentials
129
+ export AWS_SESSION_TOKEN=...
225
130
 
226
- # Option 3: Bearer Token
131
+ # Bedrock bearer token
227
132
  export AWS_BEARER_TOKEN_BEDROCK=...
228
133
 
229
- # Optional region (defaults to us-east-1)
134
+ # Region, when not supplied by the profile or AWS SDK configuration
230
135
  export AWS_REGION=us-west-2
136
+ # AWS_DEFAULT_REGION is also supported
231
137
  ```
232
138
 
233
- Also supports ECS task roles (`AWS_CONTAINER_CREDENTIALS_*`) and IRSA (`AWS_WEB_IDENTITY_TOKEN_FILE`).
234
-
235
- ```bash
236
- knightcode --provider amazon-bedrock --model us.anthropic.claude-sonnet-4-20250514-v1:0
237
- ```
238
-
239
- Prompt caching is enabled automatically for Claude models whose ID contains a recognizable model name (base models and system-defined inference profiles). For application inference profiles (whose ARNs don't contain the model name), set `AWS_BEDROCK_FORCE_CACHE=1` to enable cache points:
240
-
241
- ```bash
242
- export AWS_BEDROCK_FORCE_CACHE=1
243
- knightcode --provider amazon-bedrock --model arn:aws:bedrock:us-east-1:123456789012:application-inference-profile/abc123
244
- ```
245
-
246
- If you are connecting to a Bedrock API proxy, the following environment variables can be used:
247
-
248
- ```bash
249
- # Set the URL for the Bedrock proxy (standard AWS SDK env var)
250
- export AWS_ENDPOINT_URL_BEDROCK_RUNTIME=https://my.corp.proxy/bedrock
251
-
252
- # Set if your proxy does not require authentication
253
- export AWS_BEDROCK_SKIP_AUTH=1
254
-
255
- # Set if your proxy only supports HTTP/1.1
256
- export AWS_BEDROCK_FORCE_HTTP1=1
257
- ```
139
+ KnightCode also supports ECS task credentials and IRSA through the standard `AWS_CONTAINER_CREDENTIALS_*` and `AWS_WEB_IDENTITY_TOKEN_FILE` variables.
258
140
 
259
141
  ### Cloudflare AI Gateway
260
142
 
261
- `CLOUDFLARE_API_KEY` can be set via `/login`. The account ID and gateway slug can be set as environment variables or in the API key credential's `env` object in `auth.json`.
143
+ The gateway requires a token, account ID, and gateway ID:
262
144
 
263
145
  ```bash
264
- export CLOUDFLARE_API_KEY=... # or use /login
146
+ export CLOUDFLARE_API_KEY=...
265
147
  export CLOUDFLARE_ACCOUNT_ID=...
266
- export CLOUDFLARE_GATEWAY_ID=... # create at dash.cloudflare.com → AI → AI Gateway
267
- knightcode --provider cloudflare-ai-gateway --model "claude-sonnet-4-5"
148
+ export CLOUDFLARE_GATEWAY_ID=...
268
149
  ```
269
150
 
270
- Routes to OpenAI, Anthropic, and Workers AI through Cloudflare AI Gateway. Workers AI uses the Unified API (`/compat`) and prefixed model IDs (`workers-ai/@cf/...`). OpenAI uses the OpenAI passthrough route (`/openai`) with native OpenAI model IDs such as `gpt-5.1`. Anthropic uses the Anthropic passthrough route (`/anthropic`) with native Anthropic model IDs such as `claude-sonnet-4-5`.
271
-
272
- AI Gateway authentication uses `CLOUDFLARE_API_KEY` as `cf-aig-authorization`. Upstream authentication can be one of:
151
+ The account and gateway IDs can come from the process environment or the credential's `env` object in `auth.json`.
273
152
 
274
- | Mode | Request auth | Upstream auth |
275
- |------|--------------|---------------|
276
- | Workers AI | Cloudflare token only | Cloudflare-native |
277
- | Unified billing | Cloudflare token only | Cloudflare handles upstream auth and deducts credits |
278
- | Stored BYOK | Cloudflare token only | Cloudflare injects provider keys stored in the AI Gateway dashboard |
279
- | Inline BYOK | Cloudflare token plus upstream `Authorization` header | The request supplies the upstream provider key |
280
-
281
- For normal knightcode usage, prefer unified billing or stored BYOK. Inline BYOK requires configuring an additional upstream `Authorization` header for the Cloudflare AI Gateway provider, for example via a `models.json` provider/model override.
153
+ `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`.
282
154
 
283
155
  ### Cloudflare Workers AI
284
156
 
285
- `CLOUDFLARE_API_KEY` can be set via `/login`. `CLOUDFLARE_ACCOUNT_ID` can be set as an environment variable or in the API key credential's `env` object in `auth.json`.
157
+ Workers AI requires a token and account ID:
286
158
 
287
159
  ```bash
288
- export CLOUDFLARE_API_KEY=... # or use /login
160
+ export CLOUDFLARE_API_KEY=...
289
161
  export CLOUDFLARE_ACCOUNT_ID=...
290
- knightcode --provider cloudflare-workers-ai --model "@cf/moonshotai/kimi-k2.6"
291
162
  ```
292
163
 
293
- KnightCode automatically sets `x-session-affinity` for [prefix caching](https://developers.cloudflare.com/workers-ai/features/prompt-caching/) discounts.
164
+ The account ID can also be stored in the credential's `env` object.
294
165
 
295
166
  ### Google Vertex AI
296
167
 
297
- Uses Application Default Credentials:
168
+ Use a Google Cloud API key:
298
169
 
299
170
  ```bash
300
- gcloud auth application-default login
301
- export GOOGLE_CLOUD_PROJECT=your-project
302
- export GOOGLE_CLOUD_LOCATION=us-central1
171
+ export GOOGLE_CLOUD_API_KEY=...
303
172
  ```
304
173
 
305
- Or set `GOOGLE_APPLICATION_CREDENTIALS` to a service account key file.
306
-
307
- ## llama.cpp
308
-
309
- KnightCode supports the llama.cpp router server. Configure it with `/login llama.cpp`, manage loaded models with `/llama`, and select a loaded model with `/model`.
310
-
311
- See [llama.cpp](llama-cpp.md) for server setup, model directory layout, environment variables, and command usage.
174
+ To use Application Default Credentials, configure a project and location:
312
175
 
313
- ## Custom Providers
314
-
315
- **Via models.json:** Add Ollama, LM Studio, vLLM, or any provider that speaks a supported API (OpenAI Completions, OpenAI Responses, Anthropic Messages, Google Generative AI). See [models.md](models.md).
316
-
317
- **Via extensions:** For providers that need custom API implementations or OAuth flows, create an extension. See [custom-provider.md](custom-provider.md) and [examples/extensions/custom-provider-gitlab-duo](../examples/extensions/custom-provider-gitlab-duo/).
176
+ ```bash
177
+ export GOOGLE_CLOUD_PROJECT=your-project
178
+ # GCLOUD_PROJECT is also supported
179
+ export GOOGLE_CLOUD_LOCATION=us-central1
180
+ ```
318
181
 
319
- ## Resolution Order
182
+ Then authenticate:
320
183
 
321
- When resolving credentials for a provider:
184
+ ```bash
185
+ gcloud auth application-default login
186
+ ```
322
187
 
323
- 1. CLI `--api-key` flag
324
- 2. `auth.json` entry (API key or OAuth token)
325
- 3. Environment variable
326
- 4. Custom provider keys from `models.json`
188
+ To use a service-account key file instead, set `GOOGLE_APPLICATION_CREDENTIALS` along with the project and location.