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

bash

# 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

Download the Windows installer from python.org/downloads.
Run the installer. On the first screen, check "Add Python to PATH" before clicking Install.
Verify in a new terminal window:
powershell
```
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:

bash

# macOS / Linux
python3 -m pip --version

# Windows
python -m pip --version

If pip is missing, install it:

bash

python3 -m ensurepip --upgrade

Installation

bash

# 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

bash

# 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

bash

# 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. Non-editable local path installs created with pip install /path/to/cli follow the same pip upgrade path and move to the published PyPI release. Before upgrading, it stops any running local daemon to avoid mixing old and new code. If the daemon was previously started in background mode, the CLI starts it again automatically after a successful upgrade; otherwise it prints a manual restart hint.

Supported install sources

forgexa upgrade supports standard PyPI / pipx installs and non-editable local path installs. Editable installs, VCS installs, and other direct URL 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.

Uninstall

Use the package manager that was used to install the CLI:

bash

# Installed with pip
pip uninstall forgexa-cli

# Installed with pipx
pipx uninstall forgexa-cli

Configuration

The server URL is resolved in the following priority order:

--server-url flag (per-command override)
FORGEXA_SERVER_URL environment variable
~/.forgexa/config (saved by forgexa login --server <url> or forgexa config set)
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`)

bash

# 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

bash

# 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

bash

# List your workspaces
forgexa workspace list

# Create a workspace
forgexa workspace create "My Team"

Projects

bash

# 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

bash

# 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

bash

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

Executions

bash

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

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

Gates

bash

# 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

bash

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

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

Budget

bash

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

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

Daemon & Runtimes

The local daemon (forgexa daemon) discovers thirteen installed Agent integrations, registers their inventory, and polls for tasks. Six are standard automatic candidates; MiMo Code, Qwen Code, CodeBuddy, Qoder CLI, TraeCode CLI, ZCode, and DeepSeek Harness require explicit selection. The other local CLIs retain user-managed authentication/settings; Harness uses the managed-profile exception below. TraeCode CLI/ZCode retain their live gates.

DeepSeek Harness (deepseek, binary dsh) is the thirteenth integration and seventh explicit local agent. It is a developer preview for personal Runtimes/Desktop with a managed home and read-only external credentials, not a copied personal profile. Native Windows/shared pools/automatic routing remain blocked. See Harness installation.

bash

forgexa agent approve-live deepseek
forgexa check --agent deepseek --quick
forgexa check --agent deepseek

Approve only after exact-build start/resume/cancel/isolation acceptance. The command records an attestation, not a live test. --quick does not call the model; normal check can incur API costs. Node/platform/runtime-policy changes invalidate build approval, and changed runtime composition rejects native resume.

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

bash

# 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

bash

# 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

bash

forgexa daemon stop

Status

bash

# 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

bash

# 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.

bash

# 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

bash

# List all registered runtimes for your account
forgexa runtimes list

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

CLI Reference ​

Prerequisites ​

Check Your Python Version ​

Install Python ​

Check pip ​

Installation ​

Upgrade ​

Method 1 — Upgrade with pip or pipx ​

Method 2 — Upgrade from the CLI itself ​

Uninstall ​

Configuration ​

Global Flags ​

Authentication ​

Workspaces ​

Projects ​

Requirements ​

Board & Work Items ​

Executions ​

Gates ​

Workflow ​

Budget ​

Daemon & Runtimes ​

Start ​

Restart ​

Stop ​

Status ​

Logs ​

Agents ​

Runtimes ​

CLI Reference

Prerequisites

Check Your Python Version

Install Python

Check pip

Installation

Upgrade

Method 1 — Upgrade with pip or pipx

Method 2 — Upgrade from the CLI itself

Uninstall

Configuration

Global Flags

Authentication

Workspaces

Projects

Requirements

Board & Work Items

Executions

Gates

Workflow

Budget

Daemon & Runtimes

Start

Restart

Stop

Status

Logs

Agents

Runtimes