CLI Reference

The Forgexa CLI (forgexa) is a lightweight command-line client for managing workspaces, projects, requirements, executions, and gates from the terminal.

Prerequisites

The Forgexa CLI is a Python package. Python 3.9 or later is required.

Check Your Python Version

# macOS / Linux
python3 --version

# Windows
python --version

You should see Python 3.9.x or higher. If the command is not found, or the version is below 3.9, install Python before proceeding.

Install Python

1. Download the Windows installer from python.org/downloads.
2. Run the installer. On the first screen, check "Add Python to PATH" before clicking Install.
3. Verify in a new terminal window:

   python --version

Do not use the Microsoft Store version

Windows 11 ships a python.exe placeholder in %LOCALAPPDATA%\Microsoft\WindowsApps that opens the Store instead of running Python. Always install from python.org.

Check pip

pip is bundled with Python 3.9+. Verify it is available:

# macOS / Linux
python3 -m pip --version

# Windows
python -m pip --version

If pip is missing, install it:

python3 -m ensurepip --upgrade

Installation

# From PyPI
pip install forgexa-cli

# Or with pipx (recommended for isolated install)
pipx install forgexa-cli

# Verify
forgexa version

Upgrade

The CLI is updated frequently alongside the platform. It is recommended to upgrade after each platform release.

Method 1 — Upgrade with pip or pipx

# Upgrade with pip
pip install --upgrade forgexa-cli

# Upgrade with pipx
pipx upgrade forgexa-cli

# Check the installed version
forgexa version

Method 2 — Upgrade from the CLI itself

# Upgrade to the latest published release
forgexa upgrade

# Upgrade to a specific published release
forgexa upgrade --target-version 1.12.3

# Check the installed version
forgexa version

forgexa upgrade detects whether the CLI was installed with pipx or pip and runs the matching upgrade flow automatically. Before upgrading, it stops any running local daemon to avoid mixing old and new code.

Supported install sources

forgexa upgrade is intended for standard PyPI / pipx installs. Editable installs, local path installs, and VCS installs should be upgraded manually using the original install source.

Stay in sync

The CLI version should match the platform version. If you see unexpected errors or missing commands, upgrading is the first thing to try.

Configuration

The server URL is resolved in the following priority order:

1. --server-url flag (per-command override)
2. FORGEXA_SERVER_URL environment variable
3. ~/.forgexa/config (saved by forgexa login --server <url> or forgexa config set)
4. Build default: https://api.forgexa.net

Environment Variable	Default	Description
FORGEXA_SERVER_URL	https://api.forgexa.net	Server base URL
FORGEXA_TOKEN	—	Bearer token (overrides ~/.forgexa/config)

# View current configuration (server URL, auth status, config file path)
forgexa config show

# Permanently set the server URL
forgexa config set server-url https://your-server.com

Global Flags

Flag	Description
--server-url <URL>	Override server URL for this command only
--format table|json|quiet	Output format (default: table)

Authentication

# Login (saves token and server URL to ~/.forgexa/config)
forgexa login

# Login with server URL and credentials in one step
forgexa login --server https://your-server.com --email user@example.com

# Logout (removes saved token)
forgexa logout

Workspaces

# List your workspaces
forgexa workspace list

# Create a workspace
forgexa workspace create "My Team"

Projects

# List projects in a workspace
forgexa project list --workspace <workspace-id>

# Show project status summary
forgexa project status --project <project-id>

# Create a project
forgexa project create "My App" --workspace <workspace-id>

# Create a project with a tech stack hint
forgexa project create "My App" --workspace <workspace-id> --stack "Python FastAPI"

Requirements

# List requirements
forgexa requirement list --project <project-id>

# Create a requirement
forgexa requirement create "User registration API" --project <project-id>

# Create a requirement with a description
forgexa requirement create "User registration API" --project <project-id> --description "Support OAuth2"

# Analyze a requirement (AI-driven)
forgexa requirement analyze --id <requirement-id>

Board & Work Items

# Show kanban board
forgexa board --project <project-id>

Executions

# List executions
forgexa run list --project <project-id>

# Start an execution
forgexa run start <execution-id>

Gates

# List pending gate reviews
forgexa gates pending

# Approve a gate
forgexa gates approve --gate <gate-id>

# Approve with a comment
forgexa gates approve --gate <gate-id> --comment "LGTM"

# Reject a gate with a reason
forgexa gates reject --gate <gate-id> --reason "Missing error handling"

Workflow

# Show current workflow policy
forgexa workflow show --project <project-id>

# Reload workflow from WORKFLOW.md
forgexa workflow reload --project <project-id>

Budget

# Show workspace budget
forgexa budget --workspace <workspace-id>

# Show project budget
forgexa budget --project <project-id>

Daemon & Runtimes

The local daemon (forgexa daemon) discovers installed AI agent CLIs (Claude Code, OpenAI Codex, Gemini CLI, Kimi Code, GitHub Copilot, etc.), registers them with the Forgexa server, and polls for tasks to execute.

Shortcut commands

All forgexa daemon <cmd> commands have a top-level alias. You can drop the daemon prefix:

Full form	Shortcut
forgexa daemon start -d	forgexa start -d
forgexa daemon stop	forgexa stop
forgexa daemon restart	forgexa restart
forgexa daemon status	forgexa status
forgexa daemon logs -f	forgexa logs -f
forgexa daemon agents	forgexa agents

Both forms are fully equivalent.

Start

# Start in background (recommended)
# Guards against double-start, waits for server registration,
# then displays the discovered agents in a formatted table.
forgexa daemon start -d

# Start with a specific server URL
forgexa daemon start -d --server-url https://your-server.com

# Start in foreground (blocks terminal; Ctrl+C to stop)
# Agent CLIs are scanned and displayed before the daemon loop begins.
# Raw log lines are suppressed — use `forgexa daemon logs -f` to stream them.
forgexa daemon start

After a background start the CLI waits up to ~12 seconds for the daemon to register, then prints the discovered agents:

Daemon starting in background
  PID    : 12345
  Server : https://app.forgexa.net
  Logs   : /Users/you/.forgexa/daemon/daemon.log

  Runtime ready  (id: abc12345  status: online)
  3 agent(s) discovered:
    ✓  claude  Claude Code 1.5.8  [L3]
    ✓  codex   @openai/codex 0.3  [L3]
    ✓  kimi    Kimi Code 1.0.2    [L2]

  Stop  : forgexa daemon stop
  Logs  : forgexa daemon logs -f

Restart

# Stop the running daemon and start a fresh one in the background
forgexa daemon restart

# Restart connecting to a different server
forgexa daemon restart --server-url https://your-server.com

Stop

forgexa daemon stop

Status

# Compact table — shows local PID, registered runtimes, and agents per runtime
forgexa daemon status

# Expanded view with per-agent version and compatibility level
forgexa daemon status --verbose

# Show all runtimes across all users (platform admin only)
forgexa daemon status --all

Example compact output:

Local daemon : running  (PID 12345)
Log file     : /Users/you/.forgexa/daemon/daemon.log

ID        Daemon    Device    Status   Agents               Active/Max  Heartbeat
--------  --------  --------  -------  -------------------  ----------  -------------------
abc12345  my-mac    MacBook   online   claude, codex, kimi  0/5         2026-06-26 10:30:00

Logs

# Show last 50 lines and exit
forgexa daemon logs

# Show last 100 lines and exit
forgexa daemon logs -n 100

# Stream new lines live (like tail -f)
forgexa daemon logs -f

# Show last 200 lines then follow
forgexa daemon logs -n 200 -f

Logs are written to ~/.forgexa/daemon/daemon.log (50 MB rotating, 5 backups kept).

Agents

Dedicated view of every AI agent across all registered daemon runtimes.

# List all AI agents with version and compatibility level
forgexa daemon agents

# Include runtimes from all users (admin only)
forgexa daemon agents --all

Example output:

Runtime   Daemon    Device    Status   Agent   Version              Compat
--------  --------  --------  -------  ------  -------------------  ------
abc12345  my-mac    MacBook   online   claude  Claude Code 1.5.8    L3
                                        codex   @openai/codex 0.3    L3
                                        kimi    Kimi Code 1.0.2      L2

Compatibility levels: L3 — full autonomous execution (recommended), L2 — good quality, L1 — basic.

Runtimes

# List all registered runtimes for your account
forgexa runtimes list

# Include runtimes from all users (admin only)
forgexa runtimes list --all