Vapora/docs/setup/cli-commands.md

# CLI Commands Reference

Command-line interface for VAPORA workflow management.

## Installation

### Build from Source

```bash
cd crates/vapora-cli
cargo build --release
```

Binary location: `target/release/vapora`

### Add to PATH

```bash
# Copy to local bin
cp target/release/vapora ~/.local/bin/

# Or symlink
ln -s $(pwd)/target/release/vapora ~/.local/bin/vapora
```

### Verify Installation

```bash
vapora --version
```

## Configuration

### Environment Variables

```bash
# Backend API URL (default: http://localhost:8001)
export VAPORA_API_URL="http://localhost:8001"
```

### Command-Line Flags

```bash
# Override API URL per command
vapora --api-url http://production:8001 workflow list
```

## Commands

### vapora workflow

Workflow orchestration commands.

#### start

Start a new workflow from template.

**Usage**:

```bash
vapora workflow start --template <TEMPLATE> [--context <FILE>] [--kogral <BOOL>]
```

**Arguments**:

- `-t, --template <TEMPLATE>` - Workflow template name (required)
- `-c, --context <FILE>` - Initial context JSON file (optional)
- `--kogral <BOOL>` - Enrich with Kogral knowledge (default: true)

**Examples**:

```bash
# Start feature development workflow
vapora workflow start --template feature_development

# Start with context file
vapora workflow start \
  --template feature_development \
  --context context.json

# Start without Kogral enrichment
vapora workflow start \
  --template bugfix \
  --kogral false
```

**Context File Format** (`context.json`):

```json
{
  "task": "Implement user authentication",
  "requirements": ["OAuth2", "JWT", "MFA"],
  "priority": "high"
}
```

**Output**:

```text
✓ Workflow started: feature_development (ID: 3f9a2b1c)
```

#### list

List all active workflows.

**Usage**:

```bash
vapora workflow list
```

**Output**:

```text
╔════════════╦════════════════════╦════════════════╦══════════╦═════════════════════╗
║ ID         ║ Template           ║ Status         ║ Progress ║ Created             ║
╠════════════╬════════════════════╬════════════════╬══════════╬═════════════════════╣
║ 3f9a2b1c   ║ feature_development║ running        ║ 2/5      ║ 2026-01-24 01:23:45 ║
║ 7d8e3c4a   ║ bugfix             ║ completed      ║ 4/4      ║ 2026-01-24 00:15:32 ║
╚════════════╩════════════════════╩════════════════╩══════════╩═════════════════════╝
```

**Status Colors**:

- **Green**: `running` - Workflow executing
- **Yellow**: `waiting_approval` - Stage requires approval
- **Blue**: `completed` - Workflow finished successfully
- **Red**: `failed` - Workflow encountered error

#### status

Get detailed workflow status.

**Usage**:

```bash
vapora workflow status <WORKFLOW_ID>
```

**Arguments**:

- `<WORKFLOW_ID>` - Workflow identifier (required)

**Example**:

```bash
vapora workflow status 3f9a2b1c
```

**Output**:

```text
Workflow Details
────────────────────────────────────────────────────────────
ID:             3f9a2b1c-5e7f-4a9b-8c2d-1e3f5a7b9c1d
Template:       feature_development
Status:         running
Progress:       2/5
Created:        2026-01-24T01:23:45.123Z
Updated:        2026-01-24T01:45:12.456Z
────────────────────────────────────────────────────────────
```

#### approve

Approve a stage waiting for approval.

**Usage**:

```bash
vapora workflow approve <WORKFLOW_ID> --approver <NAME>
```

**Arguments**:

- `<WORKFLOW_ID>` - Workflow identifier (required)
- `-a, --approver <NAME>` - Approver name (required)

**Example**:

```bash
vapora workflow approve 3f9a2b1c --approver "Jane Doe"
```

**Output**:

```text
✓ Workflow 3f9a2b1c stage approved
```

**Notes**:

- Workflow must be in `waiting_approval` status
- Approver name logged in audit trail
- Workflow resumes execution immediately

#### cancel

Cancel a running workflow.

**Usage**:

```bash
vapora workflow cancel <WORKFLOW_ID> --reason <REASON>
```

**Arguments**:

- `<WORKFLOW_ID>` - Workflow identifier (required)
- `-r, --reason <REASON>` - Cancellation reason (required)

**Example**:

```bash
vapora workflow cancel 3f9a2b1c --reason "Requirements changed"
```

**Output**:

```text
✓ Workflow 3f9a2b1c cancelled
```

**Notes**:

- Cancels workflow immediately
- In-flight tasks may complete
- Reason logged in audit trail

#### templates

List available workflow templates.

**Usage**:

```bash
vapora workflow templates
```

**Output**:

```text
Available Workflow Templates
────────────────────────────────────────────────────────────
 1. feature_development
 2. bugfix
 3. documentation_update
 4. security_audit
────────────────────────────────────────────────────────────

Use vapora workflow start --template <name> to start a workflow
```

## Workflow Templates

### feature_development

5-stage workflow for implementing new features.

**Stages**:

1. **architecture_design** (architect)
2. **implementation** (2x developer, parallel)
3. **testing** (tester)
4. **code_review** (reviewer, approval required)
5. **deployment** (devops, approval required)

**Example**:

```bash
# Create context
cat > feature.json <<EOF
{
  "task": "Add user authentication",
  "requirements": ["OAuth2", "JWT", "MFA"],
  "technologies": ["Rust", "axum", "SurrealDB"]
}
EOF

# Start workflow
vapora workflow start \
  --template feature_development \
  --context feature.json

# Monitor progress
vapora workflow list

# Approve code review stage (when ready)
vapora workflow approve <id> --approver "Tech Lead"

# Approve deployment stage (when ready)
vapora workflow approve <id> --approver "Release Manager"
```

### bugfix

4-stage workflow for fixing bugs.

**Stages**:

1. **investigation** (developer)
2. **fix_implementation** (developer)
3. **testing** (tester)
4. **deployment** (devops)

**Example**:

```bash
cat > bugfix.json <<EOF
{
  "bug": "Authentication fails on mobile devices",
  "severity": "high",
  "affected_users": 500
}
EOF

vapora workflow start --template bugfix --context bugfix.json
```

### documentation_update

3-stage workflow for documentation changes.

**Stages**:

1. **content_creation** (technical_writer)
2. **review** (reviewer, approval required)
3. **publish** (devops)

**Example**:

```bash
cat > docs.json <<EOF
{
  "topic": "API Authentication Guide",
  "sections": ["Setup", "OAuth2 Flow", "JWT Tokens"],
  "format": "markdown"
}
EOF

vapora workflow start --template documentation_update --context docs.json
```

### security_audit

4-stage workflow for security reviews.

**Stages**:

1. **code_analysis** (security_engineer)
2. **penetration_testing** (security_engineer)
3. **remediation** (developer)
4. **verification** (security_engineer, approval required)

**Example**:

```bash
cat > security.json <<EOF
{
  "scope": "Authentication module",
  "compliance": ["OWASP Top 10", "SOC 2"],
  "priority": "critical"
}
EOF

vapora workflow start --template security_audit --context security.json
```

## Common Workflows

### Check Workflow Status

```bash
# List all workflows
vapora workflow list

# Get specific workflow details
vapora workflow status <id>
```

### Approve Multi-Stage Workflow

```bash
# Start workflow
ID=$(vapora workflow start --template feature_development \
  --context context.json | grep -oE '[0-9a-f-]{36}')

# Monitor until waiting for approval
watch -n 5 vapora workflow status $ID

# Approve when ready
vapora workflow approve $ID --approver "$(whoami)"
```

### Cancel Stuck Workflow

```bash
# Find workflow
vapora workflow list

# Cancel with reason
vapora workflow cancel <id> --reason "Timeout exceeded"
```

### Template Discovery

```bash
# List available templates
vapora workflow templates

# Start specific template
vapora workflow start --template <name>
```

## Error Handling

### Workflow Not Found

```text
✗ Workflow not found: abc123
```

**Cause**: Invalid workflow ID

**Solution**: Verify ID with `vapora workflow list`

### API Connection Failed

```text
✗ API request failed: HTTP 500
```

**Cause**: Backend not running or network issue

**Solution**:

```bash
# Check backend status
curl http://localhost:8001/health

# Verify API URL
echo $VAPORA_API_URL

# Check backend logs
docker logs vapora-backend
```

### Invalid Template

```text
✗ API request failed: HTTP 404
```

**Cause**: Template name doesn't exist

**Solution**:

```bash
# List available templates
vapora workflow templates

# Use exact template name
vapora workflow start --template feature_development
```

### Approval Not Allowed

```text
✗ API request failed: Stage not waiting for approval
```

**Cause**: Workflow not in `waiting_approval` status

**Solution**:

```bash
# Check workflow status
vapora workflow status <id>

# Wait for status to change to "waiting_approval"
```

## Advanced Usage

### Custom API URL

```bash
# Production environment
vapora --api-url https://vapora.example.com workflow list

# Local development with custom port
vapora --api-url http://localhost:9000 workflow start \
  --template feature_development
```

### Scripting Workflows

```bash
#!/bin/bash
set -e

# Start workflow and capture ID
WORKFLOW_ID=$(vapora workflow start \
  --template feature_development \
  --context feature.json \
  | grep -oE '[0-9a-f-]{36}')

echo "Started workflow: $WORKFLOW_ID"

# Poll until completed or failed
while true; do
  STATUS=$(vapora workflow status $WORKFLOW_ID | grep "Status:" | awk '{print $2}')

  if [[ "$STATUS" == "completed" ]]; then
    echo "Workflow completed successfully"
    exit 0
  elif [[ "$STATUS" == "failed"* ]]; then
    echo "Workflow failed: $STATUS"
    exit 1
  elif [[ "$STATUS" == "waiting_approval"* ]]; then
    echo "Workflow waiting for approval"
    vapora workflow approve $WORKFLOW_ID --approver "CI/CD Bot"
  fi

  sleep 10
done
```

### JSON Context Generation

```bash
# Generate context from git commit
cat > context.json <<EOF
{
  "task": "Fix bug from commit",
  "commit": "$(git log -1 --format=%H)",
  "message": "$(git log -1 --format=%s)",
  "author": "$(git log -1 --format=%an)",
  "files": $(git show --name-only --format= | jq -R . | jq -s .)
}
EOF

vapora workflow start --template bugfix --context context.json
```

### CI/CD Integration

```yaml
# .github/workflows/vapora-deploy.yml
name: VAPORA Deployment
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Install VAPORA CLI
        run: |
          curl -L https://github.com/vapora/vapora/releases/latest/download/vapora-cli -o vapora
          chmod +x vapora
          sudo mv vapora /usr/local/bin/

      - name: Start deployment workflow
        env:
          VAPORA_API_URL: ${{ secrets.VAPORA_API_URL }}
        run: |
          vapora workflow start \
            --template feature_development \
            --context .github/workflows/context.json
```

## Troubleshooting

### Command Not Found

```bash
# Verify installation
which vapora

# Add to PATH
export PATH="$HOME/.local/bin:$PATH"

# Or use full path
/path/to/vapora workflow list
```

### Permission Denied

```bash
# Make executable
chmod +x /path/to/vapora

# Or rebuild
cargo build --release
```

### SSL Certificate Error

```bash
# For self-signed certificates (development only)
export VAPORA_SKIP_TLS_VERIFY=true
```

## Related Documentation

- [Workflow Orchestrator](../features/workflow-orchestrator.md) - Architecture and API
- [Multi-Agent Workflows](../architecture/multi-agent-workflows.md) - Design overview
- [ADR-0028: Workflow Orchestrator](../adrs/0028-workflow-orchestrator.md) - Decision rationale
- [Deployment Guide](deployment.md) - Production deployment