Workspace configuration

The ws commands manage workspace-level configuration the same file-based way as projects. A cloned workspace is a folder named after the workspace slug, with a plane.yaml (type: workspace), schema/ and work/:

myteam/
├── plane.yaml
├── schema/
│   ├── features.yaml
│   ├── members.yaml
│   ├── workitemtypes.yaml
│   ├── project.yaml
│   ├── initiatives.yaml
│   ├── releases.yaml
│   ├── relations.yaml
│   ├── webhooks.yaml
│   ├── automations.yaml
│   ├── scripts.yaml
│   ├── templates_workitem.yaml
│   ├── templates_project.yaml
│   ├── templates_page.yaml
│   └── customers.yaml       # only when the customers feature is on
├── work/
│   ├── releases.yaml
│   └── pages.yaml           # only when the wiki feature is on
└── .plane/
    └── secrets.json         # webhook secrets, kept out of git

Some files are written only when the matching feature is on and the fetch succeeds, for example customers, wiki pages and templates.

Commands

Commands that take [workspace] work from inside the cloned folder when you leave it out.

Command	Flags	What it does
ws clone [workspace]	-c / --connection (required), --path, --skip <section>	Clone the workspace configuration into ./<slug>/. Shows a picker if you leave the slug out. A skipped work section is still created, empty.
ws pull [workspace]	-f / --force, -m / --merge, --skip <section>	Refresh from Plane. By default it shows the files that differ and asks before overwriting. --merge keeps local-only additions and applies remote changes without asking. --force lets Plane win entirely.
ws diff [workspace]	--skip <section>	Per-file comparison, grouped as local additions (what a push would send) and remote additions (what a pull would apply).
ws push [workspace]	-n / --dry-run, -f / --force, --prune, --skip <section>	Push local additions and updates. Never deletes unless you pass --prune. IDs assigned by Plane are written back into your YAML.
ws template <name> [path]	-w / --workspace, -f / --force	Save the workspace configuration as a template in <path>/<name>/, with a generated template.yaml and server IDs removed. Secrets, plane.yaml and .plane/ are never included.
ws upgrade [workspace]	-t / --template, --skip-pull, -n / --dry-run, --schema-only, -f / --force	Apply a workspace template (path, Git URL or URL@tag) to a cloned workspace. Local-only items are kept.
ws state		Inspect and reset workspace sync state.

--skip accepts releases, pages, webhooks, automations and scripts, though --help lists only releases.

plane ws clone myteam -c connection-1
cd myteam
plane ws diff
plane ws pull --merge
plane ws push --dry-run
plane ws template startup-baseline ~/plane-templates/
plane ws upgrade myteam -t ./workspaces/enterprise --skip-pull --dry-run

What ws push sends

Feature flags, work item types (new types, property create, link and unlink, options and renames), work item, project and page templates, customer properties, release tags and labels, releases, initiative labels, project states and labels, relation definitions, webhooks, automations, and workspace pages when the wiki is on. Webhook secrets are saved in .plane/secrets.json. Members and the type hierarchy aren't pushed.

ws push --prune deletes from Plane

With --prune, webhooks, automations, customer properties, templates and work item type properties that exist only in Plane are deleted. Run plane ws push --dry-run --prune first.

ws upgrade

ws upgrade applies work item types and properties, feature flags, initiative labels, relations, releases, project and page templates, and webhooks from the template. It pulls from Plane first with Plane winning, which discards local edits even with --dry-run. Pass --skip-pull --dry-run for a preview that changes nothing. It fails if you don't pass -t and no template is saved for the workspace. See upgrade for how templates merge.

ws state

Destructive.

Command	What it does
ws state show [workspace] [--json]	List workspace state as dotted paths, or print the raw JSON.
ws state remove <path> [-w workspace]	Remove one entry, for example releases.tags.v1.0.4, projects.states.Backlog or relations.Duplicate.
ws state reset [workspace] [-f]	Delete the workspace state file. The next command treats everything as new.

ws state clear-items appears in --help, but in v0.5.2 it only prints a note pointing at remove and reset, then exits 1. It changes nothing.