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.

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

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.