@vibecontrols/cli

Command-line interface for VibeControls — development environment management from the terminal.

Talks to the Burdenoff platform via the public GraphQL gateways (global + workspace) with dual-token authentication.

Install

# From Verdaccio (internal)
bun add -g @vibecontrols/cli

# From npmjs (public, when released)
npm install -g @vibecontrols/cli

Authentication

The CLI supports three authentication methods. All workspace operations require dual-token auth (platform token + workspace token). The workspace token is issued automatically when you set a workspace.

User Authentication (OAuth2 Device Code)

Interactive browser-based login. Requires an OIDC provider with device code flow support.

# Configure OIDC endpoints
vibecontrols cli-config set oidcIssuer <oidc-issuer-url>
vibecontrols cli-config set clientId <your-oauth-client-id>

# Login — opens browser for approval
vibecontrols auth login

Local dev: Works out of the box — OIDC issuer and client ID are auto-configured from the global endpoint. Just ensure global-auth-svc and global-public-gateway are running.

Production: The CLI auto-uses https://graphql.burdenoff.com/global as the OIDC issuer. Override if needed:

vibecontrols cli-config set oidcIssuer <custom-oidc-issuer>
vibecontrols cli-config set clientId <custom-client-id>

App Authentication (Client Credentials)

For service-to-service, CI/CD, or local development. Requires an app registered in the platform.

Setup (one-time, via GraphQL on the global gateway):

# 1. Create app (via global gateway — requires an authenticated user)
curl -X POST http://localhost:4000/global/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <user-token>" \
  -d '{"query":"mutation { createApp(input: {name: \"my-cli-app\", type: CLI_TOOL, redirectUris: [\"http://localhost:3000/callback\"], scopes: [\"openid\", \"profile\"]}) { app { id clientId } clientSecret } }"}'

# 2. Authenticate the app to get its actor ID
curl -X POST http://localhost:4000/global/graphql \
  -H "Content-Type: application/json" \
  -d '{"query":"mutation { authenticateApp(input: {clientId: \"<clientId>\", clientSecret: \"<clientSecret>\"}) { accessToken } }"}'
# Decode the JWT to get the "sub" claim (this is the app's actor ID)

# 3. Add app as workspace member
curl -X POST http://localhost:4000/global/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <user-token>" \
  -d '{"query":"mutation { addWorkspaceMember(input: {workspaceId: \"<workspace-id>\", userId: \"<app-sub-from-jwt>\", role: \"MEMBER\"}) { id } }"}'

Then login via CLI:

# Login as app — prompts for client ID and secret
vibecontrols auth login --client-credentials

# Or with a specific workspace (issues workspace token immediately)
vibecontrols auth login --client-credentials --workspace-id <workspace-id>

Common Auth Commands

vibecontrols auth status                # Check current auth state
vibecontrols auth token                 # Print platform access token
vibecontrols auth token --workspace     # Print workspace token
vibecontrols auth refresh               # Force token refresh
vibecontrols auth logout                # Clear stored tokens

vibecontrols workspace list             # List available workspaces
vibecontrols workspace current          # Show current workspace
vibecontrols workspace set <id>         # Switch workspace (re-issues token)

Token Lifecycle

• Platform tokens: 1 hour (auto-refreshed via refresh token)
• Workspace tokens: 15 minutes (auto-refreshed via re-issuance)
• Client credentials: re-obtained on expiry (no refresh token)
• Token storage: ~/.config/vibecontrols-cli/auth.json (mode 0600)

Commands

16 command groups, 175 subcommands.

vibecontrols auth            Authentication (login, logout, status, token, refresh)
vibecontrols workspace       Workspace context (list, current, set)
vibecontrols agents          Agent management (19 subcommands)
vibecontrols vibes           Vibe/project management (12 subcommands)
vibecontrols sessions        Terminal sessions (31 subcommands incl. sharing)
vibecontrols notes           Notes with tag support (16 subcommands)
vibecontrols config          Backend configuration (7 subcommands incl. bulk)
vibecontrols webhooks        Webhook management (10 subcommands)
vibecontrols tunnels         Cloudflare tunnel management (4 subcommands)
vibecontrols targets         SSH/RDP/VNC targets (11 subcommands)
vibecontrols vibedeck        Command button grids (16 subcommands)
vibecontrols ai-tool-events  AI tool event tracking (5 subcommands)
vibecontrols docs            Documentation sites (19 subcommands)
vibecontrols audit           Audit logs (6 subcommands)
vibecontrols ui-session      UI state persistence (7 subcommands)
vibecontrols cli-config      CLI local settings (4 subcommands)

Run vibecontrols <command> --help for subcommand details.

Quick Examples

# Agents
vibecontrols agents list --active
vibecontrols agents create --name dev --hostname my-machine --platform linux --arch x86_64 --agent-version 1.0.0
vibecontrols agents probe <id>
vibecontrols agents health

# Vibes (projects)
vibecontrols vibes create --name my-project --path /home/user/project --type PROJECT
vibecontrols vibes search "frontend"
vibecontrols vibes move <id> --parent <parent-id>

# Sessions
vibecontrols sessions create --name dev --agent <id> --type TMUX
vibecontrols sessions start <id>
vibecontrols sessions output <id> --lines 50
vibecontrols sessions share <id> --user-id <user> --permission VIEW

# Notes with tags
vibecontrols notes create --title "TODO" --content "Fix auth flow"
vibecontrols notes tag <note-id> <tag>
vibecontrols notes search "auth"

# Targets (SSH/RDP/VNC)
vibecontrols targets create --name prod-server --type SSH --host 10.0.1.5 --port 22
vibecontrols targets scan-ssh --agent-id <id>
vibecontrols targets test <id>

# VibeDeck (command buttons)
vibecontrols vibedeck create --name "Dev Commands"
vibecontrols vibedeck create-button --deck-id <id> --label "Build" --type COMMAND --command "bun run build"
vibecontrols vibedeck execute-button <button-id> --agent-id <agent-id>

# Documentation sites
vibecontrols docs create-site --vibe-id <id> --name "API Docs"
vibecontrols docs create-page --site-id <id> --title "Getting Started" --content "# Hello"
vibecontrols docs compile <site-id>

# Audit
vibecontrols audit list --action CREATE --resource-type AGENT
vibecontrols audit stats

Configuration

CLI settings are stored in ~/.config/vibecontrols-cli/config.json.

vibecontrols cli-config list                    # Show all settings
vibecontrols cli-config set workspaceEndpoint http://localhost:4003/workspaces/graphql
vibecontrols cli-config set globalEndpoint http://localhost:4000/global/graphql
vibecontrols cli-config set oidcIssuer https://auth.burdenoff.com
vibecontrols cli-config set clientId <oauth-client-id>
vibecontrols cli-config path                    # Show config file path

Default endpoints:

• Workspace gateway: http://localhost:4003/workspaces/graphql
• Global gateway: http://localhost:4000/global/graphql

Production endpoints:

• Workspace gateway: https://graphqlworkspaces.burdenoff.com/workspaces/graphql
• Global gateway: https://graphql.burdenoff.com/global/graphql

Output Formats

All list/get commands support --format (-f):

vibecontrols agents list -f json    # JSON (default in non-TTY)
vibecontrols agents list -f table   # ASCII table (default in TTY)
vibecontrols agents list -f yaml    # YAML

Development

Prerequisites

• Bun 1.3.10+
• Node.js 24.11.0+
• TypeScript 5.9+

Setup

git clone https://github.com/Algoshred/vibecontrols-cli.git
cd vibecontrols-cli
bun install

Commands

bun run dev              # Run CLI in dev mode (tsx)
bun run dev -- --help    # Dev mode with args
bun run build            # Compile TypeScript
bun run type-check       # Type checking
bun run lint             # ESLint
bun run format           # Prettier
bun run sanity           # All checks (format + lint + type-check + build)
bun run start            # Run compiled CLI

Project Structure

src/
  cli.ts                 # Entry point, Commander.js setup
  index.ts               # Public API exports
  auth/
    device-code.ts       # OAuth2 device code flow, client credentials, workspace tokens
    store.ts             # Token persistence (~/.config/vibecontrols-cli/auth.json)
  config/
    index.ts             # CLI settings persistence
  graphql/
    client.ts            # Dual-endpoint GraphQL client with auto-refresh + retry
    operations.ts        # All GraphQL queries/mutations (~100 operations)
  commands/
    base.ts              # Shared: requireAuth, execWorkspace, execGlobal, formatAndOutput
    auth.ts              # auth login/logout/status/token/refresh
    workspace.ts         # workspace list/current/set
    agents.ts            # agents (19 subcommands)
    vibes.ts             # vibes (12 subcommands)
    sessions.ts          # sessions (31 subcommands)
    notes.ts             # notes (16 subcommands)
    config.ts            # config (7 subcommands)
    webhooks.ts          # webhooks (10 subcommands)
    tunnels.ts           # tunnels (4 subcommands)
    targets.ts           # targets (11 subcommands)
    vibedeck.ts          # vibedeck (16 subcommands)
    aitoolevent.ts       # ai-tool-events (5 subcommands)
    docs.ts              # docs (19 subcommands)
    audit.ts             # audit (6 subcommands)
    ui-session.ts        # ui-session (7 subcommands)
    cli-config.ts        # cli-config (4 subcommands)
    index.ts             # Barrel export for all command registrations
  types/
    index.ts             # Shared enums (VibeType, SessionType, TargetType, etc.)
  utils/
    output.ts            # Table/JSON/YAML formatting, colored output

Adding a New Command

1. Add GraphQL operation to src/graphql/operations.ts
2. Add command handler to the relevant src/commands/*.ts file
3. Follow the pattern: execWorkspace -> printSuccess -> formatAndOutput with handleCommandError catch
4. Run bun run sanity before committing

E2E Testing

Tests live in the workspaces-doctor repo:

cd ~/products/workspaces/workspaces-doctor

# Bootstrap test environment (creates user, workspace, tokens)
./core/scripts/bootstrap-env.sh
source ./core/env/e2e-env.sh

# Create billing account for the org (required for @usage-decorated mutations)
# Then register a real agent with tunnelUrl

# Run tests
cd wspace/modules/vibecontrols
make test-cli-auth       # Auth flow tests (user + app + workspace token)
make test-cli-full-e2e   # All 102 operations through gateway
make test-cli-all        # Both suites

CI/CD

Development (every push to main): Test -> Build -> Publish to Verdaccio (CalVer, restricted)

Release (tag push or manual dispatch): Test -> Build -> Publish to npmjs (public) + Verdaccio (restricted) -> GitHub Release

CalVer format: YYYY.MDD.PATCH (e.g., 2026.330.1)

# Local publish to Verdaccio
bun run publish:verdaccio

# Local publish to npmjs (release only)
bun run publish:npm

Architecture

User/App ─── vibecontrols CLI
                │
                ├── global-public-gateway (:4000/global/graphql)
                │     └── SignIn, RefreshToken, AuthenticateApp, MyWorkspaces
                │
                └── wspace-public-gateway (:4003/workspaces/graphql)
                      ├── Authorization: Bearer <platform-token>
                      ├── X-Workspace-Authorization: Bearer <workspace-token>
                      ├── x-org-id: <org-id>
                      │
                      └── wspace-vibecontrols-svc (subgraph)
                            ├── agents, vibes, sessions, notes
                            ├── config, webhooks, tunnels, targets
                            ├── vibedeck, ai-tool-events, docs
                            ├── audit, ui-session
                            └── PostgreSQL + Valkey

License

Proprietary - Burdenoff Consultancy Services Pvt. Ltd.

Author: Vignesh T.V. ([email protected]) Repository: https://github.com/Algoshred/vibecontrols-cli