forgexa-cli 1.16.0

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 runtimes list	List your runtimes
forgexa version	Show CLI version
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

For safety, forgexa upgrade stops any running local daemon before upgrading. Restart it afterward with forgexa daemon start.

forgexa upgrade is intended for standard PyPI / pipx installs. Editable installs, local path installs, and VCS installs are rejected with a manual upgrade hint.

Configuration

Variable	Default	Description
FORGEXA_SERVER_URL	http://localhost:8000	`Server base URL
FORGEXA_TOKEN	—	Bearer token (overrides ~/.forgexa/token)

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

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