Skip to content

Latest commit

 

History

History
156 lines (102 loc) · 4.06 KB

README.md

File metadata and controls

156 lines (102 loc) · 4.06 KB

tqu – A Minimal CLI for Queue-Based Task Tracking

tqu is a lightweight command-line tool designed for queue-based task tracking with minimal overhead. Instead of complicated features like priorities or due dates, tqu uses a simple push/pop workflow across one or multiple queues. Whether you're managing everyday chores, bills, or side projects, tqu keeps task tracking fast, intuitive, and distraction-free.

tqu demo

Highlights

  • Minimalist approach: Focuses solely on adding and removing tasks in a queue. No complicated features like priorities, due dates, or attachments.
  • Queue-Based: Default queue for simple use, but supports multiple queues for different contexts (e.g., “daily,” “bills,” “my_project”).
  • CLI-centric: Fast interaction entirely through the command line
  • Low Friction: Short commands with sensible defaults, and queues are auto-created without extra steps.

Installation

  1. Install (recommended via uv):

    uv tool install tqu

    or

    pipx install tqu

    or

    pip install --user tqu

  2. (Optional) By default, tqu stores its database at ~/.tqu.sqlite. You can customize the location by setting the TQU_DB_PATH environment variable:

    export TQU_DB_PATH="/path/to/your/custom/database.sqlite"

Usage

Below are the commands you can run with tqu. In all cases, if you omit the queue name, default is used.

Basic: Single Queue Mode

For simple task management, you can use the default queue without specifying a queue name:

  1. Add a task to the default queue:

    tqu add "Pay electricity bill"

  2. List tasks in the default queue:

    tqu list

    This shows active tasks along with their IDs, oldest added task first.

  3. Remove the most recent (last) task from the default queue:

    tqu pop

    or

    tqu poplast

    This prints the removed task.

  4. Remove the least recent (first) task from the default queue:

    tqu popfirst

    This prints the removed task.

  5. Delete a task by its unique integer ID (no queue needed):

    tqu delete <task_id>

  6. Delete the default queue (and all tasks in it):

    tqu delete

    This prints all removed tasks from that queue.

Advanced: Multiple Queue Mode

Organize tasks into separate queues for different contexts. For multiple queues, simply add <queue> as the last argument.

  1. Add a task to a specific queue:

    tqu add "Buy groceries" errands

    If the queue “errands” does not exist, tqu creates it automatically. Note that, queue name can not be only numeric.

  2. List tasks in a specific queue:

    tqu list errands

  3. Pop the most recent task from a specific queue:

    tqu pop errands

    (or “poplast”)

  4. Pop the least recent task from a specific queue:

    tqu popfirst errands

  5. Delete an entire queue (and all tasks in it):

    tqu delete errands

  6. Delete a single task by ID (no need for queue name):

    tqu delete <task_id>

  7. List all queues that have at least one active task:

    tqu

Everyday Use Cases

Here are some everyday scenarios in which tqu can keep you organized:

  1. Daily Planning: Keep track of things you need to do today or this month in queues like today, month, feb2025, or biils.
  2. Reimbursements: Keep track of reimbursements you need to file at the end of the month in a queue named reimbursements.
  3. Reading / Watch / Listen Lists: Keep track of books, papers, blogs, movies, podcasts, or music you want to consume in queues like books, papers, movies, podcasts, or music.
  4. Side Projects: Keep track of tasks for side projects in queues like project1, project2, or project3.
  5. Travel Planning: Keep track of things you need to do before your next trip in a queue named travel or taiwan-trip.

License

This project is licensed under the MIT License. See the LICENSE file for details.