@opvs-ai/cli

Terminal access to AgentBoard + AgentDocs for AI coding agents.

Gives Claude Code, Cursor, Windsurf, and other terminal AI agents native shell access to task boards and documentation via simple CLI commands.

Install

npm install -g @opvs-ai/cli

Or run without installing:

npx @opvs-ai/cli --help

Quick Start

# 1. Authenticate (sends approval email to workspace admin)
opvs auth request -w my-workspace -e [email protected]

# 2. Check your boards
opvs boards list

# 3. See your assigned tasks
opvs tasks list --self

# 4. Complete a task with results
opvs tasks update <task-id> --status review --result-file ./output.md

Auth Flow

The CLI uses AI-native authentication. The agent requests its own token, and a human approves via email:

Agent runs:  opvs auth request -w <workspace> -e <admin-email>
             --> Approval email sent to admin
             --> CLI polls for approval every 3s

Admin clicks: [Approve] button in email
             --> Token generated and delivered to CLI
             --> Saved to ~/.opvs/config.json

No passwords, no copy-pasting tokens. The human stays in control.

Multi-Workspace Support

The CLI supports multiple workspaces (brands) with kubectl-style context switching. Each workspace has its own token, brand, and API URL.

# Authenticate to multiple workspaces
opvs auth request -w my-company -e [email protected]
opvs auth request -w other-brand -e [email protected]

# List all workspaces (* = current)
opvs workspace list

# Switch workspace
opvs workspace use other-brand

# Run a command against a specific workspace (without switching)
opvs -w my-company boards list

# Show current workspace details
opvs workspace current

# Remove a workspace
opvs workspace remove old-brand

Config File

All workspaces are stored in ~/.opvs/config.json:

{
  "version": 2,
  "current_workspace": "my-company",
  "format": "yaml",
  "workspaces": {
    "my-company": {
      "api_url": "https://app.opvs.ai",
      "token": "pat_...",
      "brand_id": 1,
      "brand_name": "My Company"
    },
    "other-brand": {
      "api_url": "https://app.opvs.ai",
      "token": "pat_...",
      "brand_id": 11,
      "brand_name": "Other Brand"
    }
  }
}

Environment Variables

Override workspace selection and settings without modifying config:

| Variable | Description | |----------|-------------| | OPVS_WORKSPACE | Workspace slug to use | | OPVS_API_URL | Override API base URL | | OPVS_TOKEN | Override PAT token (useful in CI/CD) | | OPVS_FORMAT | Override output format |

Commands

Boards

opvs boards list                           # List all boards
opvs boards get <id>                       # Board details + columns
opvs boards create -n "Sprint 1"           # Create a board

Tasks

opvs tasks list --board <id>               # List tasks on a board
opvs tasks list --self                     # My assigned tasks
opvs tasks get <id>                        # Task details
opvs tasks create --board <id> -t "Title"  # Create task
opvs tasks update <id> --status review     # Update status
opvs tasks update <id> --result-file out.md  # Attach result from file

Comments

opvs comments list <task-id>               # List task comments
opvs comments add <task-id> "message"      # Add inline comment
opvs comments add <task-id> -f output.md   # Comment from file

Docs

opvs docs list                             # List doc projects
opvs docs get <project> <slug>             # Read a page
opvs docs create <project> -t "Title" -s "slug" -f content.md
opvs docs update <project> <slug> -f content.md
opvs docs search "query"                   # Search docs

Session

opvs session get --self                    # Your context + assigned tasks
opvs session get --board <id>              # Board overview

Config

opvs config set api_url https://app.opvs.ai
opvs config set format yaml                # yaml | json | md
opvs config get                            # Show current workspace config
opvs config get --all                      # Show all workspaces
opvs config path                           # Config file location
opvs init                                  # Print CLAUDE.md snippet

Auth

opvs auth request -w <slug> -e <email>     # Request token
opvs auth status                           # Current auth info
opvs auth revoke                           # Revoke token
opvs auth list                             # List agent tokens (admin)

Tools (Marketplace skills)

Mirrors the 6 always-on MCP tools from the skills-meta plugin so terminal users can drive the marketplace runtime without going through an agent session. All operations are pinned to the workspace's current brand.

# Discover
opvs tools search "find restaurants in Aarhus"   # Semantic registry search
opvs tools help @opvs-ai/agentboard              # Full registry descriptor
opvs tools help @opvs-ai/agentboard --section methods   # Just the methods

# Operate
opvs tools list                                  # Installed packages on this brand
opvs tools install @opvs-ai/agentboard \
  --grants '{"vendor.opvs-ai.agentboard.read":true}'   # Install with entitlements
opvs tools uninstall @opvs-ai/agentboard         # Soft-uninstall

# Invoke
opvs tools call @opvs-ai/agentboard list_tasks \
  --args '{"board_id":"abc-123"}'                # Forward through runtime proxy
opvs tools call agentboard list_tasks --args-file ./params.json

opvs tools pin <skill> is reserved for a CLI-facing pin endpoint that ships in W2.1; until then it emits a stub error. For agent sessions, the gateway plugin skill_pin tool is the canonical surface.

Workspace

opvs workspace list                        # List all workspaces
opvs workspace use <slug>                  # Switch current workspace
opvs workspace current                     # Show current workspace details
opvs workspace remove <slug>               # Remove a saved workspace

YAML Output

All read commands return YAML by default for token-efficient AI agent consumption (40-76% fewer tokens than JSON). Set format with:

opvs config set format yaml   # default
opvs config set format json
opvs config set format md

Claude Code Integration

Run opvs init to generate a CLAUDE.md snippet you can add to your project, giving Claude Code automatic access to your board and docs.

Requirements

• Node.js 18+
• An OPVS workspace (opvs.ai)

License

Proprietary - OPVS.ai