Works CLI

Command-line interface for managing work items. Works with any AI coding agent that can run terminal commands.

Installation

npm install -g @works-cli/cli

Or run directly with npx:

npx @works-cli/cli <command>

Quick Start

# Sign in to Works (one-time)
works login

# Check who you're signed in as
works whoami

# List your assigned work
works work list

Authentication

# Sign in (opens browser for authentication)
works login

# Check current user
works whoami

# Sign out
works logout

Commands

Work Management

# List assigned work
works work list
works work list --status IN_PROGRESS
works work list --verbose

# View work details
works work view <id>
works work view <id> --full  # Show complete AGENTS.md

# Search for work
works work search "dashboard"
works work search "api" --status PENDING

# Report progress
works work progress <id> 50
works work progress <id> 75 --message "Almost done"

# Mark complete
works work complete <id> --summary "Implemented feature"
works work complete <id> --summary "Done" --files "src/app.ts,src/utils.ts"
works work complete <id> --interactive  # Prompts for details

AGENTS.md Generation

# Generate AGENTS.md for a work item
works agents-md <id>                    # Creates ./AGENTS.md
works agents-md <id> --output path.md   # Custom path
works agents-md <id> --print            # Print to stdout

Configuration (Advanced)

# Interactive configuration
works config

# Set values
works config set serverUrl https://api.works.select
works config set apiKey your-api-key

# View configuration
works config show
works config get serverUrl

# Reset to defaults
works config reset

Initialize Workspace

# Interactive - select from assigned work
works init

# With specific work ID
works init --work-id <id>

# Force overwrite existing AGENTS.md
works init --force

For AI Agents

AI agents can use these commands to interact with Works:

# Get work specification
works work view <id> --full

# Report progress during execution
works work progress <id> 25 -m "Started implementation"
works work progress <id> 50 -m "Core features done"
works work progress <id> 75 -m "Testing"

# Complete work
works work complete <id> -s "Implemented X, Y, Z" -f "file1.ts,file2.ts"

Environment Variables

You can also configure via environment variables:

export WORKS_SERVER_URL=http://localhost:3001
export WORKS_API_KEY=your-api-key

Examples

Typical Workflow

# 1. Start work on a task
works init --work-id cmj2r7f5j002hf7m0552xf01z

# 2. View full requirements
works work view cmj2r7f5j002hf7m0552xf01z --full

# 3. Report progress as you work
works work progress cmj2r7f5j002hf7m0552xf01z 30 -m "Setup complete"

# 4. Mark complete when done
works work complete cmj2r7f5j002hf7m0552xf01z \
  --summary "Implemented dashboard UI with charts" \
  --files "src/components/Dashboard.tsx,src/lib/charts.ts" \
  --pr "https://github.com/org/repo/pull/123"

CI/CD Integration

# In your CI pipeline
works work progress $WORK_ID 100 -m "Build passed"
works work complete $WORK_ID -s "Deployed to production" -p $PR_URL