cctodo

The command line tool and Python client for ccToDo, made by CloudCircus.

pip install cctodo
cctodo login          # paste a token from Settings → API tokens
cctodo mytasks
cctodo new -group "work group" "my task"
cctodo done 123

It uses only the Python standard library and needs Python 3.9 or newer.

Commands

Tasks are shown with their id (#123), and the commands take that id. Where a command takes a group, you can give its id, its title, or the start of the title (case-insensitive). Without -g, commands use your My Tasks.

A milestone is a goal with a target date that tasks in the same group can belong to (one milestone per task). It's reached when it has no pending tasks and every milestone before it is reached. Give a milestone by its id, or by its title (or the start of it) together with -g GROUP.

Add --json to any command for the raw API output. NO_COLOR turns colours off.

Exit codes:

• 0: the command succeeded.
• 1: an error occurred.
• 3: you're not logged in, or your token was revoked.

Configuration

cctodo login saves the token in ~/.config/cctodo/config.json, readable only by you (%APPDATA%\cctodo\config.json on Windows). You can set these environment variables instead:

• CCTODO_TOKEN: the API token.
• CCTODO_API_URL: the API address. It defaults to https://api.cctodo.com.
• CCTODO_CONFIG: a different config file.

To revoke a token, go to Settings → API tokens on www.cctodo.com.

Python

from cctodo import Client, Conflict

todo = Client()                                  # the same token as the CLI (or Client(token="cct_..."))
work = todo.find_group("work group")
task = todo.create_task(work.id, "Write the report", body="Due **Friday**")
todo.assign(task.id, todo.me().id)
todo.start(task.id)

for t in todo.tasks(work.id):                    # pending tasks, in order
    print(t.id, t.state, t.title)                # attribute or t["title"] access

roof = todo.create_milestone(work.id, "Roof on", "2026-11-01", description="Tiles **and** gutters")
todo.set_milestone(task.id, roof.id)             # or None to take it out
for m in todo.milestones(work.id):               # in order of target date
    print(m.title, m.target_date, "reached" if m.reached else f"{m.pending_count} to go")

try:
    todo.update_task(task.id, body="…", expected_updated_at=task.updated_at)
except Conflict:
    print("Someone else changed it first")

Return values: results are the API's JSON as Record objects (dicts with attribute access).

Errors: errors raise cctodo.NotFound (404; this also covers groups you're not in), NotAllowed (403), Invalid (400), Conflict (409), RateLimited (429) or Unauthorized (401). All of them subclass cctodo.CctodoError.

Development

pip install -e .
python -m unittest discover -s . -t .
CCTODO_API_URL=http://api.localhost:8000 cctodo whoami      # against a local cctodo_web

Licence

MIT. See LICENSE.