cli/api: add --jurisdiction and document the command#1631
Conversation
`entire api --to cell` only reached the caller's home entire-api cell.
Add `--jurisdiction <slug>` (e.g. us, eu) to target a specific
jurisdiction's cell instead, reusing the existing cell machinery: it
passes `auth.CellTarget{Jurisdiction: slug}` into NewEntireAPICellClient,
which mints the jurisdictional identity token and resolves that
jurisdiction's cell URL. No new exchange/URL/security logic.
`--jurisdiction` targets a cell, so it implies `--to cell`; combining it
with an explicit `--to core` is a contradiction and errors clearly. The
slug is normalized to a bare lowercase DNS label (US/" us " -> us).
Surface it to agents: the command was already visible in `entire help`
and `entire agent-help`, and agent-help renders live from the Cobra tree,
so the updated Long/Example/flag-usage explain `--jurisdiction`
automatically on drill-down. Also document `entire api` in CLAUDE.md,
which was missing it entirely.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Entire-Checkpoint: 2e2d0343f4a1
There was a problem hiding this comment.
Pull request overview
Adds first-class support for calling a specific jurisdiction’s entire-api cell from entire api, and documents the command surface so it’s discoverable via help/agent-help and CLAUDE.md.
Changes:
- Add
--jurisdiction <slug>toentire api, with slug normalization and a--to core+--jurisdictioncontradiction error. - Thread the resolved jurisdiction into cell client construction via
auth.CellTarget{Jurisdiction: ...}. - Document
apiinCLAUDE.mdalongside the other top-level commands.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.
| File | Description |
|---|---|
| cmd/entire/cli/api_cmd.go | Adds --jurisdiction, resolves --to/--jurisdiction interplay, and passes jurisdiction into cell client creation. |
| cmd/entire/cli/api_cmd_test.go | Updates client tests for new signature and adds coverage for target resolution behavior. |
| CLAUDE.md | Documents the api command and the new --jurisdiction behavior for users/agents. |
| const cell = "cell" | ||
| for _, tc := range []struct { | ||
| name string | ||
| flags apiFlags | ||
| toExplicit bool | ||
| wantTo string | ||
| wantJuris string | ||
| wantErr bool | ||
| }{ | ||
| // No --jurisdiction: --to is passed through untouched. | ||
| {"default", apiFlags{to: "core"}, false, "core", "", false}, | ||
| // --jurisdiction with default --to: implies cell, slug normalized to lowercase. | ||
| {"implied cell", apiFlags{to: "core", jurisdiction: " US "}, false, cell, "us", false}, | ||
| // --jurisdiction with explicit --to cell: allowed. | ||
| {"explicit cell", apiFlags{to: cell, jurisdiction: "eu"}, true, cell, "eu", false}, | ||
| // --jurisdiction with explicit --to core: contradiction, rejected. | ||
| {"contradiction", apiFlags{to: "core", jurisdiction: "eu"}, true, "", "", true}, | ||
| } { |
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
There was a problem hiding this comment.
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.
Comment @cursor review or bugbot run to trigger another review on this PR
Reviewed by Cursor Bugbot for commit 7e82009. Configure here.
| if jurisdiction != "" { | ||
| target = &auth.CellTarget{Jurisdiction: jurisdiction} | ||
| } | ||
| client, err := auth.NewEntireAPICellClient(ctx, insecure, target) |
There was a problem hiding this comment.
Jurisdiction skips catalog on direct cells
Medium Severity
When --jurisdiction is set, the cell client is built with only Jurisdiction on auth.CellTarget, not BaseURL. If the configured data API origin is a direct entire-api cell host (or loopback) rather than an apex/BFF, auth keeps that origin as the dial target while still minting an identity token for the pinned jurisdiction, so the call may not reach that jurisdiction's cell.
Reviewed by Cursor Bugbot for commit 7e82009. Configure here.
`-j` is free on the command (used: -X, -f, -F, -H, -i). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Entire-Checkpoint: 6d4dbe371e4a
What
--jurisdiction <slug>(short-j) toentire api(e.g.us,eu) to target a specific jurisdiction's entire-api cell instead of the caller's home cell.entire apiin CLAUDE.md, which was missing it entirely.Why
entire api --to cellonly ever reached the caller's home entire-api cell. There was no way to call a different jurisdiction's cell from the CLI, even though the underlying cell client (auth.NewEntireAPICellClient+auth.CellTarget) already supports pinning a jurisdiction. This is the sibling of PR #1619, which added--jurisdictiontoentire auth token.Details
--jurisdictionpassesauth.CellTarget{Jurisdiction: slug}intoNewEntireAPICellClient, which mints the jurisdictional identity token (RFC 8693,scope=openid,aud=<jurisdiction host>) and resolves that jurisdiction's cell URL from the cluster catalog — the same audited path used elsewhere.--jurisdictionimplies--to cell. Combining it with an explicit--to coreis a contradiction and errors clearly (--jurisdiction targets a cell; use --to cell (not --to core)). The slug is normalized to a bare lowercase DNS label (US/" us "→us);NewEntireAPICellClientvalidates it as a label.-jshorthand. Added alongside the existing-X/-f/-F/-H/-ishorthands (-jwas free).entire apiwas already visible inentire helpandentire agent-help, and agent-help renders live from the Cobra tree — so the updatedLong,Example, and flag usage explain--jurisdictionautomatically onentire agent-help apidrill-down. No annotation changes needed.Testing
TestResolveAPITargetcovers pass-through, implied-cell + slug normalization, explicit cell, and the--to corecontradiction.mise run fmt+mise run lintclean.go test ./cmd/entire/cli/ ./cmd/entire/cli/auth/passes.entire api --help/entire agent-help apishow the flag (-j, --jurisdiction) + examples, andentire api --to core --jurisdiction euemits the contradiction error.🤖 Generated with Claude Code