Forgecroft Docs
Quickstart Guides Essentials Power CLI Agent API Reference
OverviewGetting StartedCI UsageCoding AgentsCommand Reference
CLI

Using the CLI in CI

Gate merges on Forgecroft run results with a scoped API key and a single command.

The CLI is designed to drop into any CI system — GitHub Actions, GitLab CI, CircleCI, Buildkite, or a bare shell script. The pattern is always the same.

1. Create a scoped API key

Do not use your personal login key in CI. Create a key that can only do what the pipeline needs:

forgecroft api-keys create \
  --name "GitHub Actions — infra" \
  --scope-type project \
  --scope-id <project-id> \
  --action-scope write \
  --scopes trigger,read

This key can trigger plans and read results. It cannot approve runs, manage API keys, or touch other projects. Store the printed key in your CI secret store (for example, FORGECROFT_API_KEY in GitHub Actions).

See API Keys for the full scope reference.

2. Install and authenticate in the job

# .github/workflows/infra.yml
- name: Install Forgecroft CLI
  run: curl -sSfL https://install.forgecroft.com | sh

- name: Trigger plan
  env:
    FORGECROFT_API_URL: https://api.forgecroft.com
    FORGECROFT_API_KEY: ${{ secrets.FORGECROFT_API_KEY }}
  run: forgecroft runs plan ${{ vars.FORGECROFT_WORKSPACE_ID }}

forgecroft runs plan blocks until the run reaches a terminal state and exits 0 on success, 1 on failure. That alone is enough to gate a job.

3. Gate a merge on a previous run

For pull-request merge checks, you often want to fail if the latest run for the PR commit is not successful — without triggering a new run. Use runs list --require-success:

forgecroft runs list \
  --workspace $FORGECROFT_WORKSPACE_ID \
  --ref ${{ github.sha }} \
  --require-success

This exits 0 if at least one completed run exists for the given filters, or 1 otherwise. Pair it with --status completed for even tighter checks.

4. JSON output for downstream steps

Any command accepts --json for machine-readable output:

STATUS=$(forgecroft --json runs get $RUN_ID | jq -r '.status')
if [ "$STATUS" != "completed" ]; then
  echo "Run $RUN_ID did not complete: $STATUS" >&2
  exit 1
fi

Key hygiene