Skip to content

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:

FolderHoldsSynced by
schema/The project's structure: features, work item types, states, workflows, labels, members, and work item and page templatesplane schema push, import, sync, diff, and plane push
work/Operational data: work items, cycles, modules, milestones and pagesplane 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:

LabelMeaning
SafeRead-only, or changes only local files. Runs without asking.
ConfirmChanges Plane or overwrites local files. Asks first; --force skips the question.
DestructiveCan 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:

bash
pipx install plane-compose
plane --version

To upgrade, or to pin this release:

bash
pipx upgrade plane-compose
pip install plane-compose==0.5.2

Shell 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.

bash
# 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 pull

A work item in work/workitems.yaml:

yaml
workitems:
  - id: MYPROJ-1
    title: Implement user authentication
    type: Task
    state: Ready
    priority: high
    labels:
      - Backend
    description: |
      Add OAuth2 authentication support

Give 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 ​

CommandDoesLabel
auth loginSave a connection after checking the tokenConfirm
auth list-connectionsShow connections and their linked workspacesSafe
auth connect-workspace / disconnect-workspaceLink or unlink a workspace on a connectionConfirm
auth logoutRemove a connection and its workspacesConfirm
initScaffold a local project from a templateConfirm
cloneCopy an existing Plane project into a local folderSafe
pushPush schema, then work, with conflict detectionConfirm
pullPull schema and work into your filesConfirm
diffCompare tracked work with Plane in both directionsSafe
statusOffline summary of what is synced and what is pendingSafe
validateCheck work items before pushingSafe
schema validateCheck schema files offlineSafe
schema pushCreate the project and push the schema (additive)Confirm
schema importMap local names to remote IDs; optionally merge or overwriteConfirm
schema syncMake the remote schema match local, including deletesDestructive
schema diffCompare local and remote schemaSafe
upgradeApply a template to an existing projectConfirm
ws clone / pull / push / diff / template / upgradeWorkspace-level configuration as filesConfirm
ws stateInspect and reset workspace sync stateDestructive
stateInspect and repair project sync stateDestructive
rateRequest counters and client-side throttlingSafe

Global options such as --debug and --version go before the command. See Global options and exit codes.

Where files live ​

PathContents
~/.config/plane-compose/config.jsonSaved connections and workspaces. Owner-only (0600).
~/.config/plane-compose/rate-limits.jsonRequest counters shown by plane rate stats.
~/.config/plane-compose/plane.logDebug log, written when you pass --debug.
<project>/.plane/state.jsonSync 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 ​