workctl

Unified CLI for task management across providers. One interface, multiple backends.

Currently supports ClickUp with Jira and others on the roadmap.

Install

npm install -g workctl

Requires Node.js >= 20.

Setup

Interactive:

workctl config init

Non-interactive (for CI/agents):

workctl config init --api-key pk_xxx --team-id 12345 --format json

Configuration is stored in ~/.config/workctl/config.json. Environment variables WORKCTL_API_KEY and WORKCTL_TEAM_ID override file values.

Commands

| Command | Description | |---------|-------------| | task search | Search tasks across the entire workspace | | task list --list <ID> | List tasks from a specific list | | task view <ID> | View task details | | task create <NAME> --list <ID> | Create a new task | | task update <ID> | Update a task (status, priority, name, description) | | task delete <ID> | Delete a task | | task move <ID> --to-list <ID> | Move a task to a different list | | task bulk | Bulk update tasks matching search filters | | config init | Configure API keys and provider | | introspect | Show the full API contract (for agents/tooling) |

Task IDs

All commands accept both internal IDs (abc123) and custom IDs (DEV-123). Custom IDs are auto-detected.

Search with date ranges

workctl task search --created-after "2025-01-01" --updated-before "2025-03-31" --format json

Bulk updates

workctl task bulk --filter-status "in review" --set-status "done" --format json

Move between lists

workctl task move DEV-123 --to-list list456 --format json

Markdown descriptions

Descriptions support full Markdown. Pass inline or from a file:

workctl task create "Bug report" --list abc123 --description "## Steps to reproduce
- Open login page
- Enter credentials
- Click submit

**Expected:** Dashboard loads
**Actual:** 500 error" --format json

Or load from a file:

workctl task create "Feature spec" --list abc123 --description-file ./spec.md
workctl task update DEV-123 --description-file ./updated-spec.md

In task view (human mode), Markdown is rendered with formatting for the terminal.

Agent / Programmatic Use

All commands support --format json for structured output:

• stdout: JSON result data
• stderr: JSON error objects
• Exit codes: 0 success, 2 config, 3 auth, 4 provider, 5 rate limit

Get the full API contract:

workctl introspect --format json

Generate a .cursor/rules/workctl.mdc file for LLM workspace context:

workctl introspect --emit-rules

Architecture

src/
  commands/         CLI commands (oclif)
  domain/           Models and ports (TaskProvider interface)
  providers/        Provider implementations (ClickUp, ...)
  shared/           Base command, errors, contract, formatters
  lib/              HTTP client, config service, logger

Hexagonal architecture: commands depend on ports (interfaces), not implementations. Adding a new provider means implementing TaskProvider and registering it in the factory.

Development

git clone https://github.com/itboxful/workctl.git
cd workctl
npm install
npm run build
./bin/dev.js task search

Run tests:

npm test

License

MIT