From b2254b9425d68044c392348663f210194d5805b0 Mon Sep 17 00:00:00 2001 From: Kishore Kumar Date: Wed, 17 Jun 2026 20:42:29 +0530 Subject: [PATCH 1/2] docs(cli): fix stale CLI commands + drop removed webhook form MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Aligns the CLI reference + config docs with the shipped command surface (cli-tree.ts): configuration.mdx AGENTSFLEET_API_KEY minted via 'agentsfleet agent-key add' (not 'agent add'); agentsfleet.mdx 'tenant provider set/reset' -> 'add/delete' and external-agent commands 'agent add/list/delete' -> 'agent-key add/list/delete'; webhooks.mdx drops the URL-embedded-secret section (variant removed from the router — HMAC/Svix/per-source path only). Companion to agentsfleet#421. Co-Authored-By: Claude Opus 4.8 (1M context) --- agents/webhooks.mdx | 12 +----------- cli/agentsfleet.mdx | 20 ++++++++++---------- cli/configuration.mdx | 2 +- 3 files changed, 12 insertions(+), 22 deletions(-) diff --git a/agents/webhooks.mdx b/agents/webhooks.mdx index bf7e2d2..34ee23f 100644 --- a/agents/webhooks.mdx +++ b/agents/webhooks.mdx @@ -143,14 +143,4 @@ agentsfleet logs 0198a7b2-9e1f-7c3a-8b25-6d4f0a9e2c71 Rejected requests carry a reason code (`webhook_rejected: signature_mismatch`, etc.) so you can tell a noisy upstream from a real auth bug. -## Advanced: URL-embedded secret - -Some upstreams (a few SaaS form-postbacks, a few legacy systems) can't attach a signature header. For those, the platform accepts a path-embedded secret: - -``` -https://api.agentsfleet.net/v1/webhooks/{agent_id}/{url_secret} -``` - -The `url_secret` is matched in constant time. Reserved segments (`approval`, `grant-approval`, `svix`) cannot be used as secret values. Prefer HMAC where the upstream supports it — the URL-embedded form is a fallback. - -**Path resolution order.** The trailing segment is resolved against declared `triggers[].source` values *first*, then falls back to a `url_secret` lookup. So `POST /v1/webhooks/0198a7b2-9e1f-7c3a-8b25-6d4f0a9e2c71/github` routes to the `github` source when the agent declares one, and only searches `url_secret` values for a constant-time match on the literal string `github` when no such source is declared. Practical consequence: avoid choosing a `url_secret` value that collides with any `triggers[].source` on the same agent — the source wins and the secret will never match. +The platform accepts webhooks only with a valid signature (HMAC or Svix) or the per-source path (`/github`, `/approval`, `/grant-approval`, `/svix`). There is no URL-embedded-secret fallback. diff --git a/cli/agentsfleet.mdx b/cli/agentsfleet.mdx index bb00160..a9d881c 100644 --- a/cli/agentsfleet.mdx +++ b/cli/agentsfleet.mdx @@ -294,30 +294,30 @@ agentsfleet workspace delete 0198a7b0-3c2d-7f14-9a08-1b6e4d2f8c50 External agents are API-key–authenticated callers (LangGraph, CrewAI, Composio, your own code) that drive a specific agent programmatically. -### `agentsfleet agent add` +### `agentsfleet agent-key add` Mint an API key bound to one agent. ```bash -agentsfleet agent add --workspace 0198a7b0-3c2d-7f14-9a08-1b6e4d2f8c50 --agent 0198a7b2-9e1f-7c3a-8b25-6d4f0a9e2c71 --name my-agent +agentsfleet agent-key add --workspace 0198a7b0-3c2d-7f14-9a08-1b6e4d2f8c50 --agent 0198a7b2-9e1f-7c3a-8b25-6d4f0a9e2c71 --name my-agent ``` The raw key (`agt_a…`) is returned **once**; store it in your secret manager. -### `agentsfleet agent list` +### `agentsfleet agent-key list` List every external agent key in a workspace. ```bash -agentsfleet agent list --workspace 0198a7b0-3c2d-7f14-9a08-1b6e4d2f8c50 +agentsfleet agent-key list --workspace 0198a7b0-3c2d-7f14-9a08-1b6e4d2f8c50 ``` -### `agentsfleet agent delete ` +### `agentsfleet agent-key delete ` Revoke an external agent key. ```bash -agentsfleet agent delete --workspace 0198a7b0-3c2d-7f14-9a08-1b6e4d2f8c50 0198a7b4-6e1a-7c93-b052-8f3d2a1e7c46 +agentsfleet agent-key delete --workspace 0198a7b0-3c2d-7f14-9a08-1b6e4d2f8c50 0198a7b4-6e1a-7c93-b052-8f3d2a1e7c46 ``` --- @@ -380,7 +380,7 @@ agentsfleet tenant provider show agentsfleet tenant provider show --json ``` -### `agentsfleet tenant provider set` +### `agentsfleet tenant provider add` Activate a self-managed credential for the tenant. The credential must already exist in the workspace vault (`agentsfleet credential add `). The command validates the credential structure, resolves the model's context cap from the `cap.json` endpoint, and pins both into the tenant's provider row. @@ -389,17 +389,17 @@ Activate a self-managed credential for the tenant. The credential must already e agentsfleet credential add account-fireworks --data='{"provider":"fireworks","api_key":"fw_…","model":"accounts/fireworks/models/kimi-k2.6"}' # 2. Activate it for the tenant -agentsfleet tenant provider set --credential account-fireworks +agentsfleet tenant provider add --credential account-fireworks ``` In-flight events finish under the snapshot they were claimed under; the next event's debits use the new posture. -### `agentsfleet tenant provider reset` +### `agentsfleet tenant provider delete` Drop the explicit `tenant_providers` row and fall back to the platform-managed synth-default. ```bash -agentsfleet tenant provider reset +agentsfleet tenant provider delete ``` For the install-time vs trigger-time resolution flow, the frontmatter overlay sentinels, and the provider routing details, see [`docs/architecture/user_flow.md` §8.7](https://github.com/agentsfleet/agentsfleet/blob/main/docs/architecture/user_flow.md#87-model-and-context-cap-origin-platform-vs-self-managed) and [`docs/architecture/billing_and_provider_keys.md`](https://github.com/agentsfleet/agentsfleet/blob/main/docs/architecture/billing_and_provider_keys.md). The architecture is the canonical reference; this page is the command surface. diff --git a/cli/configuration.mdx b/cli/configuration.mdx index 5ef52f8..a18638b 100644 --- a/cli/configuration.mdx +++ b/cli/configuration.mdx @@ -32,7 +32,7 @@ Every **other command** then resolves its token, and the order is TTY-aware: |----------|---------|---------| | `AGENTSFLEET_API_URL` | API base URL | `https://api.agentsfleet.net` | | `AGENTSFLEET_TOKEN` | Auth token (for CI and scripts; user-bound, from `agentsfleet login`) | *(from `agentsfleet login`)* | -| `AGENTSFLEET_API_KEY` | Service auth (machine-bound, from `agentsfleet agent add`). Use this for service-to-service calls and external agents (LangGraph, CrewAI, Composio, your own code). | — | +| `AGENTSFLEET_API_KEY` | Service auth (machine-bound, from `agentsfleet agent-key add`). Use this for service-to-service calls and external agents (LangGraph, CrewAI, Composio, your own code). | — | | `AGENTSFLEET_STATE_DIR` | Directory for local CLI state (credentials, telemetry, session). | `~/.config/agentsfleet` | | `NO_COLOR` | Set to `1` to disable color output. | — | | `AGENTSFLEET_TELEMETRY_DISABLED` | Set to `1` to opt out of anonymous analytics + tracing. | unset (telemetry on) | From b188e38c5ce60d8340a07ea2919f18f5b6fea4ad Mon Sep 17 00:00:00 2001 From: Kishore Kumar Date: Wed, 17 Jun 2026 22:35:09 +0530 Subject: [PATCH 2/2] docs(cli): sync overview table to agent-key commands (greptile) The Overview table still listed the removed `agent add`/`agent list`/ `agent delete` commands while the External agents section below was already updated to `agent-key add/list/delete`. Align the table so the summary scan matches the full reference. Co-Authored-By: Claude Opus 4.8 (1M context) --- cli/agentsfleet.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cli/agentsfleet.mdx b/cli/agentsfleet.mdx index a9d881c..f7e6c18 100644 --- a/cli/agentsfleet.mdx +++ b/cli/agentsfleet.mdx @@ -11,7 +11,7 @@ description: "Complete agentsfleet command reference." | Agents (top-level) | `install --from`, `list`, `status`, `stop`, `resume`, `kill`, `delete`, `logs`, `events`, `steer` | | Credentials | `credential add`, `credential show`, `credential list`, `credential delete` | | Workspaces | `workspace add`, `workspace list`, `workspace use`, `workspace show`, `workspace credentials`, `workspace delete` | -| External agents | `agent add`, `agent list`, `agent delete` | +| External agents | `agent-key add`, `agent-key list`, `agent-key delete` | | Integration grants | `grant list`, `grant delete` | | Billing | `billing show` | | Diagnostics | `doctor` |