From 35afc3dd16edff58028bcb660503181062dab57a Mon Sep 17 00:00:00 2001 From: hiroTamada <88675973+hiroTamada@users.noreply.github.com> Date: Wed, 3 Jun 2026 18:52:08 +0000 Subject: [PATCH] docs: clarify --project flag does not resolve names The global --project flag (and KERNEL_PROJECT env var) forwards its value verbatim as the X-Kernel-Project-Id header. The CLI only resolves names to IDs for the projects subcommand positional arguments (get, delete, limits). Update reference/cli.mdx, reference/cli/projects.mdx, and info/projects.mdx to reflect this and direct users to pass a project ID for the global flag. --- info/projects.mdx | 10 +++++----- reference/cli.mdx | 2 +- reference/cli/projects.mdx | 15 +++++++-------- 3 files changed, 13 insertions(+), 14 deletions(-) diff --git a/info/projects.mdx b/info/projects.mdx index 0a6764e..cb9f39f 100644 --- a/info/projects.mdx +++ b/info/projects.mdx @@ -126,19 +126,19 @@ OAuth tokens (used by the Kernel CLI and MCP server) are **always org-wide**. Yo The Kernel [CLI](/reference/cli/projects) has first-class project support: -- A global `--project ` flag scopes any command to a single project. Names are resolved case-insensitively, so `--project staging` works. +- A global `--project ` flag scopes any command to a single project. The value is forwarded verbatim as the `X-Kernel-Project-Id` header, so pass a project ID (run `kernel projects list` to look it up). - The `KERNEL_PROJECT` environment variable does the same, so you can set it once in your shell or CI. -- A `kernel projects` command group lets you list, create, get, and delete projects, and manage per-project limit overrides. +- A `kernel projects` command group lets you list, create, get, and delete projects, and manage per-project limit overrides. The `get`, `delete`, and `limits` subcommands accept either an ID or a name as their positional argument — the CLI resolves the name to an ID before calling the API. ```bash # Scope a single command -kernel browsers list --project staging +kernel browsers list --project proj_abc123 # Scope every command in the shell -export KERNEL_PROJECT=staging +export KERNEL_PROJECT=proj_abc123 kernel apps list -# Manage projects +# Manage projects (these subcommands accept a name) kernel projects list kernel projects create staging kernel projects limits set staging --max-concurrent-sessions 5 diff --git a/reference/cli.mdx b/reference/cli.mdx index 7a4e39c..f09c8fe 100644 --- a/reference/cli.mdx +++ b/reference/cli.mdx @@ -75,7 +75,7 @@ kernel invoke my-app action-name --payload '{"key":"value"}' - `--version`, `-v` - Print the CLI version - `--no-color` - Disable color output - `--log-level ` - Set the log level (trace, debug, info, warn, error, fatal, print) -- `--project ` - Scope the request to a specific [project](/reference/cli/projects) (also reads the `KERNEL_PROJECT` env var) +- `--project ` - Scope the request to a specific [project](/reference/cli/projects) by ID. The value is forwarded verbatim as the `X-Kernel-Project-Id` header, so pass an ID (not a name). Also reads the `KERNEL_PROJECT` env var. ## JSON Output diff --git a/reference/cli/projects.mdx b/reference/cli/projects.mdx index 1312878..5e73f03 100644 --- a/reference/cli/projects.mdx +++ b/reference/cli/projects.mdx @@ -6,27 +6,26 @@ Manage [Projects](/info/projects) from the CLI and scope other commands to a spe ## Scoping commands to a project -Use the global `--project` flag (or the `KERNEL_PROJECT` environment variable) to scope any `kernel` command to a project. The flag accepts either a **project ID** or a **project name** — names are resolved case-insensitively by listing your projects. +Use the global `--project` flag (or the `KERNEL_PROJECT` environment variable) to scope any `kernel` command to a project. The flag value is forwarded verbatim as the `X-Kernel-Project-Id` header on every authenticated API request, so it must be a **project ID** — the CLI does not look up names for this flag. ```bash -# Scope a single command by name -kernel browsers list --project staging - -# Scope by ID +# Scope a single command kernel browsers list --project proj_abc123 # Scope via environment variable -export KERNEL_PROJECT=staging +export KERNEL_PROJECT=proj_abc123 kernel apps list ``` -Under the hood, the flag adds the `X-Kernel-Project-Id` header to every authenticated API request. OAuth-based logins (`kernel login`) remain org-wide by default, so this is the recommended way to target a single project when logged in with OAuth. +Run `kernel projects list` to find the ID for a project by name. + +OAuth-based logins (`kernel login`) remain org-wide by default, so this is the recommended way to target a single project when logged in with OAuth. Project-scoped API keys are already bound to a project server-side, so you don't need `--project` when using them — but if you do pass it, it must match the key's project or the request is rejected. -If the name is ambiguous (multiple projects share it) or no match is found, the CLI returns a clear error; pass the project ID instead. +Name resolution **is** supported on the `projects` subcommand positional arguments (`kernel projects get `, `delete`, `limits get`, `limits set`) — those commands list your projects and match case-insensitively before issuing the request. ## Commands