citrine/README.md

Citrine

Minimalist, plaintext, project-based todo CLI. Creates .citrine files in your project directory — human-readable, git-friendly, and AI-agent-parseable.

Install

Prebuilt binaries are in the dist/ directory, or build from source:

cargo install --path .

Quick Start

citrine init
citrine add "Implement caching layer"
citrine add "Fix mobile layout" --local
citrine list
citrine set a4f9 progress
citrine done a4f9
citrine rm a4f9

Commands

Command	Description
citrine init	Initialize citrine in the current directory
citrine add <description> [--local]	Add a new task (--local for .citrine.local)
citrine list [--status <s>] [--local]	List tasks, optionally filtered
citrine set <hash> <status>	Change task status
citrine done <hash>	Mark task as done (shorthand for set <hash> done)
citrine rm <hash>	Remove a task

Statuses: todo, progress, blocked, done

Hashes can be partial — a4 works if it's unambiguous.

File Format

## Backend
[a4f9] [ ] Implement caching layer @priority:high @backend
[b2e1] [>] Refactor auth module @assigned:cursor
[c3d8] [-] Deploy to staging @blocked:waiting-for-credentials
[f1a2] [x] Set up Docker config @completed:2025-02-14

## Frontend
[d4b3] [ ] Build settings page
[e5c2] [>] Fix mobile layout issues @priority:medium

Status Symbols

Symbol	Meaning
[ ]	Todo
[>]	In Progress
[-]	Blocked
[x]	Done

Metadata

Append @tag or @key:value to any task. Free-form, not validated. @completed:YYYY-MM-DD is auto-added when marking a task done.

Files

• .citrine — shared project tasks, commit to git
• .citrine.local — personal tasks, gitignored

Both share the same hash namespace. citrine list merges both by default.

Exit Codes

Code	Meaning
0	Success
1	Generic error
2	Invalid arguments
3	Not initialized