@devteam/cli

Command-line interface for the DevTeam Orchestrator - manage AI agent swarms, tasks, workers, and templates from your terminal.

Installation

cd /root/devteam-cli
npm install
npm run build
npm link  # Makes 'devteam' available globally

For development:

npm run dev -- <command>    # Run without building (uses tsx)

Quick Start

# 1. Initialize a project
devteam init

# 2. Authenticate
devteam login

# 3. Check cluster status
devteam status

# 4. Run your first task
devteam run "Analyze this codebase and suggest improvements"

Commands

devteam init

Initialize a new project in the current directory. Creates a devteam.config.json file with project-specific settings.

devteam init          # Interactive setup
devteam init -y       # Accept all defaults

devteam login

Authenticate with the DevTeam API. Stores your API key securely in the system config directory.

devteam login                    # Interactive prompt
devteam login -k <api-key>      # Provide key directly
devteam login -u https://...    # Set custom API URL
devteam logout                   # Remove stored credentials

devteam run <prompt>

Submit a task to the agent swarm and optionally stream live output.

devteam run "Review this PR for security issues"
devteam run "Build a REST API for user management" -q gpu-queue -p high
devteam run "Run tests" -w surface-book --no-stream
devteam run "Analyze data" --json

Options:

• -q, --queue <queue> - Target queue (gpu-queue, general-queue)
• -p, --priority <priority> - Task priority (low, normal, high, critical)
• -w, --worker <worker> - Target specific worker node
• -t, --tag <tags...> - Tags for the task
• --timeout <ms> - Task timeout in milliseconds
• --no-stream - Do not stream live output
• --json - Output in JSON format

devteam plan <goal>

Generate an AI execution plan with DAG (Directed Acyclic Graph) visualization showing task dependencies.

devteam plan "Build a full-stack e-commerce app"
devteam plan "Migrate database" --max-steps 5 --budget 50
devteam plan "Deploy to production" -x    # Execute immediately

Options:

• --max-steps <n> - Maximum number of plan steps
• --budget <amount> - Budget limit in dollars
• -c, --constraint <constraints...> - Constraints for the plan
• -x, --execute - Execute immediately after creation
• --json - Output in JSON format

devteam deploy <template-id>

Deploy a template from the marketplace with interactive input collection.

devteam deploy contract-review-v1
devteam deploy dd-pack-v1 -i company="Acme Corp" -i industry=tech
devteam deploy my-template --dry-run

Options:

• -q, --queue <queue> - Target queue
• -i, --input <inputs...> - Template inputs as key=value pairs
• --dry-run - Validate without deploying
• --json - Output in JSON format

devteam templates [search]

Browse and search the template marketplace.

devteam templates                      # List all templates
devteam templates "contract"           # Search by keyword
devteam templates --industry legal     # Filter by industry
devteam templates --category analysis  # Filter by category

Options:

• --industry <industry> - Filter by industry
• --category <category> - Filter by category
• --json - Output in JSON format

devteam status

Display a dashboard-style overview of the cluster including workers, queues, and task statistics.

devteam status           # One-time snapshot
devteam status -w        # Watch mode (refresh every 5s)
devteam status --json    # JSON output for scripting

Options:

• -w, --watch - Watch mode with auto-refresh
• --json - Output in JSON format

devteam tasks

List recent tasks with status, priority, and timing information.

devteam tasks                        # Show last 20 tasks
devteam tasks -s running             # Filter by status
devteam tasks -q gpu-queue -l 50     # Filter by queue, show 50

Options:

• -s, --status <status> - Filter by status (pending, running, completed, failed)
• -q, --queue <queue> - Filter by queue
• -l, --limit <n> - Number of tasks to show (default: 20)
• --json - Output in JSON format

devteam logs <task-id>

Stream live agent output via WebSocket connection. Shows historical output for completed tasks.

devteam logs abc123def          # View task output
devteam logs abc123def -f       # Follow mode
devteam logs abc123def --timestamps  # Show timestamps

Options:

• -f, --follow - Follow mode: keep streaming
• --timestamps - Show timestamps for each line
• --json - Output raw JSON messages

devteam approve

Interactive Human-in-the-Loop (HITL) approval queue. Review, approve, or reject pending agent decisions.

devteam approve          # Interactive review
devteam approve --auto   # Auto-approve all pending
devteam approve --json   # JSON output

Each approval shows:

• Risk level (LOW / MEDIUM / HIGH / CRITICAL)
• Confidence score
• Waiting time
• Detailed context

Actions: Approve (a) | Reject (r) | View details (v) | Skip (s) | Quit (q)

devteam workers

Show connected worker nodes with CPU, memory, GPU, and task queue information.

devteam workers          # Detailed view
devteam workers --json   # JSON output

devteam config

View and manage CLI configuration.

devteam config                          # Show all config
devteam config --set apiUrl=https://... # Set a value
devteam config --get apiKey             # Get a value
devteam config --reset                  # Reset to defaults

Configuration

Global Config

Stored in the system config directory (managed by the conf library). Contains:

| Key | Default | Description | |-----|---------|-------------| | apiUrl | https://devteam.marsala.dev | API server URL | | wsUrl | wss://devteam.marsala.dev/ws | WebSocket URL | | apiKey | (empty) | Authentication key | | defaultWorker | (empty) | Preferred worker node | | outputFormat | table | Output format (table, json, minimal) | | autoApprove | false | Auto-approve HITL items |

Project Config

Created by devteam init as devteam.config.json in the project root:

{
  "name": "my-project",
  "id": "proj_abc123",
  "apiUrl": "https://devteam.marsala.dev",
  "wsUrl": "wss://devteam.marsala.dev/ws",
  "defaultQueue": "general-queue",
  "workers": ["asus-gpu", "surface-book"],
  "templates": [],
  "environment": {}
}

Project config overrides global config for apiUrl and wsUrl.

API Endpoints

The CLI communicates with the DevTeam Orchestrator API:

| Method | Endpoint | Command | |--------|----------|---------| | GET | /api/health | login (verification) | | GET | /api/status | status | | POST | /api/tasks | run | | GET | /api/tasks | tasks | | GET | /api/tasks/:id | logs | | POST | /api/tasks/:id/cancel | (cancel) | | POST | /api/plans | plan | | POST | /api/plans/:id/execute | plan -x | | GET | /api/templates | templates | | GET | /api/templates/:id | deploy | | POST | /api/deploy | deploy | | GET | /api/workers | workers | | GET | /api/approvals | approve | | POST | /api/approvals | approve (submit) | | WS | /ws/tasks/:id/logs | logs (streaming) | | WS | /ws/events | status -w |

Development

# Install dependencies
npm install

# Run in development mode
npm run dev -- status
npm run dev -- run "test task"

# Build TypeScript
npm run build

# Run built version
npm start -- status

# Link globally
npm link
devteam status

Architecture

src/
  cli.ts           Main entry point (Commander.js program)
  api-client.ts    HTTP/WS client wrapper
  config.ts        Configuration management (conf library)
  utils.ts         Formatters, table rendering, colors
  commands/
    init.ts        Project initialization
    login.ts       Authentication
    run.ts         Quick task execution
    plan.ts        Execution planning with DAG
    deploy.ts      Template deployment
    templates.ts   Template marketplace
    status.ts      Cluster dashboard
    tasks.ts       Task listing
    logs.ts        Live log streaming
    approve.ts     HITL approval queue
    workers.ts     Worker node display
    config-cmd.ts  Config management