taskctl

taskctl is the lightweight Task Control CLI introduced for TAS-76.

This V1 keeps the existing Next.js app structure intact and adds a small root-level cli/ folder rather than migrating the repo into a full workspace layout.

Install

Once published, users should be able to install the CLI with npm:

npm install -g @taskcontrol/taskctl

Or run it without a global install:

npx @taskcontrol/taskctl context

Local build

From the repo root:

npm run build:cli

This compiles the CLI into cli/dist.

For a one-shot local run:

npm run taskctl -- context

To produce a publishable tarball from the repo root:

npm run pack:cli

That creates a package tarball such as taskcontrol-taskctl-0.1.0.tgz.

Configuration

For normal use, especially in shared terminals, recorded demos, or screen shares, prefer a config file and run taskctl without passing secrets on the command line.

The CLI reads its configuration in this order:

1. command-line flags
2. config file values
3. environment variables
4. built-in defaults

Supported values:

• --config for an explicit config file path
• --base-url or TASKCONTROL_BASE_URL
• --project-id or TASKCONTROL_PROJECT_ID
• --api-key or TASKCONTROL_API_KEY
• --agent-name or TASKCONTROL_AGENT_NAME

Default config file discovery:

• project-local: nearest .taskctl.json in the current directory or a parent directory
• user-level: ~/.config/taskctl/config.json

Defaults:

• base-url: https://www.taskcontrol.dev
• agent-name: task-agent

Recommended project-local config:

{
  "baseUrl": "https://www.taskcontrol.dev",
  "projectId": "3295537a-d0ed-45ca-8153-2dea9d132807",
  "apiKey": "YOUR_KEY",
  "agentName": "developer-agent"
}

Save that as .taskctl.json in the repo you are working in. The CLI will use it from that folder and its subfolders. Add .taskctl.json to .gitignore if it contains an API key.

Optional user-level fallback:

{
  "baseUrl": "https://www.taskcontrol.dev",
  "agentName": "developer-agent"
}

Create it at:

mkdir -p ~/.config/taskctl
$EDITOR ~/.config/taskctl/config.json

After that, run commands without inline credentials:

taskctl context
taskctl state --status ready
taskctl task claim <task-id>

Avoid putting project-specific projectId or apiKey values in user-level config unless you intentionally want the same Task Control project in every folder.

Environment-variable example:

export TASKCONTROL_PROJECT_ID=3295537a-d0ed-45ca-8153-2dea9d132807
export TASKCONTROL_API_KEY=YOUR_KEY
export TASKCONTROL_AGENT_NAME=developer-agent

Then users can run:

taskctl context
taskctl state --status ready

Or override with an explicit config file:

taskctl --config /path/to/config.json context

Commands

Project reads

taskctl context
taskctl activity
taskctl activity --actor-id <user-id>
taskctl done
taskctl done --page 2
taskctl members
taskctl bootstrap
taskctl agent heartbeat
taskctl agent session
taskctl agent profile
taskctl agent profile update --preferred-role developer-agent --commit-behavior per_ticket
taskctl agent release
taskctl state
taskctl state --status ready
taskctl state --ticket-number 76
taskctl state --q CLI

Standups

taskctl standup status
taskctl standup create --content "Completed: x. Working on: y. Blocked: none."
taskctl standup update <standup-id> --content "Updated standup text"
taskctl standup delete <standup-id>

Documents

taskctl document list
taskctl document get <document-id>
taskctl document create --title "Spec" --content-md "# Heading"
taskctl document update <document-id> --title "Updated spec"
taskctl document delete <document-id>

Task operations

taskctl task get <task-id>
taskctl task update <task-id> --priority high
taskctl task update <task-id> --acceptance-items '["First criterion","Second criterion"]'
taskctl task update <task-id> --acceptance-items '[]'
taskctl task update <task-id> --token-estimate-min 10000 --token-estimate-max 25000
taskctl task update <task-id> --assigned-to null
taskctl task update <task-id> --blocked-by null
taskctl task delete <task-id>
taskctl task create --title "Add CLI"
taskctl task create --title "Add CLI" --acceptance-items '["Create command sends checklist items"]' --token-estimate-min 8000 --token-estimate-max 16000
taskctl task bulk-create --file ./tasks.json
taskctl task claim <task-id>
taskctl task move <task-id> testing
taskctl task comments <task-id>
taskctl task comment <task-id> --content "Ready for review"
taskctl task finish <task-id> --comment "Ready for testing"
taskctl task release <task-id>

Create example

taskctl task create \
  --title "Improve task review" \
  --description "Add a first-class finish-work action." \
  --acceptance-items '["Records a completion summary","Moves the task to testing"]' \
  --token-estimate-min 12000 \
  --token-estimate-max 30000 \
  --status backlog \
  --priority high

Bulk create example

Create a JSON file like:

[
  {
    "title": "Plan world clock app",
    "description": "Create the planning task",
    "acceptance_items": [
      { "id": "ac-1", "text": "Goals are captured", "done": false }
    ],
    "status": "ready",
    "priority": "high"
  },
  {
    "title": "Add timezone dataset",
    "status": "backlog"
  }
]

Then run:

taskctl task bulk-create --file ./tasks.json

Notes

• Output is pretty-printed JSON so the CLI stays composable.
• The CLI talks only to the public HTTP API. It does not import or call server internals directly.
• A project-local config file is best when different folders map to different Task Control projects.
• A user-level config file is best for non-project-specific defaults such as baseUrl and agentName.
• Environment variables are still useful for CI, one-off runs, and agent runtimes.
• If you use a project-local .taskctl.json, do not commit secrets by accident.
• taskctl agent heartbeat and taskctl agent release manage the agent session lock explicitly when a workflow needs it.

Publishing

Suggested release flow from this repo:

npm run build:cli
npm run pack:cli
cd cli
npm publish --access public

Before publishing, make sure:

• the npm package name is available or the npm scope exists
• the version in cli/package.json is correct
• the CLI works in a normal networked environment
• install instructions match the published package name