Tasks CLI

coldtea-tasks is Coldtea Tasks from the command line. It exists for two callers: a person in a terminal, and an agent in a workflow that files and updates tasks as it works. Both talk to the public /v1 API and nothing else.

Install

npm install -g @coldtea/tasks
ctask --version

The package installs two names for the same binary: coldtea-tasks, and ctask for short — fewer tokens for the agents that call it most.

Needs Node 20.6 or newer. The package has no runtime dependencies.

Auth

Create an API key in the Coldtea app with a Tasks scope, then:

export COLDTEA_API_KEY=coldtea_sk_...
ctask whoami

The key identifies your TeaHouse. There is no TeaHouse flag, and the API rejects a request that names one. tasks:read lists and reads; tasks:write creates, updates and deletes. A write-only key can file a task from a title alone; choosing a team, column or assignee takes ids that only the read commands hand out.

First run

A title is enough. The server defaults the team to your TeaHouse's only team, and the column to that team's Todo, the same column the product itself files into:

ctask create "Fix the flaky login test"

The reads are for when you want to choose:

ctask teams list                 # team ids, for when you have several
ctask states list                # board columns (--team only if several teams)
ctask labels list                # label ids for --label
ctask members list               # user ids for --assignee
export COLDTEA_TEAM_ID=team_..   # pin a team, when you have several

With several teams, an absent --team is refused with the count rather than guessed. A blank --team or --state (usually an unset shell variable) is refused rather than read as a request for the default.

Exit codes

There is no exit 1. That code means "the thing under test is broken", which QA reports about an app and Tasks has nothing to say about. No code path in this CLI can produce it.

Machine output

--json prints one JSON document on stdout, in the API's own envelope: { "data": ..., "meta": { "requestId": ... } }. List commands carry meta.nextCursor; page by copying it until it is null, never by counting rows. Errors go to stderr in the same shape, so stdout stays parseable on failure. Quote meta.requestId when reporting a problem.

Descriptions are Markdown, and tasks list never prints them: a description is where an agent pastes logs and stack traces, and a listing runs in CI where output is retained. Read one task's body with tasks get <id> --description.

Environment

Commands

Generated from the CLI's own command table, so this list cannot drift from the binary. ctask help <family> prints the full help for any group below.

ctask whoami

Show the TeaHouse and key in use.

ctask list

List the tasks in your TeaHouse.

ctask get <id>

Show one task (ORA-12 or the raw id).

ctask create <title>

File a task (title alone is enough).

ctask update <id>

Change a task in place.

ctask delete <id>

Delete a task.

ctask teams list

List the teams in your TeaHouse.

ctask states list

List a team's board columns.

ctask labels list

List a team's labels.

ctask members list

List who can be assigned work.