CLI Reference

The Forgecroft CLI manages runs, workspaces, and API keys from the command line. Install it with Homebrew or the curl installer.

Installation

Homebrew:

brew install forgecroft/tap/forgecroft

curl:

curl -fsSL https://forgecroft.com/install.sh | sh

Authentication

The recommended way to authenticate is the browser-based login:

forgecroft login

This opens your browser for OAuth (GitHub or Google), creates an API key, and saves it to ~/.forgecroft/config.json. To use a different provider:

forgecroft login google

Alternatively, set credentials manually:

forgecroft configure --api-url https://api.forgecroft.com --api-key fc_live_...

Or use environment variables (useful in CI):

export FORGECROFT_API_URL=https://api.forgecroft.com
export FORGECROFT_API_KEY=fc_live_...

The CLI stores configuration in ~/.forgecroft/config.json. Environment variables override the stored config.

Global Flags

Flag	Description
`--json`	Output machine-readable JSON instead of human-readable tables
`--version`	Print the CLI version

Commands

Authenticate via browser OAuth. Opens your default browser, completes the OAuth flow, and saves an API key locally.

forgecroft login           # default: GitHub
forgecroft login google    # use Google OAuth

onboard

Interactive one-click setup. Creates a project, credentials (managed mode), state backend (managed mode), and workspace in a single call.

forgecroft onboard                          # interactive prompts
forgecroft onboard --mode managed \         # non-interactive (scripting/CI)
  --project-name "Infra" \
  --cred-name "AWS Prod" \
  --cred-type aws_static \
  --backend-name "S3 State" \
  --backend-type s3 \
  --bucket my-state-bucket \
  --region us-east-1 \
  --workspace-name production \
  --repo-url https://github.com/org/infra.git

Flag	Description
`--mode`	`managed` or `agent`
`--project-name`	Project name
`--cred-name`	Credential config name (managed only)
`--cred-type`	`aws_static`, `aws_assume_role`, `gcp_service_account`, `cloudflare_api_token`, `generic_env`
`--backend-name`	State backend name (managed only)
`--backend-type`	`s3`, `gcs`, `local`
`--bucket`	State bucket name
`--region`	State bucket region
`--workspace-name`	Workspace name
`--repo-url`	Source repository URL
`--branch`	Source branch (default: `main`)
`--source-root`	Subdirectory containing HCL
`--state-key`	State file key

In agent mode, the response includes the agent API key (shown once) and install instructions.

whoami

Show your current identity, org, role, and API key scopes.

forgecroft whoami

Use --json to parse the output programmatically.

runs plan

Trigger a plan and stream logs until completion. Exits with code 0 on success, 1 on failure.

forgecroft runs plan <workspace-id>
forgecroft runs plan <workspace-id> --no-wait   # print run ID and exit
forgecroft runs plan <workspace-id> --json       # output final run as JSON

Flag	Description
`--no-wait`	Print the run ID and exit immediately without streaming logs

runs list

List runs across all workspaces you have access to.

forgecroft runs list
forgecroft runs list --workspace <id>
forgecroft runs list --project <id> --status completed
forgecroft runs list --ref abc123 --require-success

Flag	Default	Description
`--workspace`		Filter by workspace UUID
`--project`		Filter by project UUID
`--status`		Filter by status: `queued`, `in_progress`, `completed`, `failed`, `timed_out`
`--ref`		Filter by commit SHA
`--limit`	50	Max results (up to 200)
`--offset`	0	Pagination offset
`--require-success`	false	Exit 1 if no `completed` run found (see CI gating below)

runs get

Show the status and details of a single run.

forgecroft runs get <run-id>
forgecroft runs get <run-id> --json

runs logs

Fetch or stream run logs.

forgecroft runs logs <run-id>              # fetch all available logs
forgecroft runs logs --follow <run-id>     # stream logs until run completes

Flag	Description
`--follow`	Keep polling for new log lines until the run reaches a terminal status

workspaces list

List workspaces you have access to.

forgecroft workspaces list
forgecroft workspaces list --project <id>

Flag	Description
`--project`	Filter by project UUID

api-keys list

List API keys in the current org.

forgecroft api-keys list

api-keys create

Create a new API key.

forgecroft api-keys create \
  --name "CI Pipeline" \
  --scope-type project \
  --scope-id <project-id> \
  --action-scope write \
  --scopes trigger,read

Flag	Description
`--name`	Key name (required)
`--scope-type`	`org`, `project`, or `workspace`
`--scope-id`	UUID of the project or workspace (omit for org-scoped)
`--action-scope`	`read`, `write`, or `admin`
`--scopes`	Comma-separated verb/capability scopes (e.g., `trigger,read,approve`)

The raw key value is printed once on creation. Store it securely — it cannot be retrieved again.

api-keys delete

Permanently delete an API key.

forgecroft api-keys delete <key-id>

api-keys suspend / unsuspend

Temporarily disable or re-enable an API key. Suspended keys are immediately rejected on use but can be re-enabled.

forgecroft api-keys suspend <key-id>
forgecroft api-keys unsuspend <key-id>

CI Gating with —require-success

Use runs list --require-success to gate CI pipelines on Forgecroft run results. This is useful for merge checks:

# In a GitHub Actions step:
forgecroft runs list \
  --workspace $WORKSPACE_ID \
  --ref ${{ github.sha }} \
  --require-success

This exits 0 if at least one completed run exists for the given filters, or exits 1 otherwise. Combine with --ref to check the specific commit.

JSON Output

All commands support --json for machine-readable output:

# Get workspace list as JSON
forgecroft --json workspaces list | jq '.[].name'

# Trigger a plan and get the final result as JSON
forgecroft --json runs plan <workspace-id> | jq '{status, added_count}'

API-First Quickstart — full curl-based setup walkthrough
Go SDK — build custom integrations in Go
API Keys — scope types, verb scopes, and key lifecycle