CLI

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

macOS and Linux
Windows

curl -fsSL https://downloads.forge.ai/cli/stable/install-forge.sh | sh
forge version

irm https://downloads.forge.ai/cli/stable/install-forge.ps1 | iex
forge version

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:

forge auth login
forge auth status

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

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:

Global command flags.
Environment variables.
The selected saved profile.
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:

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:

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.

Guarded execution

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

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

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 for the complete command surface.

Uninstall

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.

Commands

Review command syntax, filters, and mutation safeguards.

API

Implement retries and inspect the underlying REST contracts.

MCP

Install governed MCP servers and manage MCP sessions.

Roles

Configure permissions for operators and service accounts.

Guides

REST API

Install

Authenticate

Configuration

Global flags

Exit behavior

Guarded execution

CI

Uninstall

Commands

API

MCP

Roles

​Install

​Authenticate

​Configuration

​Global flags

​Exit behavior

​Guarded execution

​CI

​Uninstall

Commands

API

MCP

Roles

Install

Authenticate

Configuration

Global flags

Exit behavior

Guarded execution

CI

Uninstall