---
title: "Global Options"
description: "Flags and environment variables available on every PgBeam CLI command."
canonical: "https://pgbeam.com/docs/cli/global-options"
last-updated: "2026-10-30T13:32:17.000Z"
---

# Global Options

> Flags and environment variables available on every PgBeam CLI command.

URL: https://pgbeam.com/docs/cli/global-options

## Global flags

| Flag         | Description                           |
| ------------ | ------------------------------------- |
| `--token`    | API token (overrides profile)         |
| `--profile`  | Auth profile to use                   |
| `--project`  | Project ID (overrides linked project) |
| `--org`      | Organization ID (overrides profile)   |
| `--json`     | Output as JSON                        |
| `--no-color` | Disable color output                  |
| `--no-trunc` | Show full table cell values           |
| `--debug`    | Enable debug output                   |

> **JSON output**
>
> Use `--json` on any command to get machine-readable JSON output. This is
> useful for scripting and CI/CD pipelines.

With `--json`, errors are machine-readable too: instead of human-formatted console output, a failed command prints a JSON error object to stdout and exits non-zero. The `status` field is present for API errors, and `hint` carries the same remediation hint the human output shows:

```json
{
  "error": {
    "status": 401,
    "message": "invalid token",
    "hint": "Not authenticated or the token is invalid. Run `pgbeam auth login`, or pass --token / set PGBEAM_API_KEY."
  }
}
```

## Environment variables

| Variable                 | Description                                                                                                                                                                                                                                                        |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `PGBEAM_API_KEY`         | Use an API key instead of the stored profile's token. The organization still comes from `--org` or the active profile, so pass `--org` when the key belongs to a different organization. Canonical; `PGBEAM_TOKEN` and `PGBEAM_API_TOKEN` are accepted as aliases. |
| `PGBEAM_PROFILE`         | Select a named profile without `--profile`                                                                                                                                                                                                                         |
| `PGBEAM_API_URL`         | Override the API base URL (defaults to `https://api.pgbeam.com`)                                                                                                                                                                                                   |
| `PGBEAM_NO_UPDATE_CHECK` | Disable automatic update checks                                                                                                                                                                                                                                    |

`pgbeam auth status` shows which organization commands target and where it came from, and warns when a `--token` or `PGBEAM_API_KEY` credential is paired with an organization from a stored profile.

## Raw API access

The CLI includes a built-in HTTP client for making raw API requests:

```bash
pgbeam api ls                             # List all API endpoints
pgbeam api request GET /v1/regions        # Make a raw API request
pgbeam api schema listRegions             # Show operation schema
```

See [api ls](/docs/cli/api/ls) for full details.