Welcome to tasks3’s documentation!


https://img.shields.io/pypi/v/tasks3.svg https://github.com/hXtreme/tasks3/actions/workflows/tox-test.yml/badge.svg Documentation Status

A commandline tool to create and manage tasks and todos.

Most task management tools are their own applications, so to manage tasks you have to perform context switching by leaving what you’re working on to go to the task manager application.

tasks3 aims to solve that by bringing your tasks to you instead.

Each task is automatically assigned to the directory it was created in and you can easily retrieve tasks under a directory.



It is easy to explore all capabilities of tasks3 by running tasks3 --help. Each command also has its own help page which can be accessed by running:

$ tasks3 <command> --help

Create Tasks

Easily create tasks from the commandline and delegate them to folders.

Create a task in a specific folder with default settings.

$ tasks3 add --title "Think of a cool name" \
    --folder "~/Documents/story" \
Added Task:
[e1c100] Think of a cool name (⏰⏰    ) (🚨🚨  )
  [path: ~/Documents/story]

Create a task in a current folder with custom settings and description.

$ tasks3 add --title "Try new model" \
    --urgency 4 --importance 3 \
    --description "Try:\n - model with 3 layers.\n - model with 4 layers." \
Added Task:
[a0a5f4] Try new model (⏰⏰⏰⏰) (🚨🚨🚨 )
     - model with 3 layers.
     - model with 4 layers.

Edit Existing Tasks

You can edit existing tasks with the tasks3 edit command.

For example: You can use edit to update the urgency of a task.

$ tasks3 edit --urgency 4 e1c100
Updated Task:
[e1c100] Think of a cool name (⏰⏰⏰⏰) (🚨🚨  )
  [path: ~/Documents/story]

Search Tasks

You can search for tasks using various filters.

You can search for tasks with a specific importance value.

$ tasks3 search --importance 2
[4a14d0] What is right here and now
[f79155] Think of a cool name [path: /home/<user>/Documents/project]
[2ce91b] See home [path: /home]

You can restrict search to a folder and its sub-directories.

$ tasks3 search --folder ~/Documents/project --output-format yaml
title: Think of a Cool name
urgency: 2
importance: 2
tags: null
folder: /home/<user>/Documents/project

You can also search for sub-strings in task title or description. It is also possible to restrict the search to tasks that have a specific set of tags. Run tasks3 search --help to get see a full list off options.

Show Tasks

You can show all tasks under current directory.

$ tasks3 show
[a0a5f4] Try new model (⏰⏰⏰⏰) (🚨🚨🚨 )
     model with 3 layers.
     model with 4 layers.
[4a14d0] What is right here and now (⏰⏰    ) (🚨🚨  )

You can also show a particular task by specifying its id.

$ tasks3 show 1d8a9a
[1d8a9a] Give a Title to this Task. (⏰⏰    ) (🚨🚨🚨🚨)
  (Hello tasks3)
    Task with

If you prefer to see the task in a different format, you can use the --output-format option.

$ tasks3 show --output-format json 1d8a9a
  "id": "1d8a9a",
  "title": "Give a Title to this Task.",
  "urgency": 2,
  "importance": 4,
  "tags": [
    "Hello tasks3"
  "folder": "/home/<user>/Documents/tasks3",
  "description": "Task with \nmulti-line \ndesc"

Complete Tasks

You can use the tasks3 mark <task_id> or tasks3 edit --done <task_id> command to mark a task as completed.

$ tasks3 mark 2e0b84
[2e0b84] A̶d̶d̶i̶n̶g̶ ̶s̶u̶p̶p̶o̶r̶t̶ ̶f̶o̶r̶ ̶t̶a̶s̶k̶ ̶c̶o̶m̶p̶l̶e̶t̶i̶o̶n̶ (⏰⏰    ) (🚨🚨  )

Delete Tasks

You can use the tasks3 delete <task_id> command to delete a task.


Deleting is a destructive action, prefer to mark the task as complete to hide it.

$ tasks3 remove --yes 2e0b84
Removed Task: [2e0b84] Adding support for task deletion (⏰⏰    ) (🚨🚨  )

Shell Integration

tasks3 supports shell integration for bash, zsh, and fish; tasks3 will automatically run tasks3 show -o oneline when you cd into a directory to show the tasks in that directory.

You can setup shell integration by adding the following command to your .rc file.

eval "$(tasks3 shell $(basename $SHELL))"


Pull requests to support additional shells are greatly appreciated. Please see Contributing page for information on how to contribute.

This package was created with Cookiecutter and the audreyr/cookiecutter-pypackage project template.

Indices and tables