Metadata-Version: 2.4
Name: forgexa-cli
Version: 1.0.3
Summary: Forgexa CLI — command-line client for managing workspaces, projects, requirements, and agent runtimes
Author-email: Shinetech <dev@shinetechsoftware.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: Topic :: Software Development :: Build Tools
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# Forgexa CLI

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

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

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

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

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