https://docs.rs/tickrs

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

Option	Description
--json	Output in JSON format for machine consumption
-q, --quiet	Suppress all output (useful for scripts that only need exit codes)

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.

Option	Description
-n, --name <NAME>	Project name (required)
-c, --color <COLOR>	Hex color code (e.g., #FF5733)
--view-mode <MODE>	View mode: list, kanban, timeline
--kind <KIND>	Project kind: task, note

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

tickrs project update <id>

Update an existing project.

Option	Description
-n, --name <NAME>	New project name
-c, --color <COLOR>	New hex color code
--closed	Archive the 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.

Option	Description
-p, --project-id <ID>	Project ID (uses default if not specified)
--priority <PRIORITY>	Filter by priority: none, low, medium, high
--tag <TAG>	Filter by tag
--status <STATUS>	Filter by status: complete, incomplete

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.

Option	Description
-t, --title <TITLE>	Task title (required)
-p, --project-id <ID>	Project ID (uses default if not specified)
-c, --content <CONTENT>	Task description
--priority <PRIORITY>	Priority: none, low, medium, high
--tags <TAGS>	Comma-separated tags
--items <ITEMS>	Comma-separated subtasks/checklist items
--date <DATE>	Natural language date (sets start and due)
--start <DATE>	Start date (ISO 8601)
--due <DATE>	Due date (ISO 8601)
--all-day	Mark as all-day task
--timezone <TZ>	Timezone

# 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

Code	Description
AUTH_REQUIRED	Not authenticated, run tickrs init
AUTH_EXPIRED	Token expired, run tickrs init again
NOT_FOUND	Resource not found
INVALID_REQUEST	Invalid request parameters
RATE_LIMITED	API rate limit exceeded
SERVER_ERROR	TickTick server error
NETWORK_ERROR	Network connection error
NO_PROJECT	No project specified and no default set

Natural Language Dates

The --date flag accepts natural language expressions:

Expression	Result
today	Today at current time
tomorrow	Tomorrow at current time
yesterday	Yesterday at current time
next week	7 days from now
next month	1 month from now
in 3 days	3 days from now
in 2 hours	2 hours from now
in 30 minutes	30 minutes from now

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

Variable	Description
TICKTICK_CLIENT_ID	OAuth Client ID (required for init)
TICKTICK_CLIENT_SECRET	OAuth Client Secret (required for init)
TICKTICK_TOKEN	Access token (bypasses init, for automation)
RUST_LOG	Logging level (e.g., info, debug)

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