ticktickrs

A command-line interface for TickTick app. tickrs provides two modes, normal CLI output and structured JSON output for automation and scripting.

Inspired by tickli, but minus the interactive shell and some extra features.

Features

• Full CRUD operations for projects, tasks, and subtasks
• JSON output mode (--json) for AI agents and automation
• Natural language date parsing ("tomorrow", "in 3 days", "next week")
• Quiet mode (--quiet) for scripts that only need exit codes
• OAuth 2.0 authentication with secure token storage
• Default project context to reduce repetitive flags

Installation

From Releases

Download the latest release for your platform from GitHub Releases.

# macOS (Apple Silicon)
curl -LO https://github.com/SpaceK33z/tickrs/releases/latest/download/tickrs-aarch64-apple-darwin.tar.gz
tar -xzf tickrs-aarch64-apple-darwin.tar.gz
sudo mv tickrs /usr/local/bin/

# macOS (Intel)
curl -LO https://github.com/SpaceK33z/tickrs/releases/latest/download/tickrs-x86_64-apple-darwin.tar.gz
tar -xzf tickrs-x86_64-apple-darwin.tar.gz
sudo mv tickrs /usr/local/bin/

# Linux
curl -LO https://github.com/SpaceK33z/tickrs/releases/latest/download/tickrs-x86_64-unknown-linux-gnu.tar.gz
tar -xzf tickrs-x86_64-unknown-linux-gnu.tar.gz
sudo mv tickrs /usr/local/bin/

With Cargo

cargo install tickrs

From Source

git clone https://github.com/SpaceK33z/tickrs.git
cd tickrs
cargo build --release
# Binary will be at ./target/release/tickrs

Quick Start

1. Set Up TickTick OAuth App

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

2. Configure Environment Variables

export TICKTICK_CLIENT_ID="your_client_id"
export TICKTICK_CLIENT_SECRET="your_client_secret"

3. Initialize Authentication

tickrs init

This opens your browser for TickTick authorization. After authorizing, the token is stored securely at ~/.local/share/tickrs/token.

4. Start Using tickrs

# List all projects
tickrs project list

# Set a default project
tickrs project use "Work"

# Create a task
tickrs task create --title "Review PR" --priority high --date "tomorrow"

# List tasks
tickrs task list

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

Command Reference

Global Options

Root Commands

tickrs init

Initialize OAuth authentication with TickTick. Opens browser for authorization.

tickrs reset [--force]

Clear configuration and stored token. Use --force to skip confirmation.

tickrs version

Display version information.

Project Commands

tickrs project list (alias: ls)

List all projects.

tickrs project list
tickrs project list --json

tickrs project show <id>

Show details of a specific project.

tickrs project show abc123
tickrs project show inbox

tickrs project use <name-or-id>

Set the default project for subsequent commands.

tickrs project use "Work"
tickrs project use abc123

tickrs project create

Create a new project.

tickrs project create --name "Side Project" --color "#00AAFF"

tickrs project update <id>

Update an existing project.

tickrs project update abc123 --name "Archived Project" --closed

tickrs project delete <id> [--force]

Delete a project. Use --force to skip confirmation.

tickrs project delete abc123 --force

Task Commands

tickrs task list (alias: ls)

List tasks in a project.

tickrs task list
tickrs task list --priority high --status incomplete
tickrs task list --project-id inbox --json

tickrs task show <id>

Show details of a specific task.

tickrs task show task123
tickrs task show task123 --project-id abc123

tickrs task create (alias: add)

Create a new task.

# Basic task
tickrs task create --title "Buy groceries"

# Task with priority and due date
tickrs task create --title "Submit report" --priority high --date "tomorrow at 5pm"

# Task with tags
tickrs task create --title "Code review" --tags "work,urgent" --date "in 2 days"

# Task in specific project
tickrs task create --title "Research" --project-id abc123 --content "Look into new frameworks"

# Task with subtasks
tickrs task create --title "Pack for trip" --items "Passport,Clothes,Toiletries,Chargers"

tickrs task update <id>

Update an existing task.

tickrs task update task123 --title "Updated title" --priority medium
tickrs task update task123 --due "2026-01-20T14:00:00Z"
tickrs task update task123 --items "Step 1,Step 2,Step 3"

tickrs task delete <id> [--force]

Delete a task.

tickrs task delete task123 --force

tickrs task complete <id>

Mark a task as complete.

tickrs task complete task123

tickrs task uncomplete <id>

Mark a task as incomplete.

tickrs task uncomplete task123

Subtask Commands

tickrs subtask list <task-id> (alias: ls)

List subtasks (checklist items) for a task.

tickrs subtask list task123
tickrs subtask list task123 --json

Note: To create or modify subtasks, use the --items flag on tickrs task create or tickrs task update. For example: tickrs task create --title "My task" --items "Step 1,Step 2,Step 3"

JSON Output

All commands support --json for structured output suitable for AI agents and scripts.

Success Response

{
  "success": true,
  "data": {
    "tasks": [
      {
        "id": "task123",
        "projectId": "abc123",
        "title": "Complete report",
        "status": 0,
        "priority": 3,
        "dueDate": "2026-01-15T14:00:00Z",
        "tags": ["urgent", "work"]
      }
    ],
    "count": 1
  }
}

Error Response

{
  "success": false,
  "error": {
    "code": "AUTH_REQUIRED",
    "message": "Authentication required. Run 'tickrs init' to authenticate."
  }
}

Error Codes

Natural Language Dates

The --date flag accepts natural language expressions:

ISO 8601 dates are also supported: 2026-01-15T14:00:00Z

Configuration

Config File

Location: ~/.config/tickrs/config.toml

# Default project for commands without --project-id
default_project_id = "abc123"

# Default color for new projects
default_project_color = "#FF1111"

Token Storage

Location: ~/.local/share/tickrs/token

The OAuth access token is stored with 0600 permissions (owner read/write only).

Environment Variables

Token via Environment Variable

For automation (e.g. in a Docker container or anywhere the CLI can't open a browser), provide the access token directly:

export TICKTICK_TOKEN="your_access_token_here"

When TICKTICK_TOKEN is set, using the init command is not required

Getting a token for CI/CD:

1. Run tickrs init locally to complete OAuth flow
2. Copy the token from ~/.local/share/tickrs/token
3. Use e.g. export TICKTICK_TOKEN=[your-token]

Troubleshooting

"Authentication required" error

Run tickrs init to authenticate with TickTick.

"No project specified" error

Either:

1. Set a default project: tickrs project use "Project Name"
2. Specify project explicitly: tickrs task list --project-id abc123

OAuth flow fails to complete

1. Ensure TICKTICK_CLIENT_ID and TICKTICK_CLIENT_SECRET are set
2. Check that the redirect URI in your TickTick app is http://localhost:8080
3. Ensure port 8080 is not in use by another application

Token expired

Run tickrs init again to re-authenticate.

"Rate limited" error

TickTick API has rate limits. Wait a few minutes before retrying.

AI Agent Usage

tickrs is designed for AI agents and automation. Key features:

1. JSON output: Use --json for structured, parseable output
2. Exit codes: Check $? for success (0) or failure (non-zero)
3. Quiet mode: Use --quiet when you only need exit codes
4. No interactive prompts: All commands can run non-interactively with --force

Example automation script:

#!/bin/bash

# Create a task and capture the ID
result=$(tickrs task create --title "Automated task" --json)
task_id=$(echo "$result" | jq -r '.data.task.id')

if [ "$task_id" != "null" ]; then
    echo "Created task: $task_id"
else
    echo "Failed to create task"
    exit 1
fi

Development

# Build
cargo build

# Run tests
cargo test

# Run with verbose logging
RUST_LOG=debug cargo run -- project list

# Format code
cargo fmt

# Lint
cargo clippy

License

MIT