Documentation

CLI Tool

Work through tasks from Trello, GitHub, or GitLab directly from your terminal. Choose your AI provider, navigate to any project directory, and let the agent work through your tasks — checking off items as it goes.

View on npm

Install

Run instantly with npx — no install required:

npx taskpilot-cli login

Or install globally for a shorter command:

npm install -g taskpilot-cli

# Then use anywhere:
taskpilot login
taskpilot run

Prerequisites

At least one task source connected: Trello, GitHub, or GitLab
At least one AI provider API key: Anthropic (Claude), OpenAI, or Groq
Node.js 20+ installed
Claude Code installed (npm i -g @anthropic-ai/claude-code) — required only when using the Claude provider

Quick Start

All examples use npx taskpilot-cli. If you installed globally, replace with just taskpilot.

Register or sign in

Create a new account, or sign in if you already have one:

# New user — create an account
npx taskpilot-cli register

# Returning user — sign in
npx taskpilot-cli login

Connect a task source and API key

The setup wizard walks you through connecting a task source (Trello, GitHub, or GitLab) and saving your AI provider API key:

npx taskpilot-cli setup

# TaskPilot — Setup
#
#   1. Trello Not connected
#
# ? Open your browser to connect Trello? Yes
#   Opening: https://trello.com/1/authorize?...
#   ⠋ Waiting for Trello connection...
#   ✓ Trello connected!
#
#   2. API Key Not set
#
#   Get your key from https://console.anthropic.com/settings/keys
#
# ? Paste your API key: sk-ant-api03-••••••
#   ✓ API key saved (encrypted on server)
#
#   All set! Run `taskpilot run` to start a session.

You can also connect GitHub and GitLab, or add additional AI provider keys (OpenAI, Groq) from the web app Settings page.

Navigate to your project

Open your terminal in the codebase you want Claude to work on:

cd ~/my-project

Run a session

Select a board or repo, review the tasks, and launch an AI session:

npx taskpilot-cli run

# ? Select a board:
# ❯ My Project Board
#   Side Project
#   Personal Tasks
#
# My Project Board
# ─────────────────
#
#   To Do (3 cards):
#     • Fix authentication bug [0/4]
#     • Add dark mode support [0/3]
#     • Update API documentation [0/2]
#
#   In Progress (1 card):
#     • Refactor API layer [1/5]
#
#   Done (2 cards) [skipped]
#
#   Working directory: /home/you/my-project
#
# ? Start Claude Code session? (4 active cards) Yes
#
# ✓ Credentials loaded
# Starting Claude Code session...
#
#   Session initialized (model: claude-sonnet-4-20250514)
#
# I'll start by working on "Fix authentication bug"...
#   [Read]
#   [Edit]
#   ✓ Checked item on Trello
#   ✓ Checked item on Trello
#   ✓ Moved card to Done
# Moving on to "Add dark mode support"...

Commands

npx taskpilot-cli registerCreate a new account (email, password, name)

-s, --server <url>Server URL (default: https://ct.joshualevine.me)

npx taskpilot-cli loginSign in to an existing account

-s, --server <url>Server URL (default: https://ct.joshualevine.me)

npx taskpilot-cli setupConnect a task source and save your AI provider API key (interactive wizard)

npx taskpilot-cli logoutClear your stored session

npx taskpilot-cli runSelect a task source and start an AI coding session

-b, --board <id>Board/repo ID — skip interactive selection

-d, --dir <path>Working directory (default: current directory)

-m, --message <text>Initial instructions for the AI (e.g. "check the dev branch for comparison")

-s, --source <name>Task source: trello, github, or gitlab (default: trello)

-P, --provider <name>AI provider: claude, openai, or groq (default: claude)

-p, --parallelRun one agent per card/issue in parallel (uses git worktrees)

-c, --concurrency <n>Max concurrent agents in parallel mode (1-5, default: 3)

npx taskpilot-cli boardsList all your Trello boards with their IDs

npx taskpilot-cli reposList your connected GitHub repositories

npx taskpilot-cli statusCheck auth and integration status

How It Works

Authenticate — The CLI signs in to the web app and stores your session cookie locally. No credentials are stored in plaintext.

Fetch task data — Boards, cards, and checklists (or GitHub/GitLab issues with task lists) are fetched via the web app's API using your stored connection.

Load credentials — Your AI provider API key (encrypted in the database) is securely retrieved and decrypted for the session.

Run your AI agent locally — The AI agent (Claude, OpenAI, or Groq) launches in your working directory with full access to your codebase. It reads, edits, and creates files to complete each task.

Update tasks automatically — As the agent completes each task, it marks it done on your task source. On Trello, cards move to Done. On GitHub/GitLab, task list items get checked and issues can be closed.

Examples

Skip board selection with a board ID

Get the board ID from npx taskpilot-cli boards and pass it directly:

npx taskpilot-cli boards
#   My Project Board  60d5e2a3f1a2b40017c3d4e5
#   Side Project      507f1f77bcf86cd799439011

npx taskpilot-cli run --board 60d5e2a3f1a2b40017c3d4e5

Run on a different directory

Point Claude Code at a specific project without navigating there first:

npx taskpilot-cli run --dir ~/projects/my-api

Check your connection status

Verify everything is set up correctly before starting a session:

npx taskpilot-cli status

# TaskPilot — Status
#
#   Server:  https://ct.joshualevine.me
#   Auth:    Signed in as Your Name
#   Trello:  Connected
#   API Key: Configured
#
#   Ready to go! Run `taskpilot run` to start.

Give the agent extra context with --message

Pass initial instructions so the agent knows how to approach the work. Without --message, the CLI will prompt you interactively (press Enter to skip).

# Give the agent context before it starts
npx taskpilot-cli run --message "Check the development branch for comparison"

# Or be more specific
npx taskpilot-cli run --message "Focus on the API cards first, skip frontend for now"

# Without --message, you'll be prompted interactively:
# ? Instructions for the AI (optional — press Enter to skip):

Work from GitHub or GitLab issues

Use --source to pull tasks from GitHub issues or GitLab issues instead of Trello:

# Work through GitHub issues
npx taskpilot-cli run --source github

# Work through GitLab issues
npx taskpilot-cli run --source gitlab

# List your GitHub repos first
npx taskpilot-cli repos

Choose a different AI provider

Switch between Claude, OpenAI, or Groq with --provider. You must have the corresponding API key saved in Settings.

# Use OpenAI (gpt-4o) instead of Claude
npx taskpilot-cli run --provider openai

# Use Groq (llama-3.3-70b) for fast inference
npx taskpilot-cli run --provider groq

Run agents in parallel

Launch one agent per card/issue simultaneously using isolated git worktrees. Changes are merged back sequentially when complete.

# Run agents in parallel (default: 3 concurrent)
npx taskpilot-cli run --parallel

# Control concurrency (1-5 agents)
npx taskpilot-cli run --parallel --concurrency 5

# Combine with other flags
npx taskpilot-cli run --source github --provider openai --parallel

Full scripted workflow

Combine flags for a non-interactive launch:

# Login once
npx taskpilot-cli login

# Then run from anywhere with all options
npx taskpilot-cli run \
  --source github \
  --provider claude \
  --parallel \
  --dir ~/projects/my-api \
  --message "Just go"

Troubleshooting

"Session expired" error

Your login session has expired. Run npx taskpilot-cli login again to re-authenticate.

"Source not connected" or "API key not configured"

The CLI uses your web app account's integrations. Go to the web dashboard Settings page to connect your task source (Trello, GitHub, or GitLab) and save the API key for your chosen AI provider, then try the CLI again.

Can I use the CLI without the web server running?

The CLI connects to ct.joshualevine.me by default. If the site is down, the CLI won't work. You can also self-host and point at your own instance with --server.

Where is my session stored?

Your session cookie and server URL are stored at ~/.config/taskpilot/config.json with restricted file permissions (600). Run npx taskpilot-cli logout to clear it.

Claude asked me a question — what do I do?

Sometimes Claude needs clarification before proceeding. The question will appear in yellow in your terminal with a > prompt. Type your answer and press Enter — Claude will continue working.

Security

All API keys are encrypted at rest (AES-256-GCM) and only decrypted for the duration of a session
The local config file is written with restricted permissions (owner-only read/write)
Credentials are held in memory only during a session — never written to disk by the CLI
Claude Code runs with acceptEdits permission mode — it can read and edit files but won't run arbitrary shell commands without approval