Works CLI - Manage work items from the terminal
npm install @works-cli/clibash
npm install -g @works-cli/cli
`
Or run directly with npx:
`bash
npx @works-cli/cli
`
Quick Start
`bash
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
`bash
Sign in (opens browser for authentication)
works login
Check current user
works whoami
Sign out
works logout
`
Commands
$3
`bash
List assigned work
works work list
works work list --status IN_PROGRESS
works work list --verbose
View work details
works work view
works work view --full # Show complete AGENTS.md
Search for work
works work search "dashboard"
works work search "api" --status PENDING
Report progress
works work progress 50
works work progress 75 --message "Almost done"
Mark complete
works work complete --summary "Implemented feature"
works work complete --summary "Done" --files "src/app.ts,src/utils.ts"
works work complete --interactive # Prompts for details
`
$3
`bash
Generate AGENTS.md for a work item
works agents-md # Creates ./AGENTS.md
works agents-md --output path.md # Custom path
works agents-md --print # Print to stdout
`
$3
`bash
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
`
$3
`bash
Interactive - select from assigned work
works init
With specific work ID
works init --work-id
Force overwrite existing AGENTS.md
works init --force
`
For AI Agents
AI agents can use these commands to interact with Works:
`bash
Get work specification
works work view --full
Report progress during execution
works work progress 25 -m "Started implementation"
works work progress 50 -m "Core features done"
works work progress 75 -m "Testing"
Complete work
works work complete -s "Implemented X, Y, Z" -f "file1.ts,file2.ts"
`
Environment Variables
You can also configure via environment variables:
`bash
export WORKS_SERVER_URL=http://localhost:3001
export WORKS_API_KEY=your-api-key
`
Examples
$3
`bash
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"
`
$3
`bash
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
``