tickli

Tickli

A beautiful command line interface for TickTick task management, built with Charm.

Installation

go install github.com/botre/tickli@latest

Quick Start

1. Create a TickTick App

1. Go to the TickTick Developer Portal
2. Create a new app
3. Set the OAuth redirect URL to http://localhost:8080
4. Note your Client ID and Client Secret

2. Set Up and Use

# Initialize and authenticate with TickTick
tickli init

# List available projects
tickli project list

# Switch to a project
tickli project use

# Create a task
tickli task create -t "Finish documentation"

# Create a task interactively
tickli task create -i

# See what's due today
tickli today

# Complete a task
tickli task complete <task-id>

Commands

General

Smart Views

Tasks

Single-task commands (show, update, delete, complete, uncomplete, move) only need a task ID — they search all projects automatically. The --project/-P flag is only needed for list and create.

Projects

Global Flags

Interactive Mode

List commands (today, task list, project list, project use) open a table picker when running in a terminal. Typing filters results immediately (fzf-style), ↑↓ to navigate, Enter to select, Esc to clear filter or cancel. The task picker includes a preview pane that shows details of the selected task.

Commands that support --interactive (-i) use multi-step form wizards:

tickli task create -i      # project → title → content → priority → date → tags
tickli task update <id> -i
tickli project create -i   # name → color → view mode → type

The task creation wizard includes a project selector with type-to-filter and inline "+ Create new project", a tag multi-select from existing tags across all projects, and an inline input for new tags.

Destructive operations (delete, reset) use styled confirmation prompts.

Scripting

When piped or redirected, list commands automatically output tab-separated columns instead of opening a picker:

# Create a task and capture its ID
TASK_ID=$(tickli task create -t "Review PR" -q)

# Complete it
tickli task complete "$TASK_ID"

# Get today's tasks as JSON
tickli today --json

# Count overdue high priority tasks
tickli today -p high -q | wc -l

# Extract just titles
tickli today | cut -f3

# Duration field in JSON
tickli task show <task-id> --json | jq .duration

Configuration

Configuration is stored at ~/.config/tickli/config.yaml (XDG).

Set the default project with tickli project use.

Shell Completions

# Bash
tickli completion bash > /etc/bash_completion.d/tickli

# Zsh
tickli completion zsh > "${fpath[1]}/_tickli"

# Fish
tickli completion fish > ~/.config/fish/completions/tickli.fish

Exit Codes

Design Philosophy

Tickli serves two audiences equally: humans at a terminal and scripts/agents driving it programmatically.

Graceful degradation. TTY gets interactive pickers; piped output gets tab-separated columns. No flag needed — inferred from context.

Consistent JSON. Every mutating command returns the full object in --json mode. Computed fields like duration are included.

Unsurprising flags. Each flag name has one meaning across the entire CLI. Short flags are never overloaded within a command.

Flexible input, strict output. Dates accept plain dates, ISO 8601, natural language. Output uses a single canonical format.

Minimal context. Single-entity commands only need an ID. --project is only required where scope is ambiguous (list, create). Smart views need no arguments.

Three-tier output. simple (human), json (machine), quiet (IDs). --json and --quiet override per-command -o.

Stdout is data, stderr is diagnostics. Piped data stays clean.

Non-blocking. Without a TTY, commands never block for input. Every promptable value has a flag.

One theme, everywhere. A single Theme struct styles everything — pickers, forms, detail views, status messages.