CLI

Use the Gazebo CLI for account administration and agent-scoped credential retrieval from a terminal or script. All HTTP operations use the TypeScript SDK.

Installation

This guide covers manual account and agent tokens. The SDK's account-connection flow is separate: the CLI does not provide browser login or automatic renewal. Do not put application signing keys or refresh credentials in CLI arguments.

The CLI requires server-side Node.js 20 or newer. Use a maintained, security-patched Node.js 22 or 24 release for new environments.

npm install --global @gazebohq/cli
gazebo --help

The installed command is gazebo. The CLI uses @gazebohq/sdk for HTTP requests. It has no saved login or persistent configuration.

Shell variable-assignment examples below use POSIX shell syntax; adapt assignment and quoting for other shells.

Token setup

Follow the authentication guide to obtain tokens. Supply them through your secret manager or environment, not command-line values, source files or recorded terminal sessions.

Variable	Purpose
GAZEBO_ACCOUNT_TOKEN	Account administration commands
GAZEBO_API_TOKEN	Compatibility fallback for account commands only
GAZEBO_AGENT_TOKEN	Agent credential retrieval; never falls back to an account token
GAZEBO_ENDPOINT	Optional deployment origin; defaults to https://app.gazebohq.com

Alternatively, --token-file PATH reads the appropriate token from a private file outside version control. The file is read once and trimmed; the CLI never saves or updates it. A token-file option takes precedence over environment variables.

There is no --token argument or interactive login flow. Generating a replacement account API token revokes the previous one, so do not rotate a shared token merely to test the CLI.

Read-only quickstart

With an account token securely configured:

gazebo account get --json
gazebo services list --json
gazebo agents list --json
gazebo audit list --limit 5 --json

These commands do not create an agent or change a policy. Output may still contain personal information: account identity includes email, and audit events include agent metadata. Keep it out of public logs and screenshots.

Command reference

Command	Token	Purpose
account get	Account	Read account identity and feature availability
services list	Account	List connected service metadata
agents list	Account	List active agents without tokens
agents create --name NAME --reveal	Account	Create an agent and show its token once
agents delete AGENT_ID --yes	Account	Revoke the specified agent
access get AGENT_ID	Account	Inspect service policies
access set AGENT_ID SERVICE --enabled true --methods GET	Account	Replace a policy with explicit enabled state and methods
audit list	Account	Read one page of credential-access events
credentials get SERVICE --reveal	Agent	Retrieve one permitted, sensitive credential
--help	None	Show usage without making a request

The CLI does not upload credentials, administer consent, invoke provider APIs or wrap MCP. Refer to the REST API and MCP guide for those separately documented interfaces.

Create an agent safely

Agent creation returns its token once and requires --reveal before making the request. The following command prints a sensitive token. Use a private, unrecorded terminal or a secure consumer that captures stdout without logging it.

EXPIRY="$(node -e 'process.stdout.write(new Date(Date.now() + 3600000).toISOString())')"
gazebo agents create --name "GET credential retrieval" \
  --expires-at "$EXPIRY" --reveal --json

--expires-at takes a UTC ISO timestamp. Omitting it creates an agent without an expiration. Store the returned token securely; agent listings will not return it again. If directing sensitive stdout to a file, set restrictive permissions first and keep it outside version control.

Configure access

Replace AGENT_ID with the intended agent's ID. Connect the service through the dashboard first.

gazebo access get AGENT_ID --json
gazebo access set AGENT_ID stripe --enabled true --methods GET
gazebo access set AGENT_ID stripe --enabled false --methods GET

Access updates replace the existing policy. Both --enabled true|false and a nonempty --methods list are required, including when disabling access. Methods are GET, POST, PUT, PATCH and DELETE; comma-separated values are supported and lowercase input is normalized.

These policies govern credential release, not subsequent provider actions. Use provider-side scopes and IAM to constrain the credential itself.

Retrieve a credential

Use an agent token with permission for the service and declared method. This example assumes a connected stripe service with a key named api_key:

gazebo credentials get stripe \
  --method GET --key-name api_key --reveal --json

This prints the credential value. Capture it privately and pass it directly to your server-side integration. Do not use public CI logs or paste the output into chat.

Without --key-name, the server selects the primary credential, preferring api_key. Without --method, retrieval defaults to GET. --reveal is mandatory even in scripts: omitting it prevents the HTTP request rather than retrieving and hiding a secret.

A disabled service or disallowed declared method returns HTTP 403. A missing named key returns HTTP 404. The CLI does not automatically poll for approval or retry denied requests.

Audit filters and pagination

gazebo audit list --limit 50 --service stripe --outcome success --json
gazebo audit list --limit 50 --service stripe --outcome success \
  --cursor "$CURSOR" --json

Set CURSOR to the previous response's nextCursor only when hasMore is true. Every invocation returns one page with events, nextCursor and hasMore; keep filters unchanged when advancing the opaque cursor.

Filters are --limit (integer 1–200), --cursor, --agent-id, --service, --outcome (success, denied or not_found), --from and --to. Date filters take timestamp strings. Pagination and retries are not automatic.

JSON output and scripting

Default output is indented JSON; --json emits compact JSON. Successful results go to stdout, and errors go to stderr:

{"error":{"code":"http","message":"Gazebo request failed (HTTP 403)","status":403}}

The example is a generic failure shape, not a credential response. Errors omit raw server payloads, stack traces and underlying transport details. An optional retryAfter field preserves the server's Retry-After header.

For a read-only script, capture service metadata and print only a count:

import { execFileSync } from "node:child_process";

const output = execFileSync("gazebo", ["services", "list", "--json"], {
  encoding: "utf8",
  stdio: ["ignore", "pipe", "pipe"],
});
const services = JSON.parse(output);
console.log({ connectedServiceCount: services.length });

Treat stdout as sensitive when scripting agent creation or credential retrieval. Use process arguments only for non-secret options and do not log unfiltered subprocess results.

Exit code	Meaning
0	Success or help
1	Request or configuration failure
2	Usage error, including missing token or required confirmation
130	In-flight request cancelled

Endpoint, timeout and cancellation

--endpoint URL overrides GAZEBO_ENDPOINT. Supply the origin, not /api or a resource path. Optional endpoint path prefixes are preserved. Use HTTPS remotely:

gazebo --endpoint https://app.gazebohq.com services list --json
gazebo --endpoint http://localhost:8787 services list --json

The localhost example demonstrates interface configurability only. A local broker is not yet implemented, and cloud/local parity is not yet verified.

--timeout-ms overrides the default 10-second timeout, including response-body reads. Ctrl+C or SIGTERM abort in-flight SDK requests. There are no automatic retries or cookie-authentication fallbacks.

Revoke an agent

gazebo agents delete AGENT_ID --yes

--yes explicitly authorizes revocation without an interactive prompt. Confirm the ID carefully. Revoked tokens can no longer retrieve credentials; provider credentials already released remain subject to provider-side controls.

Credential security boundary

Credential retrieval returns the actual provider key to the calling runtime. A third-party host running the CLI can receive it too. Use trusted environments and narrow provider permissions; declared-method checks control credential release, not subsequent service calls.

Revoking an agent blocks future retrieval but does not invalidate a key already retrieved. Audit records show credential access, not all provider actions. Account connection and token setup are manual; there is no integrated browser consent flow or provider request proxy.

In multi-user applications, keep users' agent tokens separate and do not substitute an account administration token.

Troubleshooting and support

• Missing token / exit 2: check the environment variable for the command's account or agent mode.
• 401: check token type, expiration and revocation.
• 403: inspect the agent's service policy and declared method using an authorized account client.
• 404: check the service identifier and named key.
• 429: follow API limits guidance; repeated unchanged retries are not automatic.

Package versions and REST API versions are separate. This reference describes the current CLI command surface; do not infer support for undocumented dashboard endpoints. See API compatibility guidance and the SDK reference.

Local archive installation and controlled live-cloud workflows have passed. Public-registry installation is not yet verified, and the checks do not certify every OS, real-provider usage or a local broker.

For help, contact [email protected] with the package/runtime versions, error code, HTTP status and exit code. Never include tokens, credential values or raw account/audit output.