CLI

The Worksome CLI is a command-line tool for interacting with the Worksome GraphQL API. It provides broad API coverage across 60+ resource groups and 170+ operations, and is designed for both human users and AI agents.

Installation

Each release includes pre-built binaries for macOS, Linux, and Windows. Install Go 1.26+ if you want to build from source.

# Build from source (requires Go 1.26+)
go install github.com/worksome/worksome-cli/cmd/worksome@latest

Run worksome version to check the installed version.

Authentication

The CLI uses Personal Access Tokens (PATs). See Authentication for how to create one.

Token resolution order:

1. --token flag (highest priority)
2. WORKSOME_API_TOKEN environment variable
3. Config file (~/.worksome/config.yaml)

The endpoint and profile resolve the same way, via --endpoint/WORKSOME_ENDPOINT and --profile/WORKSOME_PROFILE.

Setting up authentication

# Interactive setup — saves token to config file (under the `default` profile unless --profile is given)
worksome auth login

# Check current auth status
worksome auth status

# List configured profiles
worksome auth list

# Switch to another profile you have created
worksome auth switch stage

# Remove a profile and its stored credentials
worksome auth logout stage

Multiple profiles

Use --profile to manage different accounts or environments. Profile names are arbitrary — create the ones you need with worksome auth login --profile <name>.

worksome --profile stage hires list
worksome --profile default hires list

Usage

The CLI uses a resource action pattern:

worksome <resource> <action> [flags]

Querying data

# Get a single resource
worksome hires get <id>

# List resources (paginated by default)
worksome hires list

# Fetch all pages
worksome hires list --all

# Custom page size
worksome hires list --first 50

# Specific page
worksome hires list --page 3

# Re-run and refresh the list every 5 seconds
worksome hires list --watch

# Filter and search
worksome hires list --active-status ACTIVE --search "john"

Creating and modifying resources

# Create via flags
worksome jobs create --company <id> --name "Backend Engineer"

# Create via JSON file (use `-` to read from stdin)
worksome jobs create --input job.json

# Mix both (flags override file values)
worksome hires terminate --input base.json --reason "PROJECT_COMPLETED_EARLY"

# Preview the operation and variables without executing
worksome jobs create --company <id> --name "Test" --dry-run

Output formats

The CLI auto-detects your terminal. When output is piped, it defaults to JSON; in an interactive terminal, it uses human-friendly formatting.

# Force JSON output
worksome hires list --output json

# Force table output
worksome hires list --output table

# Pipe-friendly
worksome hires list --output json | jq '.[] | .id'

Available resources

The CLI covers the full Worksome API. Some commonly used resource groups:

Run worksome --help for the full list, or worksome <resource> --help for available actions on a resource.

Shell completion

# Bash
source <(worksome completion bash)

# Zsh
source <(worksome completion zsh)

# Fish
worksome completion fish | source

# PowerShell
worksome completion powershell | Out-String | Invoke-Expression

Global flags

Support

For issues with the CLI or to request features, contact Support.

Other integrations

• GraphQL API — Full programmatic access for custom integrations.
• Webhooks — Real-time event notifications.
• PHP SDK — Official PHP SDK for the Worksome API.
• Zapier — No-code automation with triggers and actions.
• MCP Server — AI agent integration via Model Context Protocol.
• AI Agents — AI-ready documentation and agent integration guide.