Documentation

Everything you need to know about using Tickit to manage your tasks.

Installation

macOS

The fastest way to install on macOS — uses pre-built binaries:

Homebrew (Recommended) 
brew install ricardodantas/tap/tickit

Linux

Homebrew works on Linux too, or use Cargo:

Homebrew 
brew install ricardodantas/tap/tickit
Cargo 
cargo install tickit

Windows

Install via Cargo or download the pre-built binary:

Cargo 
cargo install tickit

Or download tickit-*-x86_64-pc-windows-msvc.zip from GitHub Releases.

From Source

Build from source 
git clone https://github.com/ricardodantas/tickit.git
cd tickit
cargo build --release

Requirements

  • Rust 1.93+ (only for Cargo/source installation)
  • macOS, Linux, or Windows

Quick Start

Get up and running in three simple steps:

1

Install Tickit

brew install ricardodantas/tap/tickit

Or use cargo install tickit

2

Add your first task

tickit add "Learn Tickit"
3

Launch the TUI

tickit

Use j/k to navigate, Space to toggle completion, ? for help

Architecture

Tickit is a single binary that provides both CLI and TUI interfaces:

CLI Mode

Quick task management from the command line. Add, list, complete, and export tasks without entering the TUI.

TUI Mode

Interactive terminal interface for managing tasks, lists, and tags with keyboard navigation and 15 beautiful themes.

Data Storage

File Path Purpose
Database ~/.config/tickit/tickit.sqlite Tasks, lists, tags storage
Config ~/.config/tickit/config.toml Theme and preferences

Add Tasks

Create tasks with various options:

Basic usage 
tickit add "Buy groceries"

Options

Flag Description Example
-d, --description Add a description -d "With milk and eggs"
-p, --priority Set priority (low, medium, high, urgent) -p high
--due Set due date (YYYY-MM-DD) --due 2026-02-15
-l, --list Assign to a list -l Work
-t, --tags Add tags (comma-separated) -t urgent,meeting
-u, --url Attach a URL -u "https://..."

Full Example

Task with all options 
tickit add "Submit quarterly report" \
  -d "Include sales figures" \
  -p urgent \
  -l Work \
  -t deadline,q1 \
  --due 2026-03-31

List Tasks

List incomplete tasks 
tickit list

Options

Flag Description
--all Include completed tasks
-l, --list <name> Filter by list
-t, --tag <name> Filter by tag
--json Output as JSON
Examples 
# List all tasks including completed
tickit list --all

# Filter by list
tickit list -l Work

# Filter by tag
tickit list -t urgent

# Output as JSON
tickit list --json

Complete Tasks

Mark task as complete 
tickit done <task-id>
💡 Tip: Use tickit list to see task IDs. The ID is shown at the beginning of each task line.

Manage Lists

List commands 
# Show all lists
tickit lists

# Create a new list
tickit lists add "Shopping" --icon "🛒"

# Delete a list
tickit lists delete <list-id>
⚠️ Note: The Inbox list is the default and cannot be deleted. Tasks without a list are assigned to Inbox.

Manage Tags

Tag commands 
# Show all tags
tickit tags

# Create a new tag with color
tickit tags add "urgent" --color "#ff5555"

# Delete a tag
tickit tags delete <tag-id>

Colors are specified as hex codes (e.g., #ff5555 for red).

Export

Export your tasks in various formats:

Export commands 
# Export to JSON
tickit export --format json > tasks.json

# Export to Markdown
tickit export --format markdown > tasks.md

# Export to CSV
tickit export --format csv > tasks.csv

# Export to todo.txt format
tickit export --format todotxt > todo.txt

Export Formats

Format Description Use Case
json Full structured export Backup, API integration
markdown Human-readable with checkboxes Documentation, sharing
csv Spreadsheet compatible Excel, Google Sheets
todotxt Standard todo.txt format Other todo apps

Update

Check for updates and install new versions directly from the command line:

Update command 
tickit update

The update command will:

  • Check crates.io for the latest version
  • Detect your installation method (Cargo or Homebrew)
  • Automatically run the appropriate update command
💡 TUI Auto-Update: Tickit also checks for updates automatically when you launch the TUI. If an update is available, you'll see a notification in the status bar. Press A to open the About dialog, then U to install the update.

TUI Overview

Launch the TUI with:

tickit
Tasks view
Tasks - Your main task list with priorities and due dates
Lists view
Lists - Organize tasks into custom lists
Tags view
Tags - Color-coded tags for flexible categorization

TUI Navigation

The TUI has three main views:

1️⃣ Tasks

Main task list. Use the sidebar to filter by list.

2️⃣ Lists

Create and manage your task lists with custom icons.

3️⃣ Tags

Create and manage color-coded tags.

Press the number keys (1, 2, 3) to switch between views.

Task Editor

Press n to create a new task or e to edit the selected task.

Task editor
The task editor with all available fields

Editor Fields

Field Description Input
Title Task name (required) Type text
Description Optional details Type text
Due Date When task is due Type YYYY-MM-DD
Priority Low, Medium, High, Urgent j/k to change
List Which list to assign j/k to change
Tags Tag selection Space to toggle, Enter on "+" to add new

Due Date Indicators

Tasks with due dates show visual indicators in the task list:

  • Red - Overdue (past due date)
  • Yellow - Due soon (within 2 days)
  • Gray - Future due date

Keyboard Shortcuts

Navigation

Key Action
j / ↓ Move down
k / ↑ Move up
g Go to first item
G Go to last item
Tab Switch focus (sidebar ↔ main)
1 Tasks view
2 Lists view
3 Tags view

Task Actions

Key Action
n New task/list/tag
e Edit selected
d Delete selected
Space Toggle task completion
o Open task URL in browser
Enter Select list in sidebar

UI Controls

Key Action
t Open theme picker
c Toggle showing completed tasks
? Show help
A About dialog
q Quit
Esc Cancel / Close dialog

Task Editor

Key Action
Tab Next field
Shift+Tab Previous field
Enter Save task
Esc Cancel

Config File

Tickit stores its configuration at:

~/.config/tickit/config.toml
config.toml 
# Theme name (see themes page for options)
theme = "dracula"

# Show completed tasks by default
show_completed = false

Themes

Tickit includes 15 beautiful built-in themes. Press t in the TUI to open the theme picker:

Theme picker
Theme picker with color previews

Available Themes

Dracula Nord Tokyo Night Catppuccin Mocha Catppuccin Latte Gruvbox Dark Gruvbox Light One Dark Solarized Dark Solarized Light Rose Pine Rose Pine Dawn Everforest Kanagawa Monokai

Browse All Themes →