Package Exports

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@opvs-ai/cli) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

@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 admin@example.com

# 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 admin@mycompany.com
opvs auth request -w other-brand -e admin@other.com

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

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