Forge CLI: terminal access to a running instance

forge-mcp gives your AI agent typed tools for content operations. forge-cli gives you the same access from the terminal.

The agent has MCP. The operator has the CLI. Both call the same Forge HTTP API. Both authenticate with a bearer token. Both operate under the same role-based access rules. The interface is different -- the access model is identical.

forge-cli ships as a separate Go module, not part of forge core.

Content operations

forge-cli <type> <verb>

forge-cli post create --from draft.md
forge-cli post update my-post --from updated.md
forge-cli post publish my-post
forge-cli post unpublish my-post
forge-cli post archive my-post
forge-cli post delete my-post
forge-cli post list --status draft
forge-cli post get my-post

--from <file> reads field values from a markdown file with YAML frontmatter. The same struct validation that applies to MCP calls and HTTP submissions applies here.

list accepts --status to filter by draft, scheduled, published, or archived. Without a filter it returns all items the current token has access to read.

Token management

Token operations require Admin role.

forge-cli token create editor-agent editor 720h
forge-cli token list
forge-cli token revoke <id>

create takes a name, role, and TTL. The token is printed once on creation -- it is not stored by the CLI.

The revoke command calls the same endpoint as revoke_token in forge-mcp. A token revoked via CLI is immediately invalid for any client using it, including agents.

Media operations

forge-cli media upload photo.jpg --description "Aerial view of the conference venue"
forge-cli media list --type image
forge-cli media delete <id>

--description is required on upload. The CLI enforces the same alt text requirement as the MCP tool and the HTTP upload endpoint. There is no path to an unlabelled file.

Connectivity check

forge-cli status

Checks connectivity to the configured Forge instance and reports the framework version from /_health. Useful for verifying that a token is valid and the instance is reachable before running a batch operation.

Configuration

forge-cli reads the Forge instance URL and token from environment variables or a local config file. It does not store credentials -- the operator manages the token lifecycle via forge-cli token or directly through the admin interface.

When to use the CLI vs MCP

The CLI is an operator tool -- suited for manual operations, batch scripts, CI pipelines, and situations where you want direct terminal access without setting up an MCP client. The MCP tools are suited for AI agents operating autonomously within a session.

The boundary is the same one that exists in the four-audiences model: agents use the operations layer (MCP), operators use the CLI. The infrastructure underneath is the same.