Notion Todo CLI

A command-line interface for managing todo items using Notion database integration. This Go-based CLI tool allows you to add and manage todo items directly from your terminal to your Notion workspace.

Installation

Linux (Recommended)

# Quick install script
curl -sSL https://raw.githubusercontent.com/caffeines/notion-todo/main/install.sh | bash

Or download manually from the releases page.

macOS (Homebrew)

# Add the tap
brew tap caffeines/tap

# Install notion-todo (available as 'todo' command)
brew install notion-todo

# Now you can use it with:
todo guide

Using Go Install

go install github.com/caffeines/notion-todo@latest

Download Binary

Download the latest release for your platform from the releases page.

Build from Source

1. Clone the repository:

   git clone https://github.com/caffeines/notion-todo.git
   cd notion-todo

2. Build the project:

   make build
   # or
   go build -o todo main.go

3. Move the binary to your PATH:

   sudo mv todo /usr/local/bin/

Quick Start

1. Build the project:

   make build
   # or
   go build -o todo main.go

2. Run the interactive setup guide:

   todo guide
   # Or use the short alias
   todo g

3. Configure the CLI:

   todo config
   # Or use the short alias
   todo c

4. Start adding todos:

   todo add "Buy groceries"
   # Or use the short alias
   todo a "Complete project" --date 25-06-2025

5. View and manage your todos:

   todo list
   # Or use short aliases
   todo l
   # or
   todo ls

That's it! The interactive guide will walk you through everything else.

Features

• 💡 Interactive Setup Guide - Step-by-step walkthrough for first-time users
• 🔧 Easy configuration setup with Notion API token and database ID
• ➕ Add todo items to your Notion database with optional due dates
• 📋 Interactive list view for managing todos with delete and status update capabilities
• ❌ Delete unwanted todo items directly from the CLI
• 📝 Simple and intuitive command-line interface with short aliases for faster usage
• 🔒 Secure credential storage
• 🎯 Direct integration with Notion API
• 📊 Status tracking and validation (Not started, In progress, Done)
• 📅 Due date support for better task management
• ⚡ Quick commands with short aliases (todo v, todo a, todo l, etc.)
• 🔄 Status normalization and validation to ensure data consistency

Prerequisites

• Go 1.23 or higher
• A Notion account with API access
• A Notion database set up for todo items

Configuration

Before using the CLI, you need to configure it with your Notion API credentials. You have two options:

Option 1: Interactive Setup Guide (Recommended)

Run the interactive setup guide for a step-by-step walkthrough:

todo guide

This interactive guide will walk you through:

• Setting up your todo database (with template option)
• Getting your database ID
• Creating a Notion integration
• Getting your API credentials
• Connecting the integration to your database
• Configuring the CLI
• Testing your setup

Navigation in the Guide:

• Next step: Enter, Space, n, l, or → (right arrow)
• Previous step: p, h, or ← (left arrow)
• Restart: r
• Quit: q or Ctrl+C

Option 2: Manual Configuration

If you prefer manual setup or already have your credentials:

todo config

This will prompt you to enter:

• Notion API Token: Your Notion integration token
• Database ID: The ID of your Notion database

Getting Notion Credentials

Quick Database Setup (Recommended)

Use the pre-configured template for the fastest setup:

1. Get the Template:

   • Go to Notion Todo Template
   • Click "Get template" and select your workspace
   • The template already has the correct database structure

2. Get Database ID:

   • Open your database in Notion
   • Copy the database ID from the URL: https://www.notion.so/{workspace}/{database_id}?v=...
   • The database ID is the string after the last / and before ?
   • Example: 217e31359630803999d6ecaabdf4e11f

Manual Database Setup

If you prefer to create the database manually:

Required Properties:

• Title (Title) - The main todo text
• Status (Select) - Todo completion status with options:
  • Todo (default)
  • In progress
  • Done
• Due Date (Date) - Optional due date for todos
• Tags (Multi-select) - Optional categorizing tags

Setup Instructions:

1. Create Integration:

   • Go to Notion Integrations
   • Click "New integration"
   • Name it "Todo CLI" or similar
   • Select your workspace and choose "Internal" type
   • Click "Save"

2. Grant Database Access:

   • In the integration configuration popup, click "Access" tab
   • Select "pages" to see your database
   • Select your todo database from the list
   • Click "Update Access"
   • Go back to "Configuration" tab

3. Copy Integration Token:

   • Click "Show" next to "Internal Integration Token"
   • Copy the token and keep it secure

Usage

Add a Todo Item

# Basic todo
todo add "Buy groceries"

# Todo with due date
todo add "Complete project documentation" --date 25-06-2025

# Todo with specific date format
todo add "Schedule dentist appointment" --date 2025-06-30

The todo items will be created in your Notion database with:

• Title: Your todo text
• Status: Set to "Todo" by default
• Due Date: Due date if specified

List and Manage Todos

# View all todos in an interactive interface
todo list

The list command provides an interactive interface where you can:

• View todos by status (Todo, In progress, Done)
• Navigate through your todos
• See due dates and completion status
• Delete unwanted todo items
• Update todo status
• Manage your todo items efficiently

Available Commands

• todo guide (or todo g) - Interactive setup guide for first-time users (recommended)
• todo config (or todo c) - Configure Notion API credentials manually
• todo add <todo-text> (or todo a) - Add a new todo item
• todo add <todo-text> --date YYYY-MM-DD - Add todo with due date
• todo list (or todo l, todo ls) - View and manage existing todos in interactive mode
• todo version (or todo v) - Show version information
• todo help - Show help information

Short Command Aliases

For faster usage, you can use these short aliases:

• todo v → todo version
• todo a → todo add
• todo l → todo list
• todo ls → todo list
• todo g → todo guide
• todo c → todo config

Command Examples

# First-time setup
todo guide
# Or use the short alias
todo g

# Add todos
todo add "Buy milk"
todo a "Finish presentation" --date 2025-06-25

# View and manage
todo list
# Or use short aliases
todo l
todo ls

# Check version
todo version
todo v

# Get help
todo help

Project Structure

├── cmd/                    # CLI commands
│   ├── add.go             # Add todo command
│   ├── config.go          # Configuration command
│   ├── guide.go           # Interactive setup guide command
│   ├── list.go            # List and manage todos command
│   ├── root.go            # Root command
│   ├── version.go         # Version command
│   ├── processors/        # Command processors
│   │   ├── add_processor.go
│   │   ├── guide_processor.go
│   │   ├── list_processor.go
│   │   ├── root_processor.go
│   │   └── version_processor.go
│   ├── steps/             # Guide step implementations
│   │   └── guide_steps.go
│   └── template/          # UI templates and styles
│       ├── guide_template.go
│       └── styles.go
├── consts/                # Application constants
│   ├── config.go          # Configuration constants
│   ├── notion.go          # Notion API constants
│   ├── status.go          # Status constants
│   └── version.go         # Version information
├── models/                # Data models
│   ├── config.go          # Configuration model
│   ├── createTodoPayload.go # Notion API payload
│   └── todoItem.go        # Todo item structure
├── service/               # Business logic services
│   ├── config/            # Configuration services
│   │   ├── credential.go
│   │   └── credentialImpl.go
│   ├── files/             # File handling services
│   │   ├── file.go
│   │   └── FileImpl.go
│   ├── notion/            # Notion API integration
│   │   ├── notion.go
│   │   └── notionImpl.go
│   └── utility/           # Utility services
│       ├── todo_utility.go
│       └── utility.go
└── main.go               # Application entry point

Configuration Storage

The application stores your configuration in a hidden directory:

• Path: ~/.notion-todo/config.json
• Contains encrypted credentials for secure storage

Troubleshooting

Common Issues

"Failed to create todo" or "Database not found"

• Make sure your integration is connected to the database (step 5 in the guide)
• Verify your Database ID is correct
• Check that your API token is valid

"Property not found" errors

• Ensure your database has the exact properties: "Title", "Status", "Due Date"
• Property names are case-sensitive
• The Status property must be of type "Select" with options: "Todo", "In progress", "Done"
• Consider using the template for correct setup

Configuration issues

• Run todo config to reconfigure your credentials
• Check if ~/.notion-todo/config.json exists and has valid JSON
• Re-run the setup guide: todo guide

Need help?

• Run todo guide for the interactive setup
• Use todo help for command information
• Check that your Notion integration has the correct permissions

Architecture

The project follows a clean architecture pattern with:

• Commands (cmd/): CLI command handlers using Cobra with dedicated processors
• Services (service/): Business logic organized by domain (config, files, notion, utility)
• Models (models/): Data structures for API communication
• Constants (consts/): Application-wide constants and configuration
• Processors (cmd/processors/): Command-specific business logic handlers

Key interfaces:

• service/notion/notion.go: Notion API operations
• service/config/credential.go: Credential management
• service/files/file.go: File operations

Development

Building

# Build the project
go build -o todo main.go

# Or use the Makefile
make build

Testing

go test ./...

Dependencies

• Cobra - CLI framework
• Bubble Tea - Terminal UI framework for interactive guide
• Lip Gloss - Style and layout for terminal interfaces
• PromptUI - Interactive prompts
• Spinner - Loading spinners for CLI operations

License

See LICENSE file for details.

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request