@forgegraph/cli

The ForgeGraph CLI (forge) for developers, CI runners, and AI agents. Deploy, review, and manage delivery from the terminal.

ForgeGraph is the canonical delivery graph for changes moving from review through staging and production. The CLI gives you full control over apps, deployments, secrets, NixOS fleet management, and more — without leaving the terminal.

Installation

npm install -g @forgegraph/cli

This installs the forge command globally. The package automatically selects the correct native binary for your platform (macOS/Linux, x64/ARM64).

Supported Platforms

| Platform | Architecture | Package | | --------------- | ------------ | ------------------------------ | | macOS | ARM64 (M1+) | @forgegraph/cli-darwin-arm64 | | macOS | x64 (Intel) | @forgegraph/cli-darwin-x64 | | Linux | ARM64 | @forgegraph/cli-linux-arm64 | | Linux | x64 | @forgegraph/cli-linux-x64 |

Quick Start

1. Configure your server

forge config set server https://forge.example.com

Or set the FG_SERVER environment variable.

2. Authenticate

# Interactive (opens browser)
forge login

# CI / headless
forge login --token <YOUR_API_TOKEN>

# Device authorization (headless, no token)
forge login --device

3. Initialize a project

cd my-project
forge init

This creates a .forgegraph.yaml in your repo linking it to a ForgeGraph app.

4. Check your setup

forge doctor

Verifies that Nix, your flake, server connection, and repo config are all healthy.

Configuration

forge reads configuration from multiple sources with this precedence (highest wins):

1. CLI flags — --server, --json, --verbose
2. Environment variables — FG_SERVER, FG_APP
3. Repo config — .forgegraph.yaml in the current directory
4. Global config — ~/.forgegraph/config.yaml

Global config

forge config set server https://forge.example.com
forge config set app my-app
forge config set stage production
forge config get server

Per-repo config (.forgegraph.yaml)

app: my-app
server: https://forge.example.com

Command Reference

Authentication

| Command | Description | | ---------------- | ------------------------------------ | | forge login | Authenticate with a ForgeGraph server | | forge logout | Clear stored credentials | | forge whoami | Show current user and server |

Applications

| Command | Description | | ------------------------- | ---------------------------- | | forge app list | List all applications | | forge app show <slug> | Show application details | | forge app create <name> | Create a new application | | forge app delete <slug> | Delete an application |

Deployments

| Command | Description | | ---------------------- | ---------------------------------------- | | forge deploy create | Create a new deployment | | forge deploy status | Check deployment status | | forge deploy history | Show deployment history | | forge deploy promote | Promote a deployment to next stage | | forge deploy abort | Abort a running deployment | | forge rollback | Rollback to a previous deployment |

Stages

| Command | Description | | ------------------------- | ---------------------------------- | | forge stage list | List stages for the current app | | forge stage add <name> | Add a new stage | | forge stage show <name> | Show stage details | | forge stage rm <name> | Remove a stage |

Nodes

| Command | Description | | ------------------------- | ------------------------ | | forge node list | List all registered nodes | | forge node show <name> | Show node details | | forge node rm <name> | Remove a node |

Secrets

| Command | Description | | ------------------------------- | ---------------------------------- | | forge secret list | List secrets for app/stage | | forge secret set <name> <val> | Set an encrypted secret | | forge secret get <name> | Retrieve a secret | | forge secret rm <name> | Remove a secret | | forge secret pull | Download secrets from server | | forge secret diff | Show uncommitted secret changes | | forge secret check | Validate secret format |

Changesets

| Command | Description | | ---------------------------- | ---------------------------------------- | | forge changeset list | List changesets | | forge changeset show <id> | Show changeset details | | forge changeset create | Create a changeset | | forge changeset diff | Show changeset diff | | forge changeset attest | Attest to an evidence gate | | forge changeset ready | Mark changeset ready for release |

forge cs is an alias for forge changeset.

Pull Requests

| Command | Description | | ---------------------------- | ------------------------------ | | forge pr list | List pull requests | | forge pr show <num> | Show PR details | | forge pr create | Create a new PR | | forge pr merge | Merge a PR | | forge pr close | Close a PR | | forge pr comment | Add a comment | | forge pr approve | Approve a PR | | forge pr request-changes | Request changes on a PR |

Releases

| Command | Description | | ------------------------- | ------------------------------ | | forge release create | Create a new release | | forge release list | List releases | | forge release show <id> | Show release details | | forge release promote | Promote a release candidate | | forge release abort | Abort a release | | forge release history | Show release history |

CI/CD

| Command | Description | | -------------------- | ------------------------ | | forge ci status | Show current CI status | | forge ci list | List CI runs | | forge ci logs | Show CI logs | | forge ci retry | Retry a failed CI run |

Evidence

| Command | Description | | ---------------------- | ---------------------------------------------- | | forge evidence push | Push evidence (JUnit, coverage, screenshots) | | forge evidence list | List evidence artifacts | | forge evidence show | Show evidence details |

Stack Management

| Command | Description | | ------------------------- | ---------------------------------------- | | forge stack validate | Validate stack manifest syntax | | forge stack show | Display current stack | | forge stack apply | Apply stack to running deployment | | forge stack generate-nix| Generate NixOS config from stack |

Edge Proxy

| Command | Description | | -------------------- | ------------------------------------ | | forge edge sync | Sync routes to edge proxy (Caddy) | | forge edge show | Display current edge config | | forge route list | List all edge routes | | forge route add | Add an edge route | | forge route remove | Remove an edge route |

NixOS Fleet

| Command | Description | | ------------------------------ | ----------------------------------- | | forge nixos machines list | List NixOS machines | | forge nixos machines show | Show machine details | | forge nixos machines assign | Assign configuration to machine | | forge nixos deploy | Deploy NixOS config | | forge nixos rollback | Rollback to previous generation | | forge nixos drift | Detect configuration drift | | forge nixos gc | Garbage collect unused packages | | forge nixos eval | Evaluate flake configuration | | forge nixos diff | Show configuration differences | | forge nixos audit | Audit configuration changes |

Monitoring

| Command | Description | | -------------------------------- | ------------------------------ | | forge monitoring logs | View application logs | | forge monitoring health | Check health status | | forge monitoring metrics | Show performance metrics | | forge monitoring events | List system events | | forge monitoring alerts list | List active alerts | | forge monitoring alerts ack | Acknowledge an alert |

Import & Migration

| Command | Description | | -------------------------- | ------------------------------------ | | forge import helm | Import Helm charts | | forge import compose | Import Docker Compose | | forge import k8s | Import Kubernetes manifests | | forge introspect | Discover workloads from live cluster | | forge migrate-secrets | Migrate K8s secrets to ForgeGraph |

Admin

| Command | Description | | ------------------------ | ------------------------ | | forge admin user list | List users | | forge admin user invite| Invite a user | | forge admin user rm | Remove a user | | forge admin runners | Manage CI runners | | forge admin cache | Manage caches | | forge admin gc | Garbage collect |

Utility

| Command | Description | | -------------------- | ------------------------------------------ | | forge status | Show delivery status with evidence summary | | forge doctor | Check Nix, flake, server, and repo config | | forge open | Open ForgeGraph UI in the browser | | forge version | Print CLI version | | forge completions | Generate shell completions (bash/zsh/fish) |

Global Flags

| Flag | Description | | ----------- | ---------------------------------- | | --json | Output in JSON format | | --verbose | Enable verbose/debug output | | --server | Override the ForgeGraph server URL |

CI / Scripting

The --json flag on every command makes forge scriptable. Combine with jq for automation:

# Get the latest deployment status as JSON
forge deploy status --json | jq '.status'

# List all apps and extract slugs
forge app list --json | jq '.[].slug'

# Use in CI with token auth
export FG_SERVER=https://forge.example.com
forge login --token "$FG_TOKEN"
forge deploy create --stage production --wait

Environment Variables

| Variable | Description | | ----------- | ----------------------------- | | FG_SERVER | ForgeGraph server URL | | FG_APP | Default application slug |

Shell Completions

Generate completions for your shell:

# Bash
forge completions bash > /etc/bash_completion.d/forge

# Zsh
forge completions zsh > "${fpath[1]}/_forge"

# Fish
forge completions fish > ~/.config/fish/completions/forge.fish

Architecture

@forgegraph/cli is a thin Node.js wrapper that resolves and executes a platform-specific native binary. The binary is written in Go and compiled for each supported platform.

@forgegraph/cli                 # Main package (shim)
  ├── optionalDep: @forgegraph/cli-darwin-arm64
  ├── optionalDep: @forgegraph/cli-darwin-x64
  ├── optionalDep: @forgegraph/cli-linux-arm64
  └── optionalDep: @forgegraph/cli-linux-x64

npm/pnpm/yarn only installs the platform package matching your OS and architecture. The shim finds and executes the native binary, forwarding all arguments.

Building from Source

If you have Go installed, you can build the CLI directly:

cd agent
go build -o forge ./cmd/fg

Or cross-compile for all platforms:

./scripts/build-cli.sh

License

MIT