<div align="center">

# plane-cli-requiem

**A fast, composable CLI for [Plane.so](https://plane.so) project management.**

[![Crates.io](https://img.shields.io/crates/v/plane-cli-requiem.svg)](https://crates.io/crates/plane-cli-requiem)
[![Downloads](https://img.shields.io/crates/d/plane-cli-requiem.svg)](https://crates.io/crates/plane-cli-requiem)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Rust](https://img.shields.io/badge/rust-1.85%2B-orange.svg)](https://www.rust-lang.org/)
[![Windows](https://img.shields.io/badge/platform-windows%20%7C%20macos%20%7C%20linux-lightgrey.svg)]()
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)]()

</div>

---

Single binary, instant startup, piped output. The Plane API requires one HTTP call per operation; plane-cli-requiem batches common workflows into single commands.

## Install

### Cargo (all platforms)

```sh
cargo install plane-cli-requiem
```

### From source

```sh
git clone https://github.com/CheckPickerUpper/plane-cli-requiem.git
cd plane-cli-requiem
cargo install --path .
```

## Quick start

```sh
# Register your workspace with an API token
plane config --workspace myteam --token plane_api_your_key_here

# Set the default project for that workspace
plane config --project myapp

# List work items
plane ls

# See what's assigned to you
plane mine
```

## Commands

### Work items

| Command | What it does |
|---------|-------------|
| `plane ls` | List items; filters: `--state`, `--priority`, `--format json\|table\|csv` |
| `plane show <ID>` | Full detail view (e.g. `plane show NRO-123`) |
| `plane show project <slug>` | Project summary with state distribution |
| `plane create <title>` | Create with `--state`, `--priority`, `--ac "criterion"` |
| `plane update <ID>` | Batch-update fields |
| `plane delete <ID>` | Delete with confirmation (`--yes` to skip) |
| `plane done <ID>` | Transition to done; verifies acceptance criteria first |

### My assignments

| Command | What it does |
|---------|-------------|
| `plane mine` | All work items, modules, cycles assigned to you |
| `plane mine items` | Only your work items |
| `plane mine modules` | Only modules you lead or belong to |
| `plane mine cycles` | Only cycles you own |
| `plane mine items --state "in progress"` | Filter by state |
| `plane mine items --priority high` | Filter by priority |
| `plane mine items --module "Auth"` | Filter within a module |
| `plane mine items --cycle "Sprint 4"` | Filter within a cycle |

Filters combine: `plane mine items --state todo --module Backend`

### Cycles and modules

| Command | What it does |
|---------|-------------|
| `plane cycles` | List all cycles with date ranges |
| `plane cycles <name>` | List work items in a cycle |
| `plane modules` | List all modules with descriptions |
| `plane modules <name>` | List work items in a module |
| `plane show cycle <name>` | Cycle detail |
| `plane show module <name>` | Module detail |

### Acceptance criteria

| Command | What it does |
|---------|-------------|
| `plane ac <ID>` | Show AC with checkboxes |
| `plane ac <ID> check <index>` | Check off an AC item |
| `plane ac <ID> add "new criteria"` | Append AC |

### Navigation

| Command | What it does |
|---------|-------------|
| `plane open <ID>` | Open in browser (work item, project, cycle, module) |
| `plane start <ID>` | Create feature branch, transition to In Progress |
| `plane pr` | Open PR via `gh` with title/body prefilled from current work item |
| `plane me` | Current user, workspace, project, auth status |
| `plane dashboard` | Terminal overview with items by state, overdue counts, AC rates |

### Git-aware context

Commands infer the work item from your branch name when called without arguments:

```sh
git checkout feat/NRO-123-add-auth

plane show    # shows NRO-123
plane done    # marks NRO-123 done
plane ac      # shows NRO-123 acceptance criteria
plane id      # prints NRO-123 (for scripts)
plane url     # prints the Plane web URL
```

### Config

| Command | What it does |
|---------|-------------|
| `plane config` | Show current config |
| `plane config --workspace <slug> --token <key>` | Register a workspace |
| `plane config --project <slug>` | Set default project for the active workspace |
| `plane workspace <slug>` | Switch active workspace |

## Configuration

Lives at `~/.plane-cli-requiem/config.toml`. Each workspace owns its own default project; switching workspaces picks up the right project automatically.

```toml
active_workspace = "myteam"

[workspaces.myteam]
api_key = "plane_api_..."
default_project = "myapp"

[workspaces.other]
api_key = "plane_api_..."
default_project = "dashboard"
```

### Per-repo overrides

Drop a `.plane.toml` in any repo root to override the global config:

```toml
workspace = "myteam"
project = "myapp"
```

### Environment variables

| Variable | What it does |
|----------|-------------|
| `PLANE_API_KEY` | Overrides the workspace API token from config |

## Output formats

All list commands support `--format` with TTY auto-detection:

- **table** (default in terminals) — colored, aligned columns
- **json** (default when piped) — for `jq` and scripts
- **csv** — spreadsheet import

```sh
plane ls                                              # colored table
plane ls | jq '.[] | select(.priority == "Urgent")'   # auto-switches to JSON
plane ls --format csv > items.csv                     # explicit CSV
```

## Architecture

Rust; single binary, no runtime dependencies. HTTP via reqwest with token auth against the Plane REST API. Config is TOML; terminal output uses comfy-table and colored.

All nullable API fields are modeled as named two-variant enums rather than `Option<T>` — the type system enforces domain correctness at the deserialization boundary.

## Roadmap

- [x] Work item CRUD (ls, show, create, update, delete, done)
- [x] Acceptance criteria (view, check, append)
- [x] Cycles and modules (list, show items)
- [x] `plane mine` with section filtering and work item filters
- [x] Per-workspace project config (no global footgun)
- [x] Per-repo `.plane.toml` overrides
- [x] Git-aware context (branch → work item inference)
- [x] `plane start` / `plane pr` workflow
- [ ] `plane bulk` state transitions
- [ ] `plane mv` between cycles/modules
- [ ] Shell completions
- [ ] Publish to crates.io

## Contributing

PRs welcome. Open an issue first for anything bigger than a typo fix.

## License

[MIT](LICENSE)
