# Citrine

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

## Install

Download a binary from [releases](https://github.com/syntaxbullet/citrine/releases) or build from source:

```bash
cargo install --path .
```

## Quick Start

```bash
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 |