tickit 0.3.0 - Docs.rs

📖 Table of Contents

✨ Features
🚀 Quick Start
💻 CLI Commands
⌨️ Keybindings
🎨 Themes
📤 Export Formats
☁️ Sync (Optional)
🏗️ Architecture
🔧 Building from Source
🤝 Contributing
📄 License

✨ Features

📋 Task Management

Create, edit, and complete tasks with titles, descriptions, URLs, and priority levels.

📁 Lists

Organize tasks into lists with custom icons. Default Inbox for quick capture.

🏷️ Tags

Add colorful tags for flexible categorization and filtering.

🖥️ Beautiful TUI

A gorgeous terminal interface with vim-style navigation and real-time updates.

⌨️ Full CLI

Script your task management with powerful command-line tools.

📤 Export Anywhere

Export to JSON, todo.txt, Markdown, or CSV formats.

Feature Highlights

Feature	Description
⚡ Priority Levels	Low, Medium, High, Urgent
🔗 Task URLs	Attach links and open them with `o`
🎨 15 Built-in Themes	From Dracula to Cyberpunk
💾 SQLite Storage	Fast, reliable, self-contained
🔍 Filter & Search	By list, tag, or completion status
✅ Toggle Completed	Show/hide completed tasks
📅 Due Dates	Set deadlines for your tasks
🔄 Auto-Update	Check for updates from TUI or CLI
☁️ Optional Sync	Self-hosted sync server for multiple devices

🚀 Quick Start

Installation

From Source

git clone https://github.com/ricardodantas/tickit
cd tickit
cargo install --path .

From crates.io (coming soon)

cargo install tickit

First Run

Simply launch the TUI:

tickit

Your tasks are stored in SQLite at ~/.config/tickit/tickit.sqlite.

💻 CLI Commands

Tickit provides a full CLI for scripting and quick actions.

Adding Tasks

# Simple task
tickit add "Buy groceries"

# With priority and list
tickit add "Review PR" --priority high --list Work

# With URL and tags
tickit add "Read article" --url "https://example.com" --tags reading,tech

# With description
tickit add "Write report" --description "Q4 summary for the team"

Listing Tasks

# Show incomplete tasks
tickit list

# Include completed tasks
tickit list --all

# Filter by list
tickit list --list Work

# Filter by tag
tickit list --tag urgent

# Output as JSON
tickit list --json

Completing Tasks

# Mark as complete (partial match supported)
tickit done "Buy groceries"

# Mark as incomplete
tickit undo "Buy groceries"

Deleting Tasks

# Delete with confirmation
tickit delete "Old task"

# Skip confirmation
tickit delete "Old task" --force

# Short alias
tickit rm "Old task" -f

Managing Lists

# List all lists
tickit lists

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

# Delete a list
tickit lists delete "Old List"

Managing Tags

# List all tags
tickit tags

# Add a new tag
tickit tags add "urgent" --color "#ff0000"

# Delete a tag
tickit tags delete "old-tag"

Exporting Tasks

# Export to JSON (default)
tickit export --output tasks.json

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

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

# Export specific list to CSV
tickit export --format csv --list Work --output work.csv

Updating Tickit

# Check for updates and install if available
tickit update

The update command automatically detects whether you installed via Cargo or Homebrew and uses the appropriate update method.

⌨️ Keybindings

Global

Key	Action
`Tab`	Next view
`Shift+Tab`	Previous view
`1` `2` `3`	Jump to view (Tasks, Lists, Tags)
`t`	Open theme picker
`A`	About Tickit
`?` / `F1`	Show help
`Ctrl+s`	Sync with server (if configured)
`q`	Quit
`Ctrl+c` / `Ctrl+q`	Force quit

Navigation

Key	Action
`↑` / `k`	Move up
`↓` / `j`	Move down
`←` / `h`	Focus sidebar
`→` / `l`	Focus main
`g` / `Home`	Go to first item
`G` / `End`	Go to last item

Tasks View

Key	Action
`Enter` / `Space`	Toggle task complete
`n`	Create new task
`e`	Edit selected task
`d` / `Delete`	Delete selected task
`p`	Cycle priority
`o`	Open task URL
`c`	Toggle show completed
`r`	Refresh

Lists/Tags View

Key	Action
`n`	Create new item
`e`	Edit selected item
`d` / `Delete`	Delete selected item

Task Editor

Key	Action
`Tab`	Next field
`Shift+Tab`	Previous field
`Enter`	Save task
`Esc`	Cancel
`Space`	Toggle tag (in Tags field)
`j` / `k`	Navigate options

🎨 Themes

Tickit includes 15 beautiful themes based on popular terminal and editor color schemes.

Press t in the TUI to open the theme picker with live preview.

Available Themes

Theme	Description
🦇 Dracula	Dark purple aesthetic (default)
🌙 One Dark Pro	Atom's iconic dark theme
❄️ Nord	Arctic, bluish color palette
🐱 Catppuccin Mocha	Warm pastel dark theme
☕ Catppuccin Latte	Warm pastel light theme
🎸 Gruvbox Dark	Retro groove colors
📜 Gruvbox Light	Retro groove, light variant
🌃 Tokyo Night	Futuristic dark blue
🌅 Solarized Dark	Precision colors, dark
🌞 Solarized Light	Precision colors, light
🎨 Monokai Pro	Classic syntax highlighting
🌹 Rosé Pine	All natural pine with soho vibes
🌊 Kanagawa	Inspired by Katsushika Hokusai
🌲 Everforest	Comfortable green forest theme
🌆 Cyberpunk	Neon-soaked futuristic theme

📤 Export Formats

JSON

Full data export with all fields — perfect for backups or integrations.

tickit export --format json --output tasks.json

{
  "tasks": [
    {
      "id": "...",
      "title": "Buy groceries",
      "priority": "high",
      "completed": false,
      "list": "Shopping",
      "tags": ["errands"]
    }
  ]
}

todo.txt

Compatible with the todo.txt format:

(A) 2024-01-01 Task title +Project @context due:2024-01-15

tickit export --format todotxt

Markdown

Human-readable format with checkboxes:

## 📥 Inbox
- [ ] 🔴 Urgent task
- [x] Completed task

## 📋 Work
- [ ] 🟡 Review PR

tickit export --format markdown

CSV

Spreadsheet-compatible format for Excel, Google Sheets, etc.

tickit export --format csv --output tasks.csv

🏗️ Architecture

Tickit is a single binary with both CLI and TUI modes.

┌─────────────────────────────────────────────────────────────┐
│                         User                                │
└─────────────────────────────────────────────────────────────┘
                              │
              ┌───────────────┴───────────────┐
              ▼                               ▼
┌─────────────────────────┐     ┌─────────────────────────────┐
│      tickit (TUI)       │     │      tickit <cmd> (CLI)     │
│  • Browse tasks         │     │  • Add tasks                │
│  • Manage lists/tags    │     │  • List/filter tasks        │
│  • Change themes        │     │  • Complete/delete          │
│  • Visual editing       │     │  • Export data              │
└─────────────────────────┘     └─────────────────────────────┘
              │                               │
              └───────────────┬───────────────┘
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                      SQLite Database                        │
│                 ~/.config/tickit/tickit.sqlite              │
└─────────────────────────────────────────────────────────────┘

Data Model

┌──────────────────┐     ┌──────────────────┐
│      Lists       │     │       Tags       │
│  • id            │     │  • id            │
│  • name          │     │  • name          │
│  • icon          │     │  • color         │
│  • is_inbox      │     └──────────────────┘
└──────────────────┘              │
         │                        │
         │ 1:N                    │ M:N
         ▼                        ▼
┌─────────────────────────────────────────────────────────────┐
│                         Tasks                               │
│  • id, title, description, url                              │
│  • priority (Low, Medium, High, Urgent)                     │
│  • completed, completed_at                                  │
│  • list_id, tag_ids[]                                       │
│  • due_date, created_at, updated_at                         │
└─────────────────────────────────────────────────────────────┘

File Locations

File	Path	Purpose
Database	`~/.config/tickit/tickit.sqlite`	Tasks, lists, tags
Config	`~/.config/tickit/config.toml`	Theme and settings
Device ID	`~/.config/tickit/.device_id`	Unique device identifier for sync

☁️ Sync (Optional)

Tickit can sync your tasks across multiple devices using a self-hosted sync server.

Sync is completely optional. Tickit works fully offline by default.

Setting Up Sync

Deploy tickit-sync server — see github.com/ricardodantas/tickit-sync
Generate an API token:
```
tickit-sync token --name "my-laptop"
```

Configure Tickit client (~/.config/tickit/config.toml):

[sync]
enabled = true
server = "https://your-server.com"
token = "your-generated-token"
interval_secs = 300  # auto-sync every 5 minutes

Manual sync: Press Ctrl+S in the TUI

Sync Features

Self-hosted: Run on your own server, keep your data private
Multi-device: Sync between desktop, laptop, and (future) mobile
Conflict resolution: Last-write-wins with conflict detection
Offline-first: Changes sync when connection is available

🔧 Building from Source

Requirements

Rust 1.93+ (uses Edition 2024 features)
Linux, macOS, or Windows

Build

# Clone the repository
git clone https://github.com/ricardodantas/tickit
cd tickit

# Build release binary
cargo build --release

# The binary will be at:
# - target/release/tickit

# Or install directly
cargo install --path .

Development

# Run TUI in development
cargo run

# Run CLI commands
cargo run -- add "Test task"
cargo run -- list

# Run tests
cargo test

# Run linter
cargo clippy

# Format code
cargo fmt

🤝 Contributing

Contributions are welcome!

Quick Start for Contributors

Fork the repository
Create a feature branch: git checkout -b feature/amazing-feature
Make your changes
Run tests: cargo test
Run clippy: cargo clippy
Format: cargo fmt
Commit: git commit -m "Add amazing feature"
Push: git push origin feature/amazing-feature
Open a Pull Request

Project Structure

tickit/
├── src/
│   ├── main.rs          # CLI entry point
│   ├── lib.rs           # Library root
│   ├── app/             # TUI application
│   │   ├── mod.rs       # App initialization
│   │   ├── events.rs    # Key event handling
│   │   ├── state.rs     # Application state
│   │   └── ui.rs        # UI rendering
│   ├── config.rs        # Configuration loading
│   ├── db.rs            # SQLite operations
│   ├── export.rs        # Export formats
│   ├── models.rs        # Data models
│   └── theme.rs         # Color themes
├── screenshots/         # Screenshots for docs
├── scripts/             # Helper scripts
└── tests/               # Integration tests

📄 License

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