compass CLI

Compass CLI — command-line interface for the Davai Ticketing API.

Installation

Option 1: Quick Install (recommended)

Using Bun:

# One-time run from the npm package
bunx --bun @compasswork/cli

# Or install globally
bun install -g @compasswork/cli

Using npm/npx:

# One-time run
npx @compasswork/cli

# Or install globally
npm install -g @compasswork/cli

The npm/Bun package only publishes the compiled /cli output (dist, README.md, LICENSE), so none of the other workspace files are exposed.

Option 2: Standalone Binary (no runtime needed)

Download the prebuilt binary for your platform from GitHub Releases:

# Linux x64
curl -fsSL https://github.com/davaico/ticketing/releases/latest/download/compass-linux-x64 -o compass
chmod +x compass
sudo mv compass /usr/local/bin/

# macOS arm64 (Apple Silicon)
curl -fsSL https://github.com/davaico/ticketing/releases/latest/download/compass-darwin-arm64 -o compass
chmod +x compass
sudo mv compass /usr/local/bin/

Option 3: Build from Source

# Clone just the CLI (sparse checkout)
git clone --filter=blob:none --sparse https://github.com/davaico/ticketing.git
cd ticketing
git sparse-checkout set cli

# Install and build
cd cli
bun install
bun run build

# Link globally
bun link

Configuration

The CLI stores config in ~/.compass/config.json:

{
  "token": "your-jwt-token",
  "apiBase": "https://ticketing-api.davai.co/api"
}

You can also set the API base via:

• --api flag on any command
• API_BASE environment variable

Authentication

For humans (email + OTP):

# Request OTP
compass login --email [email protected]

# Complete login with OTP
compass login --email [email protected] --otp 123456

For agents/performers (token):

# Login with performer token (generated by admin)
compass login --token <your-performer-token>

# Or set API base at the same time
compass login --token <token> --api https://ticketing-api.davai.co/api

Commands

Health Check

compass health

Projects

# List all projects
compass projects

# Get project details
compass project <id>

# Create project
compass create-project --name "Project X" --customer "Acme Corp"

# Update project
compass update-project <id> --name "New Name" --mode maintain

Tickets

# List tickets for a project
compass tickets --project <projectId>

# Get ticket details
compass ticket <id>

# Create ticket
compass create-ticket --project <projectId> --title "Bug: login fails" --type performer

# Update ticket
compass update-ticket <id> --status in_progress
compass update-ticket <id> --title "New title" --description "Details..."
compass update-ticket <id> --assigned-to <userId>

# Bulk assign tickets
compass assign --tickets id1,id2,id3 --to <userId>

# Link tickets
compass link-ticket <id> --tickets <linkedId1>,<linkedId2>

Comments

# List comments
compass ticket-comments <ticketId>

# Add comment
compass add-comment <ticketId> --text "Working on this now"

# Update comment
compass update-comment <ticketId> <commentId> --text "Updated text"

# Reactions
compass add-reaction <ticketId> <commentId> --emoji 👍
compass remove-reaction <ticketId> <commentId> --emoji 👍

Releases

# List releases
compass releases --project <projectId>

# Create release
compass create-release --project <projectId> --version "v1.2.0" --notes "Bug fixes" --tickets id1,id2

Users & Tokens (Admin)

# List users
compass users

# Create user
compass create-user --username "agent-1" --role PERFORMER

# Create performer token
compass create-token --user <userId>

# List tokens
compass tokens --user <userId>

# Revoke token
compass revoke-token <tokenId>

Agent Workflow Example

Typical workflow for an AI agent:

# 1. Login with performer token
compass login --token $PERFORMER_TOKEN --api https://ticketing-api.davai.co/api

# 2. List assigned tickets
compass tickets --project $PROJECT_ID | jq '.[] | select(.assignedTo == "'$AGENT_USER_ID'")'

# 3. Pick up a ticket
compass update-ticket $TICKET_ID --status in_progress

# 4. Add progress comment
compass add-comment $TICKET_ID --text "Starting work on this issue"

# 5. ... do the work ...

# 6. Mark for review
compass update-ticket $TICKET_ID --status in_review
compass add-comment $TICKET_ID --text "Completed. PR: https://github.com/..."

JSON Output

All commands output JSON for easy parsing:

# Pretty print with jq
compass tickets --project $PID | jq '.'

# Get specific fields
compass ticket $TID | jq '.ticket.status'

# Filter tickets
compass tickets --project $PID | jq '.[] | select(.status == "needs_doing")'

Building Standalone Binary

To create a standalone binary (no Bun/Node required):

cd cli
bun run build
bun build --compile --minify dist/index.js --outfile compass

# Creates: ./compass (single executable)

Cross-compile for different platforms:

bun build --compile --target=bun-linux-x64 dist/index.js --outfile compass-linux-x64
bun build --compile --target=bun-darwin-arm64 dist/index.js --outfile compass-darwin-arm64
bun build --compile --target=bun-darwin-x64 dist/index.js --outfile compass-darwin-x64

Environment Variables

| Variable | Description | |----------|-------------| | API_BASE | API base URL (default: http://localhost:3000/api) |

Troubleshooting

"Unauthorized" errors:

• Run compass login to authenticate
• Check ~/.compass/config.json has a valid token

"Connection refused":

• Verify the API is running
• Check --api or API_BASE points to correct URL

Token expired:

• Re-run compass login with your credentials or token