Husky CLI

CLI for Huskyv0 Task Orchestration with Claude Agent SDK integration.

Part of the huskyv0 monorepo

Installation

# From npm (recommended)
npm install -g @simonfestl/husky-cli

# Local development (from monorepo root)
cd packages/cli
npm install
npm run build
npm link

Quick Start

# Configure API
husky config set api-url https://your-husky-dashboard.run.app
husky config set api-key your-api-key

# Test connection
husky config test

# Interactive mode
husky

Commands

Task Management

husky task list                              # List all tasks
husky task list --status in_progress         # Filter by status
husky task list --json                       # JSON output
husky task create "Fix login bug" --priority high
husky task get <task-id>
husky task start <task-id>
husky task done <task-id> --pr https://github.com/...
husky task update <task-id> --status done
husky task delete <task-id>

Project Management

husky project list
husky project create "New Project" --description "..."
husky project get <project-id>
husky project update <project-id> --status active
husky project delete <project-id>
husky project add-knowledge <project-id> --content "..."
husky project list-knowledge <project-id>
husky project delete-knowledge <project-id> <knowledge-id>

Workflow Management

husky workflow list
husky workflow create "Onboarding" --department <id>
husky workflow get <workflow-id>
husky workflow update <workflow-id> --name "Updated"
husky workflow delete <workflow-id>
husky workflow add-step <workflow-id> --name "Step 1"
husky workflow update-step <workflow-id> <step-id> --name "Updated"
husky workflow delete-step <workflow-id> <step-id>
husky workflow generate-steps <workflow-id>    # AI-generated
husky workflow generate-mermaid <workflow-id>  # Mermaid diagram

Idea Management

husky idea list
husky idea create "New feature idea" --category feature
husky idea get <idea-id>
husky idea update <idea-id> --status approved
husky idea delete <idea-id>
husky idea convert-to-task <idea-id>

Department Management

husky department list
husky department create "Engineering"
husky department get <department-id>
husky department update <department-id> --name "Dev"
husky department delete <department-id>

VM Session Management

husky vm list
husky vm create --prompt "Fix bugs" --agent claude
husky vm get <session-id>
husky vm start <session-id>
husky vm stop <session-id>
husky vm logs <session-id>
husky vm approve <session-id>
husky vm reject <session-id> --reason "..."
husky vm update <session-id> --status approved
husky vm delete <session-id>

E2E Testing (E2E Agent)

# Run E2E tests for a task
husky e2e run <task-id>
husky e2e run <task-id> --secret ADMIN_PASSWORD --retries 2
husky e2e run <task-id> --env TEST_USER=admin --headed

# E2E Inbox (pending test requests)
husky e2e inbox                          # List all inbox messages
husky e2e inbox --status pending         # Filter by status
husky e2e inbox --task <task-id>         # Filter by task

# Watch for new E2E requests (auto-processing)
husky e2e watch --interval 30
husky e2e watch --once                   # Process once and exit

# Complete E2E test request (used by e2e-bridge)
husky e2e done <inbox-id> --passed       # Mark as passed
husky e2e done <inbox-id> --failed --notes "reason"

# Browser automation utilities
husky e2e screenshot <url>               # Take screenshot
husky e2e screenshot <url> --upload      # Upload to GCS
husky e2e record <url>                   # Record browser session

# Artifact management
husky e2e upload <file> --task <id>      # Upload to GCS
husky e2e list --task <id>               # List artifacts
husky e2e clean --older-than 7           # Clean old artifacts

PR Management (PR Agent)

husky pr list                          # List open PRs
husky pr get <pr-number>               # Get PR details
husky pr review <pr-number>            # Start review
husky pr approve <pr-number>           # Approve PR
husky pr request-changes <pr-number> --comment "..."
husky pr merge <pr-number>             # Merge PR
husky pr close <pr-number>             # Close PR

Infrastructure (DevOps)

husky infra status                     # Overall infra status
husky infra vms                        # List all VMs
husky infra services                   # Cloud Run services
husky infra logs <service>             # Service logs
husky infra metrics                    # Resource metrics

YouTube Summarization

husky youtube <url>                    # Summarize video with Gemini AI
husky youtube <url> --remember         # Also store in Second Brain
husky youtube <url> --json             # JSON output

Image Generation

husky image "a futuristic city"        # Generate image with Imagen 3
husky image "..." --output ./image.png # Save to file
husky image "..." --aspect 16:9        # Aspect ratio

Mermaid Diagrams

husky mermaid validate <file>          # Validate Mermaid syntax
husky mermaid validate --stdin         # Validate from stdin

Service Accounts

husky sa list                          # List service accounts
husky sa create <name> --role worker   # Create service account
husky sa get <id>                      # Get details
husky sa delete <id>                   # Delete service account

Agent Messaging

husky agent-msg send <to> "message"    # Send to another agent
husky agent-msg inbox                  # Check inbox
husky agent-msg read <id>              # Read message

Preview Deployments

husky preview list                     # List PR previews
husky preview get <pr-number>          # Get preview URL
husky preview logs <pr-number>         # Preview logs

Business Strategy

husky strategy show
husky strategy set-vision "Our vision..."
husky strategy set-mission "Our mission..."
husky strategy add-value --title "Innovation" --description "..."
husky strategy update-value <id> --title "Updated"
husky strategy delete-value <id>
husky strategy add-goal --title "Q1 Goal" --target "..."
husky strategy update-goal <id> --status completed
husky strategy delete-goal <id>
husky strategy add-persona --name "Developer" --description "..."
husky strategy update-persona <id> --name "Updated"
husky strategy delete-persona <id>

Process Management

husky process list
husky process create "Release Process" --department <id>
husky process get <process-id>
husky process update <process-id> --name "Updated"
husky process delete <process-id>

Roadmap Management

husky roadmap list
husky roadmap get <roadmap-id>
husky roadmap create "Q1 2025" --description "..."
husky roadmap update <roadmap-id> --name "Updated"
husky roadmap delete <roadmap-id>
husky roadmap add-phase <roadmap-id> --name "Phase 1"
husky roadmap add-feature <roadmap-id> --phase <id> --title "Feature"
husky roadmap list-features <roadmap-id>
husky roadmap update-feature <roadmap-id> <feature-id> --status done
husky roadmap delete-feature <roadmap-id> <feature-id>
husky roadmap convert-feature <roadmap-id> <feature-id>  # To task
husky roadmap generate                                    # AI-generated

Changelog Management

husky changelog generate --from <tag> --to HEAD
husky changelog list
husky changelog show <changelog-id>
husky changelog publish <changelog-id>
husky changelog delete <changelog-id>

VM Config Management

husky vm-config list
husky vm-config create --machine-type e2-medium --disk-size 50
husky vm-config update <config-id> --machine-type e2-standard-2
husky vm-config delete <config-id>

Chat / Messaging

# Check pending messages
husky chat pending
husky chat pending --json

# View inbox (GitHub + Google Chat)
husky chat inbox
husky chat inbox --unread

# Reply to any message (auto-detects platform)
husky chat reply-to <messageId> "Your response"

# Reply in Google Chat thread
husky chat reply-chat "Message" --thread <threadName>

# Mark message as read
husky chat mark-read <messageId>

# Watch for messages (inject into tmux)
husky chat watch-inject --tmux-session supervisor

The reply-to command automatically detects whether the message is from GitHub or Google Chat and uses the appropriate API to send the reply.

Settings

husky settings get <key>
husky settings set <key> <value>

Configuration

husky config set api-url https://your-husky-dashboard.run.app
husky config set api-key your-api-key
husky config get api-url
husky config list
husky config test

Authentication (Session Tokens)

Session tokens provide short-lived JWT authentication for agents. They are created using HUSKY_API_KEY and auto-refresh when expired.

# Login (creates 1-hour session token)
husky auth login --agent supervisor
husky auth login --agent husky-worker-1

# Check session status
husky auth session
husky auth session --json

# Refresh token manually
husky auth refresh
husky auth refresh --agent supervisor

# Logout (clear session)
husky auth logout

VM Startup Pattern:

#!/bin/bash
VM_NAME=$(hostname)
husky auth login --agent "$VM_NAME"
# All subsequent commands use Bearer token

How it works:

1. HUSKY_API_KEY is used once to create a session token
2. All subsequent API calls use Authorization: Bearer <token>
3. Token auto-refreshes when expired or within 5 minutes of expiry
4. Falls back to x-api-key if refresh fails

Help & Documentation

husky explain task          # Explain task commands
husky explain workflow      # Explain workflow commands
husky explain all           # Full documentation
husky --help

Shell Completion

husky completion bash >> ~/.bashrc
husky completion zsh >> ~/.zshrc
husky completion fish > ~/.config/fish/completions/husky.fish

Environment Variables

| Variable | Description | |----------|-------------| | HUSKY_API_URL | Husky Dashboard URL | | HUSKY_API_KEY | Husky API key | | ANTHROPIC_API_KEY | Anthropic API key for Claude | | GITHUB_TOKEN | GitHub token for commits (optional) |

Development

# From monorepo root
cd packages/cli

# Install dependencies
npm install

# Build
npm run build

# Watch mode
npm run dev

# Link globally for testing
npm link

Publishing / Release

Publishing a New Version

cd packages/cli

# 1. Bump version
npm version patch  # or minor/major

# 2. Publish to npm (opens browser for authentication)
npm publish --access public

# 3. Commit and push
git add .
git commit -m "chore(cli): release vX.X.X"
git push origin main

Updating on Other Devices

# Update to latest version
npm update -g @simonfestl/husky-cli

# Or reinstall
npm install -g @simonfestl/husky-cli

# Check installed version
husky --version

Changelog

v1.12.0 (2026-01-12) - Session Token Authentication

New Features:

• husky auth login --agent <name> - Create session token from HUSKY_API_KEY
• husky auth logout - Clear session token
• husky auth session - Show session status (agent, role, expiry)
• husky auth refresh - Manually refresh token

Improvements:

• All API calls now use Bearer token authentication (auto-refresh)
• Token auto-refreshes when expired or within 5 minutes of expiry
• Falls back to x-api-key for backwards compatibility
• JWT_SECRET now required in production (fail-fast)

Documentation:

• Added missing command sections: pr, infra, youtube, image, mermaid, sa, agent-msg, preview
• Updated architecture docs with session token flow

Code Quality:

• Removed as any type suppression in sop.ts

v1.7.0 (2026-01-11) - E2E Agent Production Ready

New Features:

• husky e2e inbox - List E2E test requests from API
• husky e2e watch - Watch for and auto-process E2E requests
• husky e2e run --secret - Inject secrets from GCP Secret Manager
• husky e2e run --env - Set environment variables for tests
• husky e2e run --retries - Retry failed tests automatically

Improvements:

• All artifact URLs now use HTTPS
• Better error handling in E2E commands
• Updated permissions for e2e_agent role

v1.1.0 (2026-01-09) - Unified Reply System

New Features:

• husky chat reply-to now supports both GitHub and Google Chat
• Auto-detects platform from message metadata
• GitHub replies use GitHub App (no PAT required on VM)

Improvements:

• Require 8+ character prefix for messageId matching (prevents misdirected replies)
• Better error messages for short messageId prefixes

v1.0.0 (2026-01-08) - Supervisor Architecture

BREAKING CHANGES:

• Removed: husky jules commands (replaced by supervisor architecture)
• Removed: husky services commands (deprecated)
• Removed: VM Pool management (now automated by supervisor)
• Deprecated: husky agent commands (use husky task instead)

New Features:

• Added: husky chat command for supervisor communication
• Added: Project resolver to prevent orphaned tasks
• Added: Implementation plans via husky task plan
• Added: QA review pipeline support

Improvements:

• Version now read dynamically from package.json
• Simplified task workflow
• Scope-based API key system support

v0.5.0 (2026-01-06)

• Full Dashboard feature parity (69 new commands)
• Added: project, workflow, idea, department, vm, jules, process, strategy, settings, vm-config commands
• Added: Interactive TUI mode (husky without args)
• Added: Shell completion (bash/zsh/fish)
• Added: --json flag for all commands
• Monorepo migration from separate husky-cli repo

v0.3.0 (2026-01-05)

• Added roadmap commands (list, get, create, generate, phases, features)
• Added changelog commands (generate, list, show, publish)
• Added explain command for documentation
• Added config test command

v0.2.0 (2025-01-05)

• Added agent commands (plan, execute, wait-approval)
• Added StreamClient with batching for efficient API calls
• Integration with Claude Agent SDK
• Support for planning phase before execution

v0.1.0 (2025-01-04)

• Initial release
• Task management commands (list, create, start, done)
• Configuration management
• API key authentication

License

MIT