forge-cli — Forge Docs

forge-cli is the operator CLI for a running Forge instance. It manages content, tokens, and media over HTTP using the same REST API your site exposes.

Install

go install forge-cms.dev/forge-cli@latest

Configuration

forge-cli reads two environment variables:

Variable	Description
`FORGE_URL`	Base URL of your Forge instance, e.g. `https://yoursite.com`
`FORGE_TOKEN`	Bearer token with appropriate role

Both can be stored in .forge-cli.env in the working directory. The forge-cli init command writes this file for you.

Commands

init — bootstrap a new instance

forge-cli init [--url URL] [--bootstrap-token TOKEN] [--name NAME] [--days N] [--force]

Creates a named admin token from the bootstrap token and writes .forge-cli.env. Use --force to overwrite an existing env file. See Deploy & first start for the full workflow.

status — connectivity check

forge-cli status

Checks reachability and reports the connected instance URL and token role.

Content operations

type is the URL path segment for your content module — e.g. posts, doc-pages.

Command	Description
`forge-cli <type> create --from <file>`	Create a new draft from a JSON file
`forge-cli <type> update <slug> --from <file>`	Update fields (absent fields are preserved)
`forge-cli <type> publish <slug>`	Transition to published
`forge-cli <type> unpublish <slug>`	Revert published item to draft
`forge-cli <type> archive <slug>`	Transition to archived
`forge-cli <type> delete <slug>`	Permanently delete
`forge-cli <type> list [--status ...]`	List items, optionally filtered by status
`forge-cli <type> get <slug>`	Fetch a single item

Token management (Admin role required)

Command	Description
`forge-cli token create <name> <role> <ttl-days>`	Issue a new named token
`forge-cli token list`	List all tokens
`forge-cli token revoke <id>`	Revoke a token by ID

Media

Command	Description
`forge-cli media upload <file> [--description <text>]`	Upload a file to the media library
`forge-cli media list [--type image\|document\|video\|other]`	List media records
`forge-cli media delete <id>`	Permanently delete a media record

Requires forge-media to be wired into your Forge app.

Webhook management

The webhook command manages outbound webhook endpoints and delivery jobs. All webhook operations require an Admin role token.

forge-cli communicates with your Forge instance via the MCP endpoint (FORGE_MCP_URL, default: FORGE_URL/mcp/message). Set the required variables in your environment or .forge-cli.env file before running any webhook commands.

forge webhook create

forge webhook create --url <URL> --events <event1,event2,...>

Flags

Flag	Required	Description
`--url`	Yes	HTTPS URL to deliver events to. Must be a public address — private IPs and localhost are rejected.
`--events`	Yes	Comma-separated list of event names to subscribe to.

Event name format: <type>.<lifecycle> — for example post.published, post.updated, post.deleted. The type matches the content type prefix you registered with forge.At(...).

Output

The command prints the endpoint ID and the signing secret — a 32-byte random value returned once. Copy it immediately and store it securely. It cannot be retrieved again.

endpoint: ep_abc123
secret:   dGhpcyBpcyBhIHRlc3Qgc2VjcmV0

forge webhook list

List all registered endpoints with basic delivery statistics.

forge webhook list

Secrets are never returned in list output.

forge webhook delete

Permanently remove an endpoint by ID. Delivery jobs already queued for this endpoint are not affected.

forge webhook delete <endpoint-id>

forge webhook deliveries

Show delivery logs for a specific job or all jobs for an endpoint.

forge webhook deliveries --job <job-id>
forge webhook deliveries --endpoint <endpoint-id>

Each log entry shows the attempt time, HTTP status code, duration, and any error message.

forge webhook retry

Re-queue a dead-lettered job for delivery. Resets the attempt counter to zero.

forge webhook retry <job-id>

A job reaches dead-letter status after 7 failed delivery attempts. Use forge webhook deliveries to find the job ID.

Environment variables

Variable	Required	Description
`FORGE_URL`	Yes	Base URL of your Forge instance, e.g. `https://yoursite.com`
`FORGE_TOKEN`	Yes	Bearer token with Admin role
`FORGE_MCP_URL`	No	MCP message endpoint. Defaults to `FORGE_URL/mcp/message` if not set.

Both can be set in .forge-cli.env in the current directory.