reclaim-cli 0.2.2

A command-line tool for interacting with Reclaim.ai for task management.

Reclaim CLI

This tool provides a simple and flexible command-line interface (CLI) for managing tasks at Reclaim.ai. At its core, the tool operates through a set of commands, each targeting a specific aspect of task management. The commands allow you to create tasks, log work, lists tasks, start and stop time tracking, and more.

To see the available commands, you can simply run reclaim --help, once the tools has been installed.

reclaim --help
usage: reclaim [options] <command> ...

Reclaim CLI

positional arguments:
    add-time            add time to a task
    config              show config template
    create-task         create a task
    delete-task         delete a task
    edit-task           edit a task
    list-events         list calendar events
    list-tasks          list tasks
    log-work            log work to a task
    mark-task           mark a task (in)complete
    show-habit          show a habit
    show-load           show estimated workload
    show-task           show a task
    start-task          start a task
    stop-task           stop a task

options:
  -h, --help            show this help message and exit
  -c, --config <file>   set config file (default: ~/.reclaim)

Each command can be extended with its further options. Simply run reclaim <command> --help to see the available options. Most commands also have a short alias (e.g. tasks, events, load, create, edit) — run reclaim <command> --help to see the alias for each command.

Authentication

To authenticate the tool with Reclaim.ai, you first need to obtain an API token from your account. Visit the developer settings page and generate a new API token. Once you have your token, you can provide it to the reclaim CLI in one of two ways

(1) Add the token to the configuration file ~/.reclaim in your home directory:

$ echo "reclaim_token: <token>" >> ~/.reclaim

(2) Set the environment variable RECLAIM_TOKEN with your token value:

$ export RECLAIM_TOKEN=<token>

This ensures the tool can securely authenticate and interact with your Reclaim.ai account.

Configuration

The configuration file ~/.reclaim is a YAML file. The only required field is the API token:

reclaim_token: <token>

Calendar Colors

User events (type U) are fetched from your connected Google calendars. Since the Reclaim API does not expose calendar names, you can map calendar IDs to a name and color in the configuration file. Run reclaim config to generate a template with the calendar IDs discovered from your recent events:

$ reclaim config
# Reclaim CLI configuration (~/.reclaim)

reclaim_token: <token>

# Available calendars:
calendars:
  123456:  # Next event: Team Meeting
    name:
    color: sage
  789012:  # Next event: Lunch with Alice
    name:
    color: sage

# Available colors: tomato, flamingo, tangerine, banana, sage, basil, peacock, blueberry, lavender, grape, graphite

Fill in the name and color fields for each calendar. Color names follow the Google Calendar palette. Hex colors (e.g. #33B679) are also accepted. Once configured, user event dots and titles in list-events are colored accordingly.

Example

Here is a simple example illustrating how to use the tool. Suppose you want to create a task for writing a new blog post with a duration of 8 hours and a due date in 10 days. You would run:

reclaim create-task "Write new blog post" --duration 8h --due "in 10 days"
# ✓ Created | Id: t3k9mw | Title: Write new blog post

The output of the tool is shown as comment in the example. You can then list your tasks like this:

reclaim list-tasks
#     Id      Due          Left  Prog  State  Title
#  ●  t3k9mw  2025-04-13   8h0m    0%   N3    Write new blog post

Your task has state N (new) with default priority 3. The state column is colored yellow for at-risk tasks and red for overdue tasks. Later, you realize that you need less time for the task. Simply update it using its identifier:

reclaim edit-task t3k9mw --duration 4h
# ✓ Edited | Id: t3k9mw | Title: Write new blog post

You can also view your upcoming calendar events with the list-events command:

reclaim list-events --future 3
#     Id      Date        Start    Dur  Type  Title
#  ●  t3k9mw  2025-04-10  09:00   1h0m   T3   Write new blog post
#  ●  h2plta  2025-04-10  12:30   1h0m   H1   🍕 Lunch
#  ●  m3hsaa  2025-04-11  14:00   1h0m   M4   Team Meeting

Events are shown with a compact type code: T for tasks, H for habits, U for user calendar events, M for meetings, each followed by the priority digit. The type column is colored using the event or calendar color. The ID column links events back to their source — task IDs can be passed to commands such as show-task, edit-task, or start-task, and habit IDs to show-habit:

reclaim show-habit h2plta
# Habit h2plta: 🍕 Lunch
#    Status:       enabled        Priority:     P1
#    Duration:     1h0m - 1h0m    Ideal time:   12:30
#    Recurrence:   daily          Category:     personal
#    Created:      2023-04-16     Defense:      high
#    Updated:      2024-04-10     Private:      yes

Eventually, you notice that nobody reads blogs anymore, so you delete the task and move on:

reclaim delete-task t3k9mw
# ✓ Deleted | Id: t3k9mw | Title: Write new blog post

Installation

The tool is easiest installed directly via pip

pip install reclaim-cli

This will install the latest version of the tool. You can also install it in development mode by cloning the Github repository and running:

git clone https://github.com/rieck/reclaim-cli.git
cd reclaim-cli
pip install -e ".[dev]"

After installation, the reclaim command will be available in your local environment. If you want to work on the tool, you can use the following tools to streamline your implementation.

pre-commit install
black src/
isort src/
flake8 src/
pytest

Shell Completion

The tool supports shell completion for commands, options, and — most usefully — task and habit IDs. To enable it, generate a completion script after installation.

Fish:

register-python-argcomplete --shell fish reclaim > ~/.config/fish/completions/reclaim.fish

Bash:

echo 'eval "$(register-python-argcomplete reclaim)"' >> ~/.bashrc

Zsh:

echo 'eval "$(register-python-argcomplete reclaim)"' >> ~/.zshrc

Once activated, pressing <Tab> after a command that takes an ID will fetch and complete active task or habit IDs from your account.

Dependencies

The tool relies on the unofficial Reclaim.ai Python SDK developed by Labiso GmbH.