--- name: pp-plane description: "Every Plane workspace as a typed, offline-syncable CLI — plus issue relations and module membership the REST API hides." author: "Anton Sidorov aka anticodeguy" license: "Apache-2.0" argument-hint: " [args] | install cli|mcp" allowed-tools: "Read Bash" metadata: openclaw: requires: bins: - plane-pp-cli install: - kind: go bins: [plane-pp-cli] module: github.com/mvanhorn/printing-press-library/library/project-management/plane/cmd/plane-pp-cli --- # Plane — Printing Press CLI ## Prerequisites: Install the CLI This skill drives the `plane-pp-cli` binary. **You must verify the CLI is installed before invoking any command from this skill.** If it is missing, install it first: 1. Install via the Printing Press installer. It defaults binaries to `$HOME/.local/bin` on macOS/Linux and `%LOCALAPPDATA%\Programs\PrintingPress\bin` on Windows: ```bash npx -y @mvanhorn/printing-press-library install plane --cli-only ``` 2. Verify: `plane-pp-cli --version` 3. Ensure the reported install directory is on `$PATH` for the agent/runtime that will invoke this skill. If the `npx` install fails (no Node, offline, etc.), fall back to a direct Go install (requires Go 1.26.6 or newer). This installs into `$GOPATH/bin` (default `$HOME/go/bin`), so add that directory to `$PATH` instead: ```bash go install github.com/mvanhorn/printing-press-library/library/project-management/plane/cmd/plane-pp-cli@latest ``` If `--version` reports "command not found" after install, the runtime cannot see the binary directory on `$PATH`. Do not proceed with skill commands until verification succeeds. The Plane REST API Visit our quick start guide and full API documentation at [developers.plane.so](https://developers.plane.so/api-reference/introduction). ## Unique Capabilities These capabilities aren't available in any other tool for this API. - **`relations`** — List, create, and delete work-item relations (blocking, blocked_by, duplicate, relates_to, temporal). - **`module`** — Module-membership helpers: cache enrichment (sync) and assign-on-create. Plane's issue API never returns module membership, so `sync` enriches the local cache at its tail. - **`attach-file`** — Attach a local file to a work item (presign, upload, mark uploaded) in one step; the generated commands expose only the presign and mark steps. Example: `plane-pp-cli attach-file ./report.pdf` ## Command Reference **assets** — **File Upload & Presigned URLs** Generate presigned URLs for direct file uploads to cloud storage. Handle user avatars, cover images, and generic project assets with secure upload workflows. *Key Features:* - Generate presigned URLs for S3 uploads - Support for user avatars and cover images - Generic asset upload for projects - File validation and size limits *Use Cases:* User profile images, project file uploads, secure direct-to-cloud uploads. - `plane-pp-cli assets create-generic-upload` — Generate presigned URL for generic asset upload - `plane-pp-cli assets create-user-upload` — Generate presigned URL for user asset upload - `plane-pp-cli assets delete-user` — Delete user asset. Delete a user profile asset (avatar or cover image) and remove its reference from the user profile. - `plane-pp-cli assets get-generic` — Get presigned URL for asset download - `plane-pp-cli assets update-generic` — Update generic asset after upload completion - `plane-pp-cli assets update-user` — Mark user asset as uploaded **invitations** — Manage invitations - `plane-pp-cli invitations workspaces-create` — Create a workspace invite - `plane-pp-cli invitations workspaces-destroy` — Delete a workspace invite - `plane-pp-cli invitations workspaces-list` — List all workspace invites for a workspace - `plane-pp-cli invitations workspaces-partial-update` — Update a workspace invite - `plane-pp-cli invitations workspaces-retrieve` — Get a workspace invite by ID **issues** — Manage issues - `plane-pp-cli issues get-workspace-work-item` — Retrieve a specific work item using workspace slug, project identifier, and issue identifier. - `plane-pp-cli issues search-work-items` — Perform semantic search across issue names, sequence IDs, and project identifiers. **members** — **Team Member Management** Manage team members, roles, and permissions within projects and workspaces. Control access levels and track member participation. *Key Features:* - Invite and manage team members - Assign roles and permissions - Control project and workspace access - Track member activity and participation *Use Cases:* Team setup, access control, role management, collaboration. - `plane-pp-cli members` — Retrieve all users who are members of the specified workspace. **projects** — **Project Management** Create and manage projects to organize your development work. Configure project settings, manage team access, and control project visibility. *Key Features:* - Create, update, and delete projects - Configure project settings and preferences - Manage team access and permissions - Control project visibility and sharing *Use Cases:* Project setup, team collaboration, access control, project configuration. - `plane-pp-cli projects create` — Create a new project in the workspace with default states and member assignments. - `plane-pp-cli projects delete` — Permanently remove a project and all its associated data from the workspace. - `plane-pp-cli projects list` — Retrieve all projects in a workspace or get details of a specific project. - `plane-pp-cli projects retrieve` — Retrieve details of a specific project. - `plane-pp-cli projects update` — Partially update an existing project's properties like name, description, or settings. **stickies** — Manage stickies - `plane-pp-cli stickies create-sticky` — Create a new sticky in the workspace - `plane-pp-cli stickies delete-sticky` — Delete a sticky by its ID - `plane-pp-cli stickies list` — List all stickies in the workspace - `plane-pp-cli stickies retrieve-sticky` — Retrieve a sticky by its ID - `plane-pp-cli stickies update-sticky` — Update a sticky by its ID **users** — **Current User Information** Get information about the currently authenticated user including profile details and account settings. *Key Features:* - Retrieve current user profile - Access user account information - View user preferences and settings - Get authentication context *Use Cases:* Profile display, user context, account information, authentication status. - `plane-pp-cli users` — Retrieve the authenticated user's profile information including basic details. **work-items** — **Work Items & Tasks** Create and manage work items like tasks, bugs, features, and user stories. The core entities for tracking work in your projects. *Key Features:* - Create, update, and manage work items - Assign to team members and set priorities - Track progress through workflow states - Set due dates, estimates, and relationships *Use Cases:* Bug tracking, task management, feature development, sprint planning. - `plane-pp-cli work-items get-workspace-2` — Retrieve a specific work item using workspace slug, project identifier, and issue identifier. - `plane-pp-cli work-items search-2` — Perform semantic search across issue names, sequence IDs, and project identifiers. ### Finding the right command When you know what you want to do but not which command does it, ask the CLI directly: ```bash plane-pp-cli which "" ``` `which` resolves a natural-language capability query to the best matching command from this CLI's curated feature index. Exit code `0` means at least one match; exit code `2` means no confident match — fall back to `--help` or use a narrower query. ## Auth Setup Run `plane-pp-cli auth setup` to print the URL and steps for getting a key (add `--launch` to open the URL). Then set: ```bash export PLANE_API_KEY_AUTHENTICATION="" ``` To persist credentials, use `plane-pp-cli auth set-token `. Stored secrets live in `credentials.toml` under the data dir, not in `config.toml`. Run `plane-pp-cli doctor` to verify setup. ## Workspace targeting Plane's REST API is workspace-scoped: every request goes to `…/api/v1/workspaces//…`. The public API **cannot enumerate** a user's workspaces from an API key, so the slug is user-supplied — take it from the browser URL (`app.plane.so//`). Keep `base_url` templated as `https:///api/v1/workspaces/{slug}` (literal `{slug}`); do **not** bake a concrete slug into it (that pins the CLI to one workspace and is flagged by `doctor`). The active workspace is chosen by precedence: **`--workspace ` flag > `PLANE_SLUG` env > `default_workspace` (config)**. > **Hitting an unexpected `403`/empty result?** Run `echo $PLANE_SLUG` first. A process-wide `PLANE_SLUG` exported in your shell **silently overrides** `default_workspace`, so commands target that workspace and items in any other one come back as `403 "You do not have permission"` — a wrong-workspace symptom masquerading as a permissions problem, not a key issue. Either unset it, set it per-project (e.g. `PLANE_SLUG=` in the project's env), or pass `--workspace ` explicitly (the flag always wins). `plane-pp-cli workspaces current` shows the active slug **and where it was resolved from**. ```bash # One-time onboarding: probe + enroll your slug(s), write a templated base_url plane-pp-cli init --host https://api.plane.so acme bravo --default acme # Or manage the local registry directly plane-pp-cli workspaces add acme bravo # access-probes each before saving plane-pp-cli workspaces use acme # probe + set as the default plane-pp-cli workspaces list # show enrolled workspaces (the API can't list them for you) plane-pp-cli workspaces current # show active slug + where it was resolved from # Target a specific workspace for one command (overrides env + default) plane-pp-cli members --workspace bravo --agent --select display_name ``` Enrollment is local-only (a `[[workspaces]]` registry in `config.toml`) because the API can't enumerate workspaces by key. A bad slug fails loudly (the probe rejects it with a non-zero exit) rather than silently returning the wrong workspace. **Via the MCP server:** the `plane_execute` tool takes an optional top-level `workspace` argument — the MCP twin of `--workspace`, same top precedence over `PLANE_SLUG`/`default_workspace`. Pass it to target one call at a specific workspace; omit it to use the configured default. (Without it the server resolves the slug from `PLANE_SLUG`/`default_workspace` at load time, so the same `403`-as-wrong-workspace trap above applies to MCP calls.) ## Agent Mode Add `--agent` to any command. Expands to: `--json --compact --no-input --no-color --yes`. - **Pipeable** — JSON on stdout, errors on stderr - **Filterable** — `--select` keeps a subset of fields. Dotted paths descend into nested structures; arrays traverse element-wise. Critical for keeping context small on verbose APIs: ```bash plane-pp-cli projects list --agent --select id,name,status ``` - **Previewable** — `--dry-run` shows the request without sending - **Offline-friendly** — sync/search commands can use the local SQLite store when available - **Non-interactive** — never prompts, every input is a flag - **Explicit retries** — use `--idempotent` only when an already-existing create should count as success, and use `--ignore-missing` only when a missing delete target should count as success ### Response envelope Commands that read from the local store or the API wrap output in a provenance envelope: ```json { "meta": {"source": "live" | "local", "synced_at": "...", "reason": "..."}, "results": } ``` Parse `.results` for data and `.meta.source` to know whether it's live or local. A human-readable `N results (live)` summary is printed to stderr only when stdout is a terminal AND no machine-format flag (`--json`, `--csv`, `--compact`, `--quiet`, `--plain`, `--select`) is set — piped/agent consumers and explicit-format runs get pure JSON on stdout. ## Paths and state Agents should treat the CLI's path resolver as part of the runtime contract: - Use `--home ` for one invocation, or set `PLANE_HOME=` to relocate all four path kinds under one root. - Use per-kind env vars only when a specific kind must diverge: `PLANE_CONFIG_DIR`, `PLANE_DATA_DIR`, `PLANE_STATE_DIR`, `PLANE_CACHE_DIR`. - Resolution order is per-kind env var, `--home`, `PLANE_HOME`, XDG (`XDG_CONFIG_HOME`, `XDG_DATA_HOME`, `XDG_STATE_HOME`, `XDG_CACHE_HOME`), then platform defaults. - `config` contains settings like `config.toml` and profiles. `data` contains `credentials.toml`, `data.db`, cookies, and auth sidecars. `state` contains persisted queries, jobs, and `teach.log`. `cache` contains regenerable HTTP/cache files. - Stored secrets live in `credentials.toml` under the data dir. Existing legacy `config.toml` secrets are read for compatibility and leave `config.toml` on the first auth write. - Run `plane-pp-cli doctor --fail-on warn` to surface path and credential-location warnings. `agent-context` exposes a schema v4 `paths` block for agents that need the resolved dirs. - For MCP, pass relocation through the MCP host config. The MCP binary does not inherit CLI flags: ```json { "mcpServers": { "plane": { "command": "plane-pp-mcp", "env": { "PLANE_HOME": "/srv/plane" } } } } ``` Fleet precedence: an inherited per-kind env var overrides an explicit `--home` for that kind. Use `PLANE_HOME` or per-kind vars as durable fleet levers, and use `--home` only for a single invocation. Relocation is not reversible by unsetting env vars; move files manually before clearing `PLANE_HOME`, or `doctor` will not find credentials left under the former root. ## Automatic learning This CLI ships a self-capturing learning loop. The CLI does its own bookkeeping: every invocation is journaled locally, a failed flag followed by a corrected retry auto-derives a `flag_alias` candidate, and a `teach` on a query family without a playbook auto-synthesizes a `playbook_candidate` from the session's journal. Your job is judgment only: `recall` first, act on surfaced candidates, `teach` the final answer, `playbook amend` when you observe a correction. You never record failures by hand. ### Step 1: `recall` before any discovery Before list/search/drill commands on a new user question, run: ```bash plane-pp-cli recall "" --agent ``` The response envelope: ```json { "query": "...", "normalized": "", "query_entities": ["..."], "found": true | false, "match_score": 0.0, "results": [ { "resource_id": "...", "resource_type": "...", "venue": "...", "confidence": 2, "entity_match": "exact|partial|unknown", "source": "taught|preseed|pattern", "warnings": ["..."] } ], "mismatches": [ /* only when --debug-mismatches */ ], "warnings": [ /* top-level */ ], "candidates": [ { "id": 12, "class": "flag_alias | playbook_candidate", "summary": "...", "sightings": 3, "last_seen": "...", "rationale": "...", "next_action": ["", "plane-pp-cli learnings confirm 12"] } ], "playbook": { "query_family": "...", "playbook": { "steps": [ { "cmd": "", "purpose": "..." } ], "entity_slots": ["$ENTITY"], "expected_tool_calls": 3 }, "slots_resolved": { "$ENTITY": { "token": "", "canonical": "" } }, "notes": "" }, "notes": "" } ``` Empty-store short-circuit: if the store has no learnings, playbooks, or candidates yet (recall finds nothing and `learnings list` and `learnings candidates` are both empty), skip recall for the rest of this session instead of taxing every query; resume recall-first once something has been taught. ### Step 2: decision tree Read `candidates`, `playbook`, `notes`, `results[0]`, and warnings in that order: ``` if Candidates present (warnings include "candidates_present"): -> candidates are try-then-confirm, never facts. Follow each candidate's two-step next_action verbatim: run the trial command first, then run `learnings confirm ` only after the trial verified the behavior. Reject a wrong candidate with `learnings reject `. -> NEVER re-teach something recall surfaced as a candidate; confirm or reject that candidate instead of teaching a duplicate. -> candidates ride alongside playbooks and resource hits, not instead of them; continue with the branches below after acting on them. if Playbook present: -> READ Playbook.notes verbatim FIRST (workarounds + gotchas the CLI surface doesn't expose) -> replay Playbook.steps in order, substituting Playbook.slots_resolved entries for the entity slot tokens. If a step's slot is unresolved, fall back to discovery for that step only. -> the Playbook's expected_tool_calls is a budget; if you find yourself running materially more, record the divergence via `plane-pp-cli playbook amend` at end-of-session. elif Notes present (no Playbook): -> read Notes verbatim before any discovery step; they carry known gotchas for this query family even when no structured choreography exists yet. elif Found AND Results[0].EntityMatch == "exact" AND Results[0].Confidence >= 2: -> skip discovery; fetch live data for Results[*].ResourceID in parallel elif Found AND Results[0].EntityMatch == "partial": -> candidate hint, NOT a hit; read the resource title to validate before trusting elif (any row in Mismatches[] when --debug-mismatches was passed): -> treat as cold start; the stored learning is for a different entity (different canonical resolved from query_entities) else: // Found == false, no playbook, no notes -> cold start; run discovery normally; teach the answer afterward (Step 4). If the family has no playbook yet, that teach auto-synthesizes a playbook candidate from this session's journal - you do not need to record one by hand. ``` Playbook and Notes are orthogonal to the per-resource path. A recall response can carry both a Playbook AND a `Results[]` hit - use both: the Playbook tells you which choreography to run; the resource hits short-circuit specific steps. Default to skipping `mismatches`; pass `--debug-mismatches` only when investigating cold-start surprises. Candidate judgment details: `learnings confirm ` prints the candidate's full payload before materializing it - check that the printed payload matches the behavior you verified. `learnings reject ` tombstones the derivation signature so the same candidate does not resurface. The envelope carries only the few candidates worth acting on now; `plane-pp-cli learnings candidates` lists the full open set. Graceful degradation: if `learnings confirm` is an unknown command, you are driving an older binary - ignore the candidates guidance and follow the rest of the protocol. ### Step 3: always read `warnings` - `low_confidence`: row exists at `confidence<2`. Treat as a hint, not a skip-discovery hit. - `resource_not_in_store`: the local store doesn't have the resource the learning points at. The match validator couldn't classify entities — direct-fetch and re-evaluate. - `cross_alias_match` (per-result): the row