Todoist CLI (with Interactive TUI Mode)

A fast, terminal-based task manager that syncs with your Todoist account. Manage your tasks efficiently without leaving the command line.

(This is a WIP, but it works. Feel free to contribute!)

Features

• 📝 Create, edit, and delete tasks
• ✅ Mark tasks as complete
• 🔄 Sync with Todoist API
• 💾 Local SQLite cache for offline access
• ⌨️ Vim-style keyboard shortcuts
• 🎨 Clean terminal UI powered by Ratatui

Prerequisites

• Rust 1.90.0 or later
• A Todoist account
• Your Todoist API token

Getting Your Todoist API Token

To use this application, you'll need a Todoist API token:

1. Visit the Todoist Developer Settings

   • Go to Todoist Integrations Settings
   • Or navigate manually: Todoist → Settings → Integrations → Developer

2. Find Your API Token

   • Scroll to the "API token" section
   • Your token will be displayed (it looks like a long string of letters and numbers)

3. Copy Your Token

   • Click the "Copy API token" button or select and copy the token manually
   • Keep this token secure - it provides full access to your Todoist data

For more information about the Todoist API, visit the official API documentation.

Installation

1. Clone the repository:

git clone https://github.com/yourusername/todoist-cli.git
   cd todoist-cli

2. Build the project:

cargo build --release

3. Set up your API token:

   Export your Todoist API token as an environment variable:

   Linux/macOS:

export TODOIST_TOKEN="your_api_token_here"

Windows (PowerShell):

$env:TODOIST_TOKEN="your_api_token_here"

Windows (Command Prompt):

set TODOIST_TOKEN=your_api_token_here

Tip: To make this permanent, add the export command to your shell's configuration file (~/.bashrc, ~/.zshrc, etc.) or use Windows environment variable settings.

Usage

Interactive TUI Mode

Run the application without arguments to launch the interactive terminal interface:

cargo run

Or using the compiled binary:

./target/release/todoist-cli

Keyboard Shortcuts

Normal Mode:

• j / ↓ - Move down
• k / ↑ - Move up
• a - Add new task
• i - Edit selected task
• d - Delete selected task
• t - Toggle task completion (mark as done)
• q - Quit application

Insert Mode (Add/Edit):

• Type to enter task title
• Enter - Save task
• Esc - Cancel and return to normal mode
• Backspace - Delete character

Command Line Mode

You can also use the CLI directly for quick operations:

Add a task:

cargo run -- add "Buy groceries"

Update a task:

cargo run -- update 1 "Buy groceries and cook dinner" true

Delete a task:

cargo run -- delete 1

How It Works

1. Sync on Startup: The app fetches your tasks from Todoist when launched
2. Local Cache: Tasks are cached in a local SQLite database (tasks.db)
3. Real-time Updates: All changes are immediately synced with Todoist
4. Offline Support: View cached tasks even without internet connection

Project Structure

todoist-cli/
├── src/
│   ├── api/          # Todoist API client
│   ├── cli/          # Command-line interface
│   ├── controller/   # Application state management
│   ├── db/           # SQLite cache
│   ├── models/       # Data structures
│   ├── utils/        # Helper functions
│   └── main.rs       # Entry point
├── Cargo.toml
└── README.md

Troubleshooting

"TODOIST_TOKEN env var required" error:

• Make sure you've set the TODOIST_TOKEN environment variable
• Verify the token is correct by checking your Todoist settings

Tasks not syncing:

• Check your internet connection
• Verify your API token is still valid
• Check the Todoist API status page

Build errors:

• Ensure you're using Rust 1.90.0 or later: rustc --version
• Try cleaning the build: cargo clean && cargo build

License

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

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Acknowledgments

• Built with Ratatui for the terminal UI
• Uses the Todoist REST API v1
• Inspired by the need for a fast, keyboard-driven task manager

Not associated with Todoist in any way.