> ## 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.

# Commands

> Forge CLI command syntax, filters, output behavior, and guarded mutations.

Every command returns the JSON response from its corresponding public API
operation. Identifiers such as `GROUP_ID`, `SESSION_ID`, and `POLICY_ID` are
opaque Forge IDs unless the command explicitly accepts a registry slug.

## Read commands

### Core

```text theme={"system"}
forge capabilities list
forge sessions list
forge sessions show SESSION_ID
forge entities list
forge entities show ENTITY_ID
forge findings list
forge findings show FINDING_ID
```

`capabilities list` returns authorization metadata for the active actor.
Session, entity, and finding commands require an organization.

Search and list commands return a bounded page rather than an implicit full
export. Follow the response's cursor, offset, or page fields until its
continuation indicator is empty. Totals returned by aggregate operations are
computed across the complete matching scope; their dimension breakdowns remain
bounded to the limits declared by the operation.

### Inventory

```text theme={"system"}
forge inventory list [--query TEXT] [--kind KIND] [--source-adapter KEY] [--surface SURFACE] [--limit N]
forge inventory show GROUP_ID
forge inventory components --group GROUP_ID [--limit N]
forge inventory mcp-config-files [--family FAMILY] [--state STATE] [--mcp-server ID] [--limit N]
forge inventory mcp-servers [--family FAMILY] [--state STATE] [--mcp-server ID] [--limit N]
forge inventory mcp-tools [--family FAMILY] [--state STATE] [--mcp-server ID] [--limit N]
forge inventory shadow-ai [--query TEXT] [--category CATEGORY] [--limit N]
```

`inventory list` searches grouped inventory. `components` expands one group.
The MCP inventory commands query discovered configuration files, servers, or
tools rather than registry definitions.

### Audit and compliance

```text theme={"system"}
forge audit search [--limit N] [--cursor CURSOR] [--action ACTION] [--target-type TYPE] [--target-id ID] [--actor-console-user-id ID] [--occurred-after RFC3339] [--occurred-before RFC3339]
forge audit anomalies
forge audit export-jsonl
forge compliance snapshot
forge compliance export [json|csv|pdf]
```

`audit export-jsonl` writes JSON Lines, not a JSON array. Compliance export
defaults to `json`.

### Fleet and configuration

```text theme={"system"}
forge fleet devices
forge fleet devices show DEVICE_ID
forge fleet show DEVICE_ID
forge fleet summary
forge config profiles
forge config rollout-states
forge config inventory-snapshots
forge config assignments
```

### Policies and violations

```text theme={"system"}
forge policies schema
forge policies list content|access|skill-acl
forge policies get FAMILY POLICY_ID
forge policies export content|access POLICY_ID --out POLICY.json [--revision N]
forge policies revisions FAMILY POLICY_ID
forge policies backtests list [--page N] [--limit N]
forge policies backtests get RUN_ID
forge policies backtests events [--result RESULT] [--page N] [--limit N] RUN_ID
forge violations list [--policy POLICY_ID] [--action ACTION] [--session SESSION_ID] [--finding-linked VALUE] [--include-evidence] [--limit N]
```

`--finding-linked` accepts `all`, `true`, `false`, or `linked`.

`policies export` writes only the canonical saved definition. Use `--revision`
to pin the exact immutable revision that produced a policy hit; omit it to pull
the current revision into Git. A policy definition can be backtested before
deployment with `forge policies backtests run --family FAMILY --file
POLICY.json --mode quick`.

Policy-as-code validation and packaging:

```text theme={"system"}
forge policies rego-format --file MODULE.rego [--check]
forge policies rego-schema --family content|access
forge policies rego-validate --family content|access --file MODULE.rego [--input INPUT.json]
forge policies rego-lint --family content|access --file MODULE.rego [--input INPUT.json]
forge policies rego-compile --family content|access --file MODULE.rego [--input INPUT.json]
forge policies rego-test --family content|access --file MODULE.rego --input INPUT.json
forge policies rego-explain --family content|access --file MODULE.rego --input INPUT.json

forge policies package-validate --archive PACKAGE.zip
forge policies package-test --archive PACKAGE.zip
forge policies package-lock --archive PACKAGE.zip
forge policies package-export --archive PACKAGE.zip --out CANONICAL.zip
```

`rego-format` runs locally using Rego v1. Other Rego commands submit the bounded
module and optional input to Forge's policy-code validation contract.
The package commands support fixture-backed regression tests through
`tests.json`. See the repository's `examples/detection-as-code` directory for
a minimal GitHub Actions workflow.

### Governance and approvals

```text theme={"system"}
forge governance requests
forge governance request REQUEST_ID
forge governance grants
forge governance interventions
forge approvals list [--status STATUS]
forge approvals mine
forge approvals show APPROVAL_ID
```

## Registry commands

### MCP servers

```text theme={"system"}
forge mcp list [--status approved]
forge mcp show SERVER
forge mcp install SERVER [--client claude-code|codex] [--config PATH] [--credential VALUE]
forge mcp status [SERVER] [--client claude-code|codex]
forge mcp uninstall SERVER [--client claude-code|codex] [--config PATH]
forge mcp run SERVER
forge mcp sessions
```

`SERVER` accepts the registry item slug or ID. Install modifies only the
selected client's MCP entry and records the installation in the active Forge
profile. `run` provides a local stdio bridge for clients that cannot use the
remote gateway directly.

Upstream OAuth administration:

```text theme={"system"}
forge mcp oauth-discover --url URL [--provider PROVIDER]
forge mcp oauth-register-upstream SERVER [--client-name NAME] [--redirect-uri URI] [--scopes CSV] [--no-persist] [--no-discovery]
```

### Skills

```text theme={"system"}
forge skills list [--status approved]
forge skills show SKILL
forge skills install SKILL [--client claude-code|codex] [--root PATH]
forge skills status [SKILL] [--client claude-code|codex]
forge skills uninstall SKILL [--client claude-code|codex] [--root PATH]
```

Forge verifies every packaged file's size and SHA-256 digest before writing it.
Install refuses to replace a directory that is not marked as Forge-managed.

### Deployments

```text theme={"system"}
forge deploy init --name NAME [--slug SLUG] [--config forge.yaml] [--host URL] [--force]
forge deploy validate [--config forge.yaml] [--env-file .env] [--host URL]
forge deploy [--config forge.yaml] [--env-file .env] [--host URL] [--runtime-adapter ADAPTER] [--runtime-url URL] [--image IMAGE]
```

`init` creates the server-side deployment draft and writes its starter
`forge.yaml` with mode `0600`; it refuses to overwrite an existing file unless
`--force` is present. Validation expands `${VAR}` references from `--env-file`
and then the process environment. Deployment validates before submitting and
defaults to the `local_docker` runtime adapter.

## Write commands

The following signatures show their required safety inputs. A command can
still require additional domain values.

```text theme={"system"}
forge findings transition --finding ID --status STATUS --reason TEXT --idempotency-key KEY --confirm

forge fleet validate --devices CSV --source-adapters CSV --reason TEXT --idempotency-key KEY [--dry-run] [--confirm]
forge fleet repair --devices CSV --source-adapters CSV --reason TEXT --idempotency-key KEY [--dry-run] [--confirm]
forge fleet rotate-token --devices CSV --source-adapters CSV --reason TEXT --idempotency-key KEY [--dry-run] [--confirm]

forge config preview --profile ID --reason TEXT --idempotency-key KEY
forge config publish --profile ID [--changelog TEXT] --reason TEXT --idempotency-key KEY [--dry-run] [--confirm]
forge config rollback --profile ID --source-release ID [--changelog TEXT] --reason TEXT --idempotency-key KEY [--dry-run] [--confirm]

forge mcp create-token SERVER --name NAME [--expires-days DAYS]
forge mcp rotate-token SERVER --token TOKEN_ID [--name NAME] [--expires-days DAYS] --confirm
forge mcp revoke-token SERVER --token TOKEN_ID --confirm
forge mcp revoke-session --session ID --reason TEXT --idempotency-key KEY --confirm
```

Use `forge mcp tokens SERVER` to find token IDs and review non-secret
credential metadata. Gateway token secrets are returned only when created or
rotated.

Governance mutations:

```text theme={"system"}
forge governance resolve --request ID --decision approve|deny [--justification TEXT] --reason TEXT --idempotency-key KEY
forge governance revoke-grant --grant ID --reason TEXT --idempotency-key KEY [--dry-run] [--confirm]
forge governance create-intervention --entity-type TYPE --entity ID --action ACTION --reason TEXT --idempotency-key KEY
forge governance clear-intervention --intervention ID --reason TEXT --idempotency-key KEY
```

MCP approval mutations:

```text theme={"system"}
forge approvals create-mcp --mcp-server ID [--business-use-case TEXT] [--urgency VALUE] [--target-app APP] [--target-project REF] [--target-team TEAM] [--run-scanner] --reason TEXT --idempotency-key KEY --confirm
forge approvals approve --approval ID --reason TEXT --idempotency-key KEY --confirm
forge approvals deny --approval ID --justification TEXT --reason TEXT --idempotency-key KEY --confirm
forge approvals run-scanner --approval ID [--directory-users CSV] --reason TEXT --idempotency-key KEY --confirm
forge approvals update-suggestion --approval ID --suggestion ID --payload JSON --reason TEXT --idempotency-key KEY --confirm
```

Service-account administration:

```text theme={"system"}
forge service-accounts list
forge service-accounts create --name NAME [--role ROLE] [--scopes CSV] --reason TEXT --idempotency-key KEY --confirm
forge service-accounts update --service-account ID [--name NAME] [--description TEXT] [--role ROLE] [--scopes CSV] --reason TEXT --idempotency-key KEY --confirm
forge service-accounts rotate-token --service-account ID [--scopes CSV] --reason TEXT --idempotency-key KEY --confirm
forge service-accounts revoke-token --service-account ID --token ID --reason TEXT --idempotency-key KEY [--dry-run] [--confirm]
forge service-accounts disable --service-account ID --reason TEXT --idempotency-key KEY --confirm
```

Organization automation settings:

```text theme={"system"}
forge settings get
forge settings update \
  [--service-accounts-enabled BOOL] \
  [--mcp-enabled BOOL] \
  [--mcp-read-only BOOL] \
  [--block-destructive-mcp BOOL] \
  [--built-in-agent-enabled BOOL] \
  [--max-token-seconds N] \
  [--allowed-scopes CSV] \
  [--allowed-cidrs CSV] \
  --reason TEXT --idempotency-key KEY --confirm
```

Boolean settings are complete desired values, not toggles. Read current
settings before constructing an update.

Policy writes:

```text theme={"system"}
forge policies apply --family content|access|skill-acl --file POLICY.json [--revision CURRENT_REVISION]
forge policies restore --expected CURRENT_REVISION FAMILY POLICY_ID HISTORICAL_REVISION
```

`apply` creates when `--revision` is zero or omitted. A positive revision
performs an optimistic update of the policy ID inside the JSON document.
`restore` creates a new current revision from the selected historical revision;
it does not rewrite revision history.

## Script parsing

Treat JSON fields as a versioned API response, not formatted terminal text:

```bash theme={"system"}
forge inventory list --kind agent --limit 25 |
  jq -r '.items[] | [.id, .displayName] | @tsv'
```

Do not parse stderr. On API failure the CLI returns exit code `1` and writes a
redacted error message to stderr.