Terminalist - Todoist Terminal Client

📖 Documentation: Configuration | Keyboard Shortcuts | Development | Architecture

A terminal application for interacting with Todoist, built in Rust with a modern TUI interface.

Features

• Interactive TUI Interface - Beautiful terminal user interface with ratatui
• Local Data Caching - Fast, responsive UI backed by a local SQLite cache that survives restarts
• Smart Sync - Automatic sync on startup, on a configurable interval, and manual refresh with 'r'
• Project Management - Browse projects with hierarchical display
• Task Management - View, navigate, complete, and create tasks
• Task Search - Fast database-powered search across all tasks with '/' shortcut
• Keyboard & Mouse Navigation - Efficient keyboard operation with mouse support
• Real-time Updates - Create, complete, and delete tasks/projects
• Label Support - View task labels with colored badges
• Responsive Layout - Adapts to terminal size with smart scaling
• Help System - Built-in help panel with keyboard shortcuts
• Configuration File - Customizable settings via TOML configuration

Installation

Option 1: Install from Homebrew (macOS & Linux)

brew tap romaintb/terminalist
brew install terminalist

Option 2: Install from AUR (Arch Linux)

yay -S terminalist # Or any other AUR helper (eg: paru)

Option 3: Install from Crates.io

cargo install terminalist

Option 4: Build from Source

# Clone the repository
git clone https://github.com/romaintb/terminalist.git; cd terminalist
cargo build --release # Build the project
cargo run --release # Run the application

The binary will be available at target/release/terminalist after building.

Help Wanted: Package Maintainers

We support Homebrew for installation! For other distributions (Debian/Ubuntu, Fedora, NixOS, etc.), we're looking for help packaging Terminalist. If you're interested in maintaining a package, please open an issue or submit a PR!

Setup

1. Get your Todoist API Token

1. Go to Todoist Developer Settings
2. Copy your API token

2. Set Environment Variable

export TODOIST_API_TOKEN=your_token_here

3. (Optional) Generate Configuration File

# Generate a default config file with all available options
terminalist --generate-config

This creates a config file at ~/.config/terminalist/config.toml with customizable settings.

4. Run the Application

terminalist

Configuration

Terminalist supports customization via TOML configuration files.

# Generate a default config file with all available options
terminalist --generate-config

This creates a config file at ~/.config/terminalist/config.toml.

📖 See Configuration Guide for detailed configuration options.

Quick Start Controls

Essential keyboard shortcuts to get started:

Key	Action
j/k	Navigate tasks up/down
J/K	Navigate projects up/down
Space	Complete task
a	Create new task
/	Search tasks
b	Toggle sidebar
r	Sync with Todoist
?	Show help panel
q	Quit

📖 See Complete Keyboard Shortcuts for all available controls and interface details.

How It Works

Terminalist uses a smart sync mechanism:

• Fast Startup: Cached data from the last run is shown instantly while the sync runs
• Startup Sync: Syncs with Todoist once on startup, in the background
• Periodic Sync: Re-syncs every auto_sync_interval_minutes (5 by default, 0 disables it)
• Manual Sync: Press r to force refresh from Todoist
• Real-time Updates: Create, modify, and delete tasks/projects immediately

📖 See Architecture Guide for technical details.

Contributing

Contributions are welcome! See Development Guide for setup instructions and coding standards.

License

This project is open source. Feel free to modify and use as needed.