scriptable • live • hierarchical

plnk

A deterministic, scriptable, hierarchy-aware CLI and SDK for Planka kanban project management. Plus a live terminal TUI explorer built on the same stack.

Note

Tested against self-hosted Planka only. The cloud-hosted service hasn't been exercised yet — your mileage may vary.

Two tools, one stack

Tool	What it's for
plnk	Scriptable CLI for automation, CI/CD, and AI workflows
plnk-tui	Live terminal explorer with real-time websocket sync

Both share config and auth — run plnk init once and both binaries are ready. Landing page at plattnum.github.io/planka-cli.

Install

Requires Rust 1.87+. Prebuilt binaries are on the roadmap.

# From a checkout
cargo install --path crates/plnk-cli --force
cargo install --path crates/plnk-tui --force

# Or from git
cargo install --git https://github.com/plattnum/planka-cli plnk-cli
cargo install --git https://github.com/plattnum/planka-cli plnk-tui

Quickstart

plnk init                 # interactive: server URL + API token
plnk auth status          # verify credentials resolve
plnk project list         # start driving Planka
plnk-tui                  # launch the TUI explorer

Walkthrough: docs/cli/examples.md.

plnk (CLI)

Shape: plnk <resource> <action> [target] [flags]. Design principles:

• Strict hierarchy — project → board → list → card → task/comment. All finds are scoped. No global flat queries.
• Typed exit codes — 0 success · 2 validation · 3 auth · 4 not-found · 5 server.
• Three outputs — table for humans, json for scripts, markdown for reports.
• Machine-readable help — plnk <cmd> --help --output json returns a stable schema agents can bind to before running.
• stdout is data, stderr is logs.

Reference docs, one per resource:

• Projects · Boards · Lists · Cards
• Tasks · Comments · Labels
• Attachments · Memberships · Users
• Authentication · Grammar reference · Transport policy
• Worked examples

plnk-tui

A terminal-native explorer for the same hierarchy. Single-board websocket subscription means edits from the browser appear in your terminal in near real time.

plnk-tui --server http://your-planka-host --username you
# prompts for password

Navigate projects → boards → lists → cards with ↑↓→Enter. Press L on any board to promote it to the live target. Edit titles inline with e or descriptions in $EDITOR with E. Press y to copy the selected node's ID hierarchy as JSON to the clipboard (or Y for a paste-ready plnk snapshot command) — built for handing context off to an AI agent in one keystroke.

Env pre-fills: PLANKA_SERVER, PLANKA_USERNAME, PLANKA_PASSWORD, PLNK_TUI_BOARD.

Docs: docs/tui/ — overview · keybindings · live-target model · tree view reference · fast copy.

Architecture

Three-crate Rust workspace:

• plnk-core — standalone Planka SDK. HTTP client, domain models, API traits, auth, typed errors. Usable on its own.
• plnk-cli — the plnk binary. Clap grammar + output rendering over plnk-core.
• plnk-tui — the plnk-tui binary. Ratatui explorer + Engine.IO websocket.

API versioning lives behind traits. If Planka changes its API, only the PlankaClientV1 implementation changes — domain models and the CLI layer are untouched.

Building

cargo check
cargo clippy -- -D warnings
cargo fmt --check
cargo test

See AGENTS.md for the full design rules, API quirks, and contribution guidelines.

Support

If this is useful to you, consider buying me a coffee.

License

MIT