Advanced CLI

This guide covers advanced Forge CLI patterns for power users, CI/CD pipelines, and automation workflows. For basic commands, see CLI Usage.

JSON Output Mode

All Forge CLI commands support --json for machine-readable output, useful in scripts and CI pipelines:

forge sites --json
forge info --json
forge deploy --json
forge versions --json

JSON output includes structured data with consistent field names, making it easy to parse with tools like jq:

forge sites --json | jq '.[].name'

CI/CD Integration

GitHub Actions

Deploy on every push to your main branch:

name: Deploy to Forge
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:

uses: actions/checkout@v4

name: Install Forge CLI run: npm install -g @beachio/forge-cli

name: Deploy env: FORGETOKEN: ${{ secrets.FORGETOKEN }} run: forge deploy --json

Using Site Tokens

For deploy-only access without full account permissions, use a site token instead:

- name: Deploy
  env:
    FORGESITETOKEN: ${{ secrets.FORGESITETOKEN }}
  run: forge deploy --json

Site tokens are scoped to a single site and can only deploy -- they cannot list sites, change settings, or access other resources.

Other CI Platforms

The Forge CLI works in any environment with Node.js. Set FORGETOKEN or FORGESITE_TOKEN as an environment variable and install the CLI via npm:

npm install -g @beachio/forge-cli
forge deploy --json

Working with Multiple Sites

Linking Directories

Each project directory can be linked to a Forge site via forge.json:

forge add my-site.getforge.io

This writes a forge.json file in the current directory so subsequent commands target the correct site without --site flags.

Targeting Specific Sites

Override the linked site for any command:

forge deploy --site staging.getforge.io
forge info --site production.getforge.io
forge settings --site my-site.getforge.io --ssl on

Automation Scripts

Deploy with Rollback on Failure

#!/bin/bash
SITE="my-site.getforge.io"
CURRENT=$(forge versions --site "$SITE" --json | jq -r '.[0].id')

forge deploy --site "$SITE" --json
if [ $? -ne 0 ]; then
  echo "Deploy failed, rolling back to version $CURRENT"
  forge rollback --site "$SITE" --version-id "$CURRENT"
fi

Environment-Based Deploys

#!/bin/bash
if [ "$1" = "production" ]; then
  forge deploy --site prod.getforge.io -m "Production deploy $(date)"
elif [ "$1" = "staging" ]; then
  forge deploy --site staging.getforge.io -m "Staging deploy $(date)"
fi

Token Management

Creating CLI Tokens

forge token create

Tokens are long-lived and provide full CLI access to your account. Store them securely in CI/CD secrets.

Listing and Revoking Tokens

forge token list
forge token revoke <token-id>

Revoke tokens that are no longer needed or may have been compromised.

Organisation Context

When working across multiple organisations:

forge orgs                           # List your organisations
forge org switch --id 123            # Switch to an organisation
forge sites                          # Now shows sites for org 123
forge org switch --id personal       # Switch back to personal

All commands respect the current organisation context. Use --org flags on individual commands for one-off operations without switching context:

forge sites --org 123
forge create --name new-site --org 123

.forgeignore

Control which files are excluded from deploys by creating a .forgeignore file in your project root. It follows .gitignore syntax:

node_modules/
.git/
.env
*.log
.DS_Store

This reduces upload size and prevents sensitive files from being deployed.