forgexa-cli 1.0.3

Forgexa CLI — command-line client for managing workspaces, projects, requirements, and agent runtimes

Forgexa CLI

Command-line client for the [Forgexa platform.

Lightweight, zero-dependency — communicates with the Forgexa server via REST API using only Python stdlib.

Installation

# From PyPI (recommended)
pip install forgexa-cli

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

# 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 status	Show daemon statuses
forgexa daemon stop	Stop local daemon
forgexa runtimes list	List runtimes
forgexa version	Show CLI version

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 forgexa CLI handles remote daemon queries. To start a daemon locally, use the forgexa-daemon command from the backend package:

pip install ./backend
forgexa-daemon  # starts the runtime daemon

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