---
title: "CLI | Gazebo Docs"
description: "Use the Gazebo CLI for account administration, agent credential retrieval, safe scripting, explicit access policies, and audit pagination."
url: "https://gazebohq.com/docs/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](/docs/sdk).

## Installation
This guide covers manual account and agent tokens. The SDK's [account-connection flow](/docs/consent) 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.

```sh
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](/docs/api/authentication) 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:

```sh
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](/docs/api) and [MCP guide](/docs/mcp) 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.

```sh
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.

```sh
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`:

```sh
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

```sh
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:

```json
{"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:

```js
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:

```sh
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

```sh
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](/docs/api/errors); 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](/docs/api/errors) and the [SDK reference](/docs/sdk).

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 [hello@gazebohq.com](mailto:hello@gazebohq.com) with the package/runtime versions, error code, HTTP status and exit code. Never include tokens, credential values or raw account/audit output.