feat(cli): add projects support with --project flag and name resolution by hiroTamada · Pull Request #147 · kernel/cli

hiroTamada · 2026-04-10T15:18:53Z

Summary

Adds a global --project persistent flag (and KERNEL_PROJECT_ID env var) that injects the X-Kernel-Project-Id header to scope all API requests to a specific project
The flag accepts either a project ID or a project name — names are resolved via the projects list endpoint with case-insensitive matching
Adds kernel projects subcommands: list, create, get, delete, get-limits, set-limits
Upgrades kernel-go-sdk to v0.48.0 for project endpoint support (also fixes ProxyService.Check signature change)

How it works

When --project is provided:

If the value looks like a cuid2 ID (24 lowercase alphanumeric chars), it's used directly as the project ID header
Otherwise, the CLI authenticates first, calls GET /projects to list all projects, finds a case-insensitive name match, and injects the resolved ID
Clear errors for: no match found, multiple matches (ambiguous name)

Test plan

Tested against staging with a project-scoped API key:

--project "cli-test-project" (by name) — resolves correctly
--project "CLI-TEST-PROJECT" (case-insensitive) — resolves correctly
--project "g9vcya6unur84k70n0u8s9p9" (by ID) — works directly
--project "nonexistent-project" — clear error message
KERNEL_PROJECT_ID="cli-test-project" env var with name — resolves correctly
No --project with scoped API key — auto-scopes via server middleware
kernel projects list/create/get/delete/get-limits/set-limits — all functional

Made with Cursor

Note

Medium Risk
Touches global request-scoping (adds a header to all authenticated API calls) and introduces new project/limits operations, so misconfiguration could unintentionally scope or modify the wrong project; changes are otherwise localized and covered by unit tests.

Overview
Adds project-scoped operation support to the CLI via a new persistent --project flag (with KERNEL_PROJECT and legacy KERNEL_PROJECT_ID env fallback) that injects the X-Kernel-Project-Id header into all authenticated SDK requests.

Introduces a new kernel projects command group to list/create/get/delete projects and to get/set per-project limit overrides, including ID-or-name resolution with pagination and clearer handling of “unlimited” limits and invalid/negative inputs.

Upgrades github.com/kernel/kernel-go-sdk to v0.48.0, updates proxy health-check calls to match the new Check(..., kernel.ProxyCheckParams{}) signature, and adjusts/extends tests around project selection/name resolution and limits output.

^{Reviewed by Cursor Bugbot for commit a20844d. Bugbot is set up for automated code reviews on this repo. Configure here.}

Add global --project flag (and KERNEL_PROJECT_ID env var) that injects X-Kernel-Project-Id header to scope all API requests to a project. The flag accepts either a project ID or a project name — names are resolved via the projects list endpoint (case-insensitive). Also adds `kernel projects` subcommands: list, create, get, delete, get-limits, set-limits. Upgrades kernel-go-sdk to v0.48.0 for project endpoint support. Made-with: Cursor

firetiger-agent · 2026-04-10T15:19:03Z

Firetiger deploy monitoring skipped

This PR didn't match the auto-monitor filter configured on your GitHub connection:

Any PR that changes the kernel API. Monitor changes to API endpoints (packages/api/cmd/api/) and Temporal workflows (packages/api/lib/temporal) in the kernel repo

Reason: PR modifies CLI functionality (packages/cli) and SDK dependencies, not kernel API endpoints (packages/api/cmd/api/) or Temporal workflows (packages/api/lib/temporal).

To monitor this PR anyway, reply with @firetiger monitor this.

Made-with: Cursor

- looksLikeCUID: require first character to be a letter (cuid2 spec) - FakeProxyService.CheckFunc: update type signature and delegation to include body parameter Made-with: Cursor

Reuse cuidRegex from browsers.go in looksLikeCUID and update the regex to require the first character to be a letter (matching the cuid2 spec). Made-with: Cursor

Previously negative values were silently discarded, reporting success without sending the value to the API. Made-with: Cursor

get, delete, get-limits, and set-limits now accept either a project ID or name. Names are resolved via the projects list endpoint, reusing the same resolveProjectByName helper as the --project global flag. Made-with: Cursor

The default page size could miss projects beyond the first page. Request a large limit to cover typical org sizes. Made-with: Cursor

rgarcia · 2026-04-13T13:51:42Z

+
+		projectVal, _ := cmd.Flags().GetString("project")
+		if projectVal == "" {
+			projectVal = os.Getenv("KERNEL_PROJECT_ID")


nit: since this now accepts either a project name or ID, should this env var be called KERNEL_PROJECT to match --project and better signal the flexibility?

rgarcia · 2026-04-13T13:51:42Z

+// resolveProjectByName lists the caller's projects and returns the ID of the
+// one whose name matches (case-insensitive). Returns an error if no match or
+// multiple matches are found.
+func resolveProjectByName(ctx context.Context, client kernel.Client, name string) (string, error) {


curious why we need client-side name resolution here. if the API/SDK already has a get-by-id-or-name path under the hood, might be worth delegating to that instead of listing + matching locally

rgarcia · 2026-04-13T13:51:42Z

+	"github.com/spf13/cobra"
+)
+
+var projectsCmd = &cobra.Command{


question on code organization: browsers uses a cobra-independent struct + typed input pattern (BrowsersCmd, BrowsersListInput, etc.), which seems to make the logic easier to test and keeps flag parsing separate from API behavior/output formatting. since projects is already a multi-command surface, would it be worth following that pattern here too with a ProjectsCmd?

rgarcia · 2026-04-13T13:51:42Z

+}
+
+var projectsLimitsGetCmd = &cobra.Command{
+	Use:   "get-limits <id-or-name>",


question on command shape: these get-limits / set-limits verbs feel a little inconsistent with the rest of the cli. most resources use list/get/create/update/delete, and when an area grows we seem to introduce a nested noun subtree like browsers fs ... or browsers computer .... if project admin actions are going to expand, would projects limits get / projects limits set be a better fit?

rgarcia · 2026-04-13T13:51:42Z

+			return nil
+		}
+
+		out, _ := json.MarshalIndent(limits, "", "  ")


looks like these limits commands always print raw json. the rest of the cli seems to reserve machine-readable output for an explicit --output json / -o json flag and otherwise uses human-friendly tables/messages. might be worth making projects follow that same convention for consistency

Adopt the typed handler pattern for projects while preserving Cobra wiring, add nested limits subcommands with backward-compatible aliases, and standardize limits output behavior. Also support KERNEL_PROJECT precedence and paginate project name resolution to avoid missing matches outside the first page. Made-with: Cursor

socket-security · 2026-04-13T14:52:44Z

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	golang/github.com/kernel/kernel-go-sdk@v0.44.1-0.20260323174449-5e56fc5d99a6 ⏵ v0.48.0	⁺¹

View full report

masnwilliams

lgtm — all review comments addressed. typed handler pattern, nested limits subcommands, human-readable output, and KERNEL_PROJECT precedence all look good.

Remove name resolution from the global --project flag. The flag now passes the value directly as the X-Kernel-Project-Id header without attempting to resolve project names. The resolveProjectByName function is retained for explicit project subcommands (e.g. 'projects get <name>') where name lookup is expected.

cursor

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit a20844d. Configure here.}

cursor · 2026-04-17T16:21:20Z

+
+		if projectVal != "" {
+			clientOpts = append(clientOpts, option.WithHeader("X-Kernel-Project-Id", projectVal))
+		}


Global --project flag skips name-to-ID resolution

High Severity

The --project flag handler in PersistentPreRunE passes the raw projectVal directly into the X-Kernel-Project-Id header without calling resolveProjectArg or resolveProjectByName. When a user supplies a project name instead of an ID, the name string is sent verbatim as the header value rather than being resolved to an actual project ID. The resolveProjectByName function is defined in the same file but never wired into this code path, so the documented name-resolution behavior (CUID2 check, then list-and-match) doesn't occur for the global flag.

Additional Locations (1)

cmd/root.go#L248-L291

^{Reviewed by Cursor Bugbot for commit a20844d. Configure here.}

merge: resolve go.mod/go.sum conflict with main (keep sdk v0.48.0)

dac2b2a

Made-with: Cursor

cursor bot reviewed Apr 10, 2026

View reviewed changes

Comment thread cmd/root.go Outdated

Comment thread cmd/proxies/common_test.go

fix: address bugbot review comments

73aca64

- looksLikeCUID: require first character to be a letter (cuid2 spec) - FakeProxyService.CheckFunc: update type signature and delegation to include body parameter Made-with: Cursor

cursor bot reviewed Apr 10, 2026

View reviewed changes

Comment thread cmd/root.go Outdated

fix: consolidate CUID validation into single shared regex

b110ced

Reuse cuidRegex from browsers.go in looksLikeCUID and update the regex to require the first character to be a letter (matching the cuid2 spec). Made-with: Cursor

hiroTamada requested review from masnwilliams and rgarcia April 10, 2026 15:43

cursor bot reviewed Apr 10, 2026

View reviewed changes

Comment thread cmd/projects.go Outdated

fix: reject negative limit values with explicit error in set-limits

e55a6c3

Previously negative values were silently discarded, reporting success without sending the value to the API. Made-with: Cursor

cursor bot reviewed Apr 10, 2026

View reviewed changes

Comment thread cmd/root.go

hiroTamada added 2 commits April 10, 2026 13:02

fix: support project name in subcommand positional arguments

4024bbb

get, delete, get-limits, and set-limits now accept either a project ID or name. Names are resolved via the projects list endpoint, reusing the same resolveProjectByName helper as the --project global flag. Made-with: Cursor

fix: fetch up to 200 projects for name resolution

8d3fa6a

The default page size could miss projects beyond the first page. Request a large limit to cover typical org sizes. Made-with: Cursor

rgarcia requested changes Apr 13, 2026

View reviewed changes

hiroTamada requested a review from rgarcia April 13, 2026 16:52

masnwilliams approved these changes Apr 14, 2026

View reviewed changes

masnwilliams added 2 commits April 17, 2026 11:55

Merge branch 'main' into hiro/cli-project-support

ac2bea2

cursor bot reviewed Apr 17, 2026

View reviewed changes

masnwilliams mentioned this pull request Apr 17, 2026

Add project scoping support kernel/kernel-mcp-server#100

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(cli): add projects support with --project flag and name resolution#147

feat(cli): add projects support with --project flag and name resolution#147
hiroTamada wants to merge 10 commits intomainfrom
hiro/cli-project-support

hiroTamada commented Apr 10, 2026 •

edited by cursor bot

Loading

Uh oh!

firetiger-agent bot commented Apr 10, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

rgarcia Apr 13, 2026

Uh oh!

rgarcia Apr 13, 2026

Uh oh!

rgarcia Apr 13, 2026

Uh oh!

rgarcia Apr 13, 2026

Uh oh!

rgarcia Apr 13, 2026

Uh oh!

socket-security bot commented Apr 13, 2026 •

edited

Loading

Uh oh!

masnwilliams left a comment

Uh oh!

cursor bot left a comment

Uh oh!

cursor bot Apr 17, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

hiroTamada commented Apr 10, 2026 • edited by cursor bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

How it works

Test plan

Uh oh!

firetiger-agent bot commented Apr 10, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

rgarcia Apr 13, 2026

Choose a reason for hiding this comment

Uh oh!

rgarcia Apr 13, 2026

Choose a reason for hiding this comment

Uh oh!

rgarcia Apr 13, 2026

Choose a reason for hiding this comment

Uh oh!

rgarcia Apr 13, 2026

Choose a reason for hiding this comment

Uh oh!

rgarcia Apr 13, 2026

Choose a reason for hiding this comment

Uh oh!

socket-security bot commented Apr 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

masnwilliams left a comment

Choose a reason for hiding this comment

Uh oh!

cursor bot left a comment

Choose a reason for hiding this comment

Uh oh!

cursor bot Apr 17, 2026

Choose a reason for hiding this comment

Global --project flag skips name-to-ID resolution

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

hiroTamada commented Apr 10, 2026 •

edited by cursor bot

Loading

socket-security bot commented Apr 13, 2026 •

edited

Loading