Installation & Authentication

Install

npm install -g @beachio/forge-cli

Requires Node.js 18 or later.

Verify Installation

forge --version
forge --help

Authentication

Forge CLI supports multiple authentication methods for different workflows.

Interactive Login

forge login                              # Prompts for email and password
forge login --email me@example.com       # Prompts for password only

Direct Token

forge login --with-token <cli-token>     # Store a pre-existing CLI token

Browser Login (OAuth2)

forge login --browser                    # Opens browser for authentication

Environment Variables

For CI/CD pipelines and automation:

export FORGE_TOKEN=<cli-token>           # CLI token for general access
export FORGESITETOKEN=<site-token>     # Site token for deploy-only access

Check Auth Status

forge whoami                             # Show current user, token type, and org context

Logout

forge logout                             # Clear stored credentials

Token Management

Create scoped tokens for CI/CD and AI agents:

forge token create

forge token create --name "CI Deploy" --scopes sites:deploy --site-ids 101,102

forge token create --name "AI Agent" --scopes sites:deploy --site-ids 101 --expires-in-days 7

forge token list

forge token revoke <id>

Token Create Options

Option	Description	Default
--name	Human-readable label	—
--scopes	Comma-separated scopes	unrestricted
--site-ids	Comma-separated site IDs to restrict access	all sites
--expires-in-days	Days until token expires	90

Available Scopes

Scope	Grants
sites:read	List sites, view version info
sites:write	Create new sites
sites:deploy	Deploy to sites
forms:read	Read form submissions
analytics:read	Read site analytics
bandwidth:read	Read bandwidth usage
organisations:read	Read organisations
organisations:write	Manage organisations

Tokens created with no scopes have unrestricted access.

Project Configuration

Initialize

forge init                               # Create forge.json interactively
forge init --force                       # Overwrite existing forge.json

Creates a forge.json in your project root:

{
  "site": "my-site.getforge.io",
  "deploy_directory": ".",
  "compiler": "none",
  "ignore": ["node_modules", ".git", ".env"]
}

Property	Description
site	Site URL to deploy to
site_token	Site token (optional, alternative to CLI token)
deploy_directory	Directory to deploy (default: .)
compiler	Compiler mode (none, jekyll, middleman, etc.)
ignore	Patterns to exclude from deployment

.forgeignore

You can create a .forgeignore file with gitignore-style patterns to exclude files from deployment. This works alongside the ignore array in forge.json.

Site Resolution

For commands that operate on a site, the target is resolved in this order:

1. --site flag on the command
2. --site-token global option
3. site or site_token in forge.json
4. Stored site tokens from login