forgexa-cli 1.21.8

Forgexa CLI — command-line client and AI agent runtime for the Forgexa platform

Forgexa CLI

Command-line client and agent runtime for the Forgexa platform.

Communicates with the Forgexa server via REST API. Includes a built-in daemon that discovers local AI agents (Claude Code, Codex, Gemini CLI, OpenCode, Kimi Code, etc.) and executes tasks on behalf of the server.

Installation

# From PyPI (recommended)
pip install forgexa-cli

# Or with pipx (isolated environment)
pipx install forgexa-cli

# Upgrade later
forgexa upgrade
forgexa upgrade --target-version 1.12.3

# Verify installation
forgexa version

Development Installation

# Install from source (editable mode)
git clone https://github.com/forgexa/forgexa.git
cd ai-software-factory/cli
pip install -e .

Quick Start

# Configure server (default: http://localhost:8000)
export FORGEXA_SERVER_URL=https://your-server.example.com

# Login (saves token to ~/.forgexa/token)
forgexa login

# List workspaces
forgexa workspace list

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

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

Commands

Command	Description
forgexa login	Login and save access token
forgexa logout	Remove saved token
forgexa workspace list	List workspaces
forgexa workspace create <name>	Create a workspace
forgexa project list --workspace <id>	List projects
forgexa project create <name> --workspace <id>	Create a project
forgexa requirement list --project <id>	List requirements
forgexa requirement create <title> --project <id>	Create a requirement
forgexa requirement analyze --id <id>	Analyze a requirement
forgexa board --project <id>	Show kanban board
forgexa run list --project <id>	List executions
forgexa run start <execution-id>	Start an execution
forgexa gates pending	List pending gates
forgexa gates approve --gate <id>	Approve a gate
forgexa gates reject --gate <id>	Reject a gate
forgexa workflow show --project <id>	Show workflow policy
forgexa workflow reload --project <id>	Reload workflow
forgexa budget --workspace <id>	Budget overview
forgexa daemon start	Start local daemon (discover agents, run tasks)
forgexa daemon start -d	Start daemon in background
forgexa daemon status	Show your daemon statuses
forgexa daemon stop	Stop local daemon
forgexa check	Verify locally-installed agent CLIs are genuinely usable (runs a real task per agent)
forgexa check --quick	Same, but discovery only — no live task, no API calls
forgexa check --agent <name>	Check a single agent (e.g. claude, codex, kimi)
forgexa runtimes list	List your runtimes
forgexa version	Show CLI version
forgexa version --status	Show auto-upgrade status (mode, active/last success/last failure)
forgexa upgrade	Upgrade to the latest CLI release
forgexa upgrade --target-version <version>	Upgrade or roll forward to a specific release

Self Upgrade

# Upgrade to the latest published release
forgexa upgrade

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

The command detects how forgexa-cli was installed:

• pipx install: uses pipx upgrade forgexa-cli, or pipx install --force forgexa-cli==<version> for a pinned version
• pip install: uses python -m pip install --upgrade forgexa-cli
• non-editable local path install (pip install /path/to/cli): follows the same pip upgrade path and switches to the published PyPI release

For safety, forgexa upgrade stops any running local daemon before upgrading. 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.

forgexa upgrade supports standard PyPI / pipx installs and non-editable local path installs. Editable installs, VCS installs, and other direct URL installs are rejected with a manual upgrade hint.

One-Shot Upgrade Script (recommended for production runtimes)

forgexa upgrade alone only auto-restarts the daemon if it was already running in background mode right before the upgrade started — if it had already stopped for any other reason (crash, manual stop, first-time setup), you're left to restart it yourself. cli/scripts/upgrade.sh (macOS/Linux) and cli/scripts/upgrade.ps1 (Windows) wrap the full, correct sequence explicitly so the daemon is deterministically stopped, upgraded, and started again in the background every time, regardless of its state going in:

# macOS / Linux
./cli/scripts/upgrade.sh
./cli/scripts/upgrade.sh --target-version 1.21.7
./cli/scripts/upgrade.sh --server-url https://api.forgexa.net --login

# Windows
.\cli\scripts\upgrade.ps1
.\cli\scripts\upgrade.ps1 -TargetVersion 1.21.7
.\cli\scripts\upgrade.ps1 -ServerUrl https://api.forgexa.net -Login

Steps: daemon stop (no-op if not running) → upgrade → daemon start -d → optional login → daemon status. Login is skipped by default (the previously saved session is reused) unless you pass --email/--password (-Email/-Password), set FORGEXA_LOGIN_EMAIL/FORGEXA_LOGIN_PASSWORD, or pass --login/-Login to be prompted interactively. Run with --help/Get-Help .\upgrade.ps1 for all options.

Automatic Background Upgrade

By default (auto_upgrade=silent), forgexa checks for updates in the background (once every 24h) and silently installs new releases — no need to run forgexa upgrade yourself, the same way GitHub Copilot CLI / Claude Code / Kimi Code work (see docs/designs/cli-auto-upgrade-design.md for the full design). forgexa upgrade remains fully available at any time for an immediate manual upgrade or to pin a specific --target-version — the two are independent and coexist.

# Back to notify-only: check and print a footer notice, but never install automatically
forgexa config set auto-upgrade notify

# Disable update checks entirely
forgexa config set auto-upgrade off

# Re-enable silent background installs (the default)
forgexa config set auto-upgrade silent

Mode	Check	Silent background install	Footer notice
silent (default)	✅	✅	✅ (one-time "updated to vX" notice next run)
notify	✅	❌	✅
off	❌	❌	❌

A silent install only ever runs for a safe, already-detected install source (pip/pipx — the same sources forgexa upgrade supports), never while a local daemon is running (it's skipped and retried on a later invocation instead), never in CI or a non-interactive/--format json session, and gives up automatically after 2 consecutive failures for the same target version. Check forgexa version --status to see the current mode and the last install attempt's outcome, or ~/.forgexa/upgrade.log for the raw install output.

FORGEXA_AUTO_UPGRADE=<silent|notify|off> overrides the config file for the current shell session; the legacy FORGEXA_NO_UPDATE_CHECK=1 remains a supported alias for off.

Configuration

Variable	Default	Description
FORGEXA_SERVER_URL	http://localhost:8000	`Server base URL
FORGEXA_TOKEN	—	Bearer token (overrides ~/.forgexa/token)
FORGEXA_AUTO_UPGRADE	—	Override auto_upgrade (silent|notify|off) for this session
FORGEXA_NO_UPDATE_CHECK	—	Legacy alias for FORGEXA_AUTO_UPGRADE=off

Output Format

forgexa workspace list                  # Table (default)
forgexa workspace list --format json    # JSON
forgexa workspace list --format quiet   # IDs only

Daemon Management

The daemon discovers locally installed AI agents and registers them with the Forgexa server. It then polls for tasks and executes them using your local agents.

Start Daemon

# Foreground (default — see logs, Ctrl+C to stop)
forgexa daemon start

# Background (detached)
forgexa daemon start -d

# Connect to a specific server
forgexa daemon start --server-url https://your-server.example.com

# Or via the standalone entry point
forgexa-daemon

Other Daemon Commands

# Check your daemon status (from server)
forgexa daemon status

# Platform admin: list all runtimes
forgexa daemon status --all

# Stop background daemon
forgexa daemon stop

# List your runtimes
forgexa runtimes list

# Platform admin: list all runtimes
forgexa runtimes list --all

Agent Health Check

Before starting the daemon (or when tasks keep failing on this machine), verify that every installed agent CLI is genuinely usable — not just present on PATH. forgexa check reuses the exact discovery and execution code the daemon uses in production, so a PASS means the agent really works (auth, quota, and sandbox problems only ever surface on a real invocation).

# Check runtime prerequisites, discover installed agents, then run one real,
# minimal task through each to confirm it works
forgexa check

# Fast pass: discovery only, no live task, no API calls
forgexa check --quick

# Check a single agent
forgexa check --agent claude

# Check runtime prerequisites and only the selected agent without a live task
forgexa check --quick --agent claude

Example output:

Agent Availability Report
----------------------------------------------------------------------
  ✓  claude     v2.1.14 (Claude Code)
  ✗  codex      not installed
       'codex' not found on PATH, or found but 'codex --version' failed / did not
       report a version. Install (or reinstall) the agent CLI and make sure it is
       on PATH, then re-run 'forgexa check'.
  ✓  kimi       v0.27.0
----------------------------------------------------------------------
2/3 agent(s) available for real platform tasks.

Supported AI Agents

The daemon automatically discovers these agents if installed on your system:

Agent	Command
Claude Code	claude
OpenAI Codex	codex
Gemini CLI	gemini
OpenCode	opencode
Kimi Code	kimi

Environment Variables (Daemon)

Variable	Default	Description
DAEMON_SERVER_URL	http://localhost:8000	Server to connect to
DAEMON_API_TOKEN	—	Auth token (auto-read from ~/.forgexa/token)
DAEMON_MAX_CONCURRENT	5	Max parallel tasks
DAEMON_POLL_INTERVAL	3	Poll interval (seconds)

Publishing to PyPI

Prerequisites

pip install build twine

Build & Publish

cd cli/

# Build only (creates dist/)
./scripts/publish.sh build

# Publish to TestPyPI (for testing)
./scripts/publish.sh test

# Publish to PyPI (production)
./scripts/publish.sh

Version Bumping

# Bump version (updates pyproject.toml + __init__.py)
./scripts/bump-version.sh 1.1.0

# Then commit, tag, and publish
git add -A && git commit -m "release(cli): v1.1.0"
git tag cli-v1.1.0
./scripts/publish.sh

PyPI Authentication

Configure via environment variables or ~/.pypirc:

# Using API token (recommended)
export TWINE_USERNAME=__token__
export TWINE_PASSWORD=pypi-AgEIcH...

# Or create ~/.pypirc
cat > ~/.pypirc << 'EOF'
[pypi]
username = __token__
password = pypi-AgEIcH...

[testpypi]
repository = https://test.pypi.org/legacy/
username = __token__
password = pypi-AgEIcH...
EOF
chmod 600 ~/.pypirc

Local Development & Debugging

Editable Install

cd cli
pip install -e .

This installs the forgexa command pointing to your local source. Changes take effect immediately.

Testing Against Local Server

# Point CLI to local backend
export FORGEXA_SERVER_URL=http://localhost:8000

# Login
forgexa login

# Test commands
forgexa workspace list
forgexa daemon start

Testing Against Remote/LAN Server

export FORGEXA_SERVER_URL=http://192.168.0.100:8000
forgexa login
forgexa daemon start

Debugging the Daemon

# Run in foreground to see all logs
forgexa daemon start

# Check which agents are discovered
forgexa runtimes list

# Verbose logging (if supported)
DAEMON_LOG_LEVEL=DEBUG forgexa daemon start

Project Structure

cli/
├── forgexa_cli/
│   ├── __init__.py     # Version constant
│   ├── main.py         # CLI entry point (argparse)
│   ├── daemon.py       # Daemon implementation
│   └── py.typed        # PEP 561 marker
├── scripts/
│   ├── bump-version.sh # Version management
│   ├── publish.sh      # PyPI publishing
│   └── sync-daemon.sh  # Sync daemon code from backend
├── pyproject.toml      # Package metadata
└── README.md           # This file

Design Principles

• Zero external dependencies — uses only Python stdlib (urllib, json, subprocess)
• Lightweight — installs in seconds, no compilation needed
• Cross-platform — works on Linux, macOS, Windows
• Standalone daemon — discovers local AI agents without server-side configuration