> ## Documentation Index
> Fetch the complete documentation index at: https://docs.forge.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI

> Install, authenticate, and automate Forge from a terminal or CI job.

Forge CLI is a JSON-first client for the public Forge API. It supports
interactive OAuth, service-account tokens, named profiles, registry
installation, bounded reads, and guarded administrative writes.

## Install

<Tabs>
  <Tab title="macOS and Linux">
    ```bash theme={"system"}
    curl -fsSL https://downloads.forge.ai/cli/stable/install-forge.sh | sh
    forge version
    ```
  </Tab>

  <Tab title="Windows">
    ```powershell theme={"system"}
    irm https://downloads.forge.ai/cli/stable/install-forge.ps1 | iex
    forge version
    ```
  </Tab>
</Tabs>

The installer selects the build for the current operating system and CPU,
verifies its published SHA-256 checksum, and installs `forge` on the command
path. macOS and Linux use `/usr/local/bin` when writable and otherwise use
`~/.local/bin`. Run the stable-channel installer again to update to its current
release. `forge version` verifies the installed version after installation or
an update.

## Authenticate

Interactive login uses OAuth device authorization and discovers the
organization bound to the resulting token:

```bash theme={"system"}
forge auth login
forge auth status
```

Use a service-account token for CI or another non-interactive environment:

```bash theme={"system"}
export FORGE_TOKEN="..."
export FORGE_ORG_ID="org_123"
forge auth status
```

You can save that credential to the active profile with
`forge auth login --token "$FORGE_TOKEN"`. Avoid doing so on ephemeral CI
runners; environment injection keeps the credential out of a persisted profile.

## Configuration

Values resolve in this order, from highest to lowest precedence:

1. Global command flags.
2. Environment variables.
3. The selected saved profile.
4. Built-in defaults.

| Flag         | Environment         | Default                                  |
| ------------ | ------------------- | ---------------------------------------- |
| `--base-url` | `FORGE_BASE_URL`    | `https://api.forge.ai`                   |
| `--token`    | `FORGE_TOKEN`       | Active profile token                     |
| `--org`      | `FORGE_ORG_ID`      | Active profile organization              |
| `--profile`  | `FORGE_PROFILE`     | `default`                                |
| —            | `FORGE_CONFIG_PATH` | OS-specific Forge credential path        |
| —            | `FORGE_CONFIG_HOME` | OS-specific user configuration directory |

Only JSON output is currently supported. `--output json` is accepted
explicitly and is the default.

Profiles isolate organizations or environments:

```bash theme={"system"}
forge --profile production auth login
forge --profile staging auth login --base-url https://api-staging.forge.ai
forge --profile production auth status
```

On supported systems, access tokens, refresh tokens, and MCP gateway tokens are
stored in the operating-system keychain. The profile stores a keychain
reference. Credential files use user-only permissions and are replaced
atomically.

## Global flags

Global flags must appear before the command group:

```text theme={"system"}
forge [global flags] <group> <command> [command flags]
```

| Flag                    | Behavior                                                                             |
| ----------------------- | ------------------------------------------------------------------------------------ |
| `--profile NAME`        | Select a saved profile.                                                              |
| `--base-url URL`        | Override the API origin.                                                             |
| `--token TOKEN`         | Override the bearer token.                                                           |
| `--org ID`              | Override the organization ID.                                                        |
| `--output json`         | Select JSON output; no other format is accepted.                                     |
| `--reason TEXT`         | Supply a mutation reason to commands that accept global safety fields.               |
| `--idempotency-key KEY` | Supply a stable mutation identity.                                                   |
| `--dry-run`             | Request a preview when supported.                                                    |
| `--confirm`             | Confirm guarded execution.                                                           |
| `--debug-request-id ID` | Attach a caller-supplied diagnostic request ID. Do not use it as operation identity. |
| `--version`             | Print version, commit, and build date.                                               |

Command-local safety flags override neither authorization nor policy. Forge
still validates the actor's role, token scopes, organization settings, and the
operation contract.

## Exit behavior

| Code | Meaning                                                              |
| ---- | -------------------------------------------------------------------- |
| `0`  | Command completed successfully.                                      |
| `1`  | Authentication, network, API, decoding, or command execution failed. |
| `2`  | Global arguments were invalid or no command was supplied.            |

Successful commands write JSON to stdout. Errors and usage text are written to
stderr. The CLI does not retry API requests automatically; automation should
apply the retry rules described in the [API guide](/developer/api).

## Guarded execution

Preview a supported write, review the JSON response, then execute with the same
reason and idempotency key:

```bash theme={"system"}
forge config publish \
  --profile profile_123 \
  --changelog "Update endpoint policy rollout" \
  --reason "Change request CHG-789" \
  --idempotency-key "chg-789-profile-123-publish" \
  --dry-run

forge config publish \
  --profile profile_123 \
  --changelog "Update endpoint policy rollout" \
  --reason "Change request CHG-789" \
  --idempotency-key "chg-789-profile-123-publish" \
  --confirm
```

One-time service-account secrets are returned only when created or rotated.
Capture them directly into a secret manager and do not persist the command
output in build artifacts.

## CI

```bash theme={"system"}
set -euo pipefail

export FORGE_TOKEN="${FORGE_CI_TOKEN:?missing FORGE_CI_TOKEN}"
export FORGE_ORG_ID="${FORGE_CI_ORG_ID:?missing FORGE_CI_ORG_ID}"

forge capabilities list > forge-capabilities.json
forge compliance snapshot > forge-compliance-snapshot.json
forge audit export-jsonl > forge-audit.jsonl
```

Use a dedicated service account whose role and scopes cover only these
commands. See [Commands](/developer/commands) for the complete command surface.

## Uninstall

```bash theme={"system"}
curl -fsSL https://downloads.forge.ai/cli/stable/install-forge.sh | sh -s -- --uninstall
```

Add `--purge` only when the local Forge credential store should also be removed.

<CardGroup cols={2}>
  <Card title="Commands" icon="list-tree" href="/developer/commands">
    Review command syntax, filters, and mutation safeguards.
  </Card>

  <Card title="API" icon="braces" href="/developer/api">
    Implement retries and inspect the underlying REST contracts.
  </Card>

  <Card title="MCP" icon="blocks" href="/developer/mcp">
    Install governed MCP servers and manage MCP sessions.
  </Card>

  <Card title="Roles" icon="key-round" href="/secure/roles">
    Configure permissions for operators and service accounts.
  </Card>
</CardGroup>