Vapora/docs/setup/cli-commands.md

CLI Commands Reference

Command-line interface for VAPORA workflow management.

Installation

Build from Source

cd crates/vapora-cli
cargo build --release

Binary location: target/release/vapora

Add to PATH

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

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

Verify Installation

vapora --version

Configuration

Environment Variables

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

Command-Line Flags

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

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:

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

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

Output:

✓ Workflow started: feature_development (ID: 3f9a2b1c)

list

List all active workflows.

Usage:

vapora workflow list

Output:

╔════════════╦════════════════════╦════════════════╦══════════╦═════════════════════╗
║ 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:

vapora workflow status <WORKFLOW_ID>

Arguments:

• <WORKFLOW_ID> - Workflow identifier (required)

Example:

vapora workflow status 3f9a2b1c

Output:

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:

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

Arguments:

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

Example:

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

Output:

✓ 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:

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

Arguments:

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

Example:

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

Output:

✓ Workflow 3f9a2b1c cancelled

Notes:

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

templates

List available workflow templates.

Usage:

vapora workflow templates

Output:

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:

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

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:

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:

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

# List all workflows
vapora workflow list

# Get specific workflow details
vapora workflow status <id>

Approve Multi-Stage Workflow

# 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

# Find workflow
vapora workflow list

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

Template Discovery

# List available templates
vapora workflow templates

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

Error Handling

Workflow Not Found

✗ Workflow not found: abc123

Cause: Invalid workflow ID

Solution: Verify ID with vapora workflow list

API Connection Failed

✗ API request failed: HTTP 500

Cause: Backend not running or network issue

Solution:

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

# Verify API URL
echo $VAPORA_API_URL

# Check backend logs
docker logs vapora-backend

Invalid Template

✗ API request failed: HTTP 404

Cause: Template name doesn't exist

Solution:

# List available templates
vapora workflow templates

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

Approval Not Allowed

✗ API request failed: Stage not waiting for approval

Cause: Workflow not in waiting_approval status

Solution:

# Check workflow status
vapora workflow status <id>

# Wait for status to change to "waiting_approval"

Advanced Usage

Custom API URL

# 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

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

# 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

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

# Verify installation
which vapora

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

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

Permission Denied

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

# Or rebuild
cargo build --release

SSL Certificate Error

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

Related Documentation

• Workflow Orchestrator - Architecture and API
• Multi-Agent Workflows - Design overview
• ADR-0028: Workflow Orchestrator - Decision rationale
• Deployment Guide - Production deployment