Plane Compose
Plane Compose manages a Plane project as files. You keep the project's schema and work items in YAML next to your code, and the plane command validates, diffs and syncs them with a Plane workspace through the public REST API.
It works like git plus terraform for a Plane project. plane clone and plane pull bring remote state down to files, plane push sends local edits up, and plane diff shows divergence in both directions. plane schema import and plane schema sync give a Terraform-style import and a declarative sync for the project schema.
These pages document Plane Compose v0.5.2. Run plane <command> --help for the live flag list on your version.
Schema and work
A project folder has two layers, plus local sync state:
| Folder | Holds | Synced by |
|---|---|---|
schema/ | The project's structure: features, work item types, states, workflows, labels, members, and work item and page templates | plane schema push, import, sync, diff, and plane push |
work/ | Operational data: work items, cycles, modules, milestones and pages | plane push, plane pull, plane diff |
.plane/ | state.json, which maps local names and keys to remote IDs. Git-ignored and maintained for you. See Sync state. | Automatic; inspect it with plane state |
See Project files for every file and field.
How commands behave
Each command falls into one of three groups:
| Label | Meaning |
|---|---|
| Safe | Read-only, or changes only local files. Runs without asking. |
| Confirm | Changes Plane or overwrites local files. Asks first; --force skips the question. |
| Destructive | Can delete remote data or discard local sync state. Read it twice. |
Install
Plane Compose needs Python 3.10 or later. The package is plane-compose on PyPI and the command it installs is plane. pipx is the recommended installer:
pipx install plane-compose
plane --versionTo upgrade, or to pin this release:
pipx upgrade plane-compose
pip install plane-compose==0.5.2Shell completion is available through plane --install-completion and plane --show-completion.
Quick start
From nothing to a Plane project with one work item. You need an API token, which you create in Plane under your profile settings. Replace myteam with your workspace slug.
# 1. Save a connection. The token is checked against the workspace first.
plane auth login --server-url https://api.plane.so --auth-type pat \
--token "$PLANE_TOKEN" --workspace myteam -c main
# 2. Scaffold a local project. Nothing is created in Plane yet.
plane init MYPROJ -w myteam
cd myproj
# 3. Create the project in Plane and push the schema
plane schema push
# 4. Add a work item to work/workitems.yaml, then check it
plane validate
# 5. Push schema and work items
plane push
# Later: see drift in both directions, and pull remote edits down
plane diff
plane pullA work item in work/workitems.yaml:
workitems:
- id: MYPROJ-1
title: Implement user authentication
type: Task
state: Ready
priority: high
labels:
- Backend
description: |
Add OAuth2 authentication supportGive every work item a stable id
A work item without an id is tracked by a hash of its content, so editing its title makes Plane Compose treat it as a new item and create a duplicate. After the first push, plane writes the Plane sequence ID (for example MYPROJ-1) back into your YAML. plane validate warns about any item without an id.
The built-in template defines no custom work item types. Use Plane's own types such as Task, Bug and Feature by name.
All commands
| Command | Does | Label |
|---|---|---|
auth login | Save a connection after checking the token | Confirm |
auth list-connections | Show connections and their linked workspaces | Safe |
auth connect-workspace / disconnect-workspace | Link or unlink a workspace on a connection | Confirm |
auth logout | Remove a connection and its workspaces | Confirm |
init | Scaffold a local project from a template | Confirm |
clone | Copy an existing Plane project into a local folder | Safe |
push | Push schema, then work, with conflict detection | Confirm |
pull | Pull schema and work into your files | Confirm |
diff | Compare tracked work with Plane in both directions | Safe |
status | Offline summary of what is synced and what is pending | Safe |
validate | Check work items before pushing | Safe |
schema validate | Check schema files offline | Safe |
schema push | Create the project and push the schema (additive) | Confirm |
schema import | Map local names to remote IDs; optionally merge or overwrite | Confirm |
schema sync | Make the remote schema match local, including deletes | Destructive |
schema diff | Compare local and remote schema | Safe |
upgrade | Apply a template to an existing project | Confirm |
ws clone / pull / push / diff / template / upgrade | Workspace-level configuration as files | Confirm |
ws state | Inspect and reset workspace sync state | Destructive |
state | Inspect and repair project sync state | Destructive |
rate | Request counters and client-side throttling | Safe |
Global options such as --debug and --version go before the command. See Global options and exit codes.
Where files live
| Path | Contents |
|---|---|
~/.config/plane-compose/config.json | Saved connections and workspaces. Owner-only (0600). |
~/.config/plane-compose/rate-limits.json | Request counters shown by plane rate stats. |
~/.config/plane-compose/plane.log | Debug log, written when you pass --debug. |
<project>/.plane/state.json | Sync state for one project. Git-ignored. |
Set PLANE_CONFIG_DIR to use a different config directory. On first use, Plane Compose copies config.json and credentials from the legacy ~/.config/plane-cli/ location, unless PLANE_CONFIG_DIR is set.
Next steps
- Authentication: connections, self-hosted Plane, non-interactive login
- Project files: every file and field, and how sync state works
- Create and sync projects:
init,clone,push,pull,diff,status,validate - Schema and templates: the
schemacommands andupgrade - Workspace configuration: the
wscommands - Reference: sync state, CI, multiple projects, environment variables, troubleshooting

