Metadata-Version: 2.4
Name: forgexa-cli
Version: 1.8.6
Summary: Forgexa CLI — command-line client and AI agent runtime for the Forgexa platform
Author-email: Jason Sun <dev.winds@gmail.com>
License: MIT
Project-URL: Homepage, https://forgexa.net
Project-URL: Documentation, https://docs.forgexa.net
Project-URL: Repository, https://github.com/forgexa/forgexa
Project-URL: Issues, https://github.com/forgexa/forgexa/issues
Keywords: forgexa,ai,software-factory,cli,devops,agent
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Provides-Extra: daemon
Requires-Dist: httpx>=0.24; extra == "daemon"

# Forgexa CLI

Command-line client and agent runtime for the [Forgexa](https://forgexa.net) platform.

Lightweight — communicates with the Forgexa server via REST API using only Python stdlib.
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

```bash
# From PyPI (recommended)
pip install forgexa-cli

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

# Verify installation
forgexa version
```

### Development Installation

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

## Quick Start

```bash
# 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 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

```bash
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

```bash
# 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

```bash
# Check daemon status (from server)
forgexa daemon status

# Stop background daemon
forgexa daemon stop
```

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

```bash
pip install build twine
```

### Build & Publish

```bash
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

```bash
# 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`:

```bash
# 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

```bash
cd cli
pip install -e .
```

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

### Testing Against Local Server

```bash
# 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

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

### Debugging the Daemon

```bash
# 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
