plane-cli: Instructions file for Codex

PlaneCLI

A Python CLI for Plane.so (SaaS or self-hosted) that manages projects, work items, cycles, modules, documents, labels, states, intake queues, and comments. Its defining feature is fuzzy resource resolution: any resource can be referenced by name, identifier (ABC-123), or UUID. Built with cyclopts, Rich, rapidfuzz, cashews, and the official plane-sdk.

Language

All docs, comments, and commit messages in English.

Commands

Everything runs through uv; common tasks are wrapped in the Makefile.

make install                       # uv sync (dev environment)
make test                          # uv run pytest tests/
make lint                          # ruff check src/
make lint-fix                      # ruff check --fix src/
make format                        # ruff format src/ tests/
make check                         # lint + test — run before committing
make run ARGS="wi ls -p Frontend"  # run the CLI

Single test: uv run pytest tests/test_resolve.py::test_name -v. Line length 100, Python >= 3.11, ruff selects E, F, I, W.

Structure

src/planecli/
  app.py           # Root cyclopts App; main() entry point; sub-app registration
  commands/        # One module per resource (list/show/create/update/delete). New features go here.
  utils/resolve.py # Resolution layer: resolve_<x>/resolve_<x>_async (UUID → identifier → fuzzy name)
  utils/fuzzy.py   # rapidfuzz token_sort_ratio, threshold 60
  api/             # client.py (PlaneClient singleton); async_sdk.py (async wrapper)
  cache.py         # cashews disk cache; one cached_list_<x> per resource
  formatters/      # output() / output_single() — table to stderr, JSON to stdout
  exceptions.py    # PlaneCLIError subclasses with message/hint/exit_code

Request flow: command → resolve → async SDK wrapper → (cache | Plane SDK) → formatter. See docs/architecture.md.

Conventions

• Never call the sync Plane SDK directly from a command. Wrap single calls in run_sdk(fn, *args) and paginated lists in paginate_all_async(list_fn, ...). For concurrent batches use create_client() (a fresh client per thread — don't share the singleton's requests.Session). See ADR-0001.
• Reads go through the cache layer. Resolvers and list commands call cached_list_<x>(...), which returns plain dicts (not Pydantic models). After any create/update/delete, call await invalidate_resource("<resource>", workspace, project_id). See ADR-0004.
• Error handling. Wrap SDK calls in try/except PlaneError and raise handle_api_error(e). Raise ValidationError/ResourceNotFoundError for user-facing problems. Exit codes: Auth=2, NotFound=3, API=4, Validation=5.
• --json flag. Every read/mutate command takes json: bool = False and passes as_json=json to the formatter. Table output stays on stderr so --json 2>/dev/null yields clean JSON. See ADR-0005.
• Lazy imports. Import SDK models and cache helpers inside the command function to keep CLI startup fast (sub-app registration in app.py uses # noqa: E402 deliberately).
• cyclopts idioms. Sub-apps declare aliases via name=["module", "modules"]; subcommands via @app.command(name="list", alias="ls"); short flags via Annotated[str, Parameter(alias="-p")]. Numpydoc parameter docstrings become --help text.