Plane User Guide

Plane is an open-source project management tool for tracking work items, running cycles (sprints), and managing product roadmaps. This guide shows you how to get into Plane and how to use every part of the product — from creating your first work item to running cycles, building custom views, writing pages, and automating work through the API.

This guide covers the Community Edition of Plane (the open-source build in the makeplane/plane repository). Features that are exclusive to Plane's paid tiers are noted where relevant.

1. Quick Start

There are two ways to get a Plane account. Pick the one that fits you.

1.1 Option A — Plane Cloud (fastest)

The quickest way to use Plane is the hosted Plane Cloud service. You do not manage any infrastructure.

1. Go to app.plane.so.
2. Sign up with Google, GitHub, or email.
3. Create your first workspace and invite your team.

Tip

If you only want to evaluate Plane's features (work items, cycles, modules, pages, views), use Plane Cloud. Come back to self-hosting once you know you want to run it on your own infrastructure.

1.2 Option B — Self-host with Docker (full control)

Self-hosting gives you full control over your data. You need a machine with Docker installed, a minimum of 2 vCPU and 4 GB RAM, and a bash-capable shell (Linux, macOS, or Git Bash on Windows).

# 1. Create a working folder
mkdir plane-selfhost && cd plane-selfhost

# 2. Download the official installer for the latest release
curl -fsSL -o setup.sh https://github.com/makeplane/plane/releases/latest/download/setup.sh
chmod +x setup.sh

# 3. Run it
./setup.sh

The installer presents a menu:

Select an Action you want to perform:
   1) Install (x86_64)
   2) Start
   3) Stop
   4) Restart
   5) Upgrade
   6) View Logs
   7) Backup Data
   8) Exit

Action [2]:

Type 1 to install (this downloads docker-compose.yaml and plane.env into a plane-app/ folder), then 8 to exit. Edit plane-app/plane.env to set your domain, run ./setup.sh again, and choose 2 to start.

# After editing plane.env, start the stack
./setup.sh        # choose: 2) Start

Open your browser at the URL you configured (default http://localhost). The first account you create on a fresh instance must be promoted to instance admin — see Section 11 for the one-time admin setup.

Important

For a complete self-hosting reference — architecture, all environment variables, Kubernetes/Swarm, backups, upgrades, SSO — see the Plane Admin Guide. This User Guide covers only the everyday "get it running" path.

1.3 Your first five minutes in Plane

Once you can sign in, the fastest path to value:

• [ ] Create a workspace (your organization's home).
• [ ] Create a project inside it.
• [ ] Create a few work items (tasks/issues).
• [ ] Set a state (Todo → In Progress → Done) and assignee on each.
• [ ] Start a cycle and pull work items into it.
• [ ] Open the Analytics view to watch progress.

The rest of this guide expands each of these.

2. Core Concepts

Plane organizes everything into a clear hierarchy. Understanding it makes the rest of the product obvious.

Note

Plane renamed "issues" to work items in the product UI, but you will still see "issue" in the API, the URL structure, and older terminology. They are the same object.

Workspace (my-team)
└── Project (Website Redesign, identifier WEB)
    ├── Work Items  (WEB-1, WEB-2, …)
    ├── Cycles      (Sprint 12, Sprint 13)
    ├── Modules     (Checkout, Search)
    ├── Views       (My open bugs, This week)
    ├── Pages       (Spec docs, meeting notes)
    └── Members      (with roles)

3. Workspaces

A workspace is where your team lives. You can belong to multiple workspaces (e.g. one per company or client).

3.1 Creating a workspace

On first sign-in you are prompted to create a workspace. Later, create additional ones from the workspace switcher in the top-left sidebar.

A workspace has:

• A name and a unique slug (used in every URL).
• Members with roles.
• A home dashboard with recent activity, your assigned work, and widgets.
• Workspace-level settings (members, billing, exports, webhooks, integrations, API tokens).

3.2 Inviting members

Workspace admins invite members by email from Settings → Members. Invited users receive an email (self-hosted instances must have SMTP configured for invitations to send — see the Admin Guide).

Each member has a workspace role:

Tip

Roles are also applied per project — a workspace Member can be a project Admin in one project and not a member of another. See Section 4.3.

3.3 Favorites and recents

Star any project, view, page, or cycle to pin it to your Favorites in the sidebar. Plane also tracks recently visited items on your workspace home so you can jump back to where you were.

4. Projects

A project groups related work. Everything you track — work items, cycles, modules, pages — belongs to a project.

4.1 Creating a project

From the workspace sidebar, click + Create Project. You set:

• Name and identifier — the identifier is a short uppercase prefix (e.g. WEB) that numbers every work item in the project (WEB-1, WEB-2, …). Choose it carefully; it appears everywhere.
• Description, icon/emoji, and cover image.
• Network/visibility — whether the project is private (invite-only) or visible to the whole workspace.
• Lead and initial members.

Caution

The project identifier must be unique within the workspace and is hard to change later because it is baked into every work item's reference number. Pick a stable, meaningful prefix from the start.

4.2 Project features

Each project can enable or disable major features from Project Settings → Features:

• Cycles — time-boxed iterations.
• Modules — feature groupings.
• Views — saved filters.
• Pages — project documents.
• Intake — triage inbox for incoming work items.

Disabling a feature hides it from the project sidebar. Enable only what your team uses to keep the interface focused.

4.3 Project members and roles

Add members to a project from Project Settings → Members. Project roles mirror workspace roles (Admin, Member, Guest) but apply only inside the project. A project Admin can manage states, labels, estimates, and members for that project.

4.4 States and labels

• States define your workflow. Each state belongs to one of five state groups: Backlog, Unstarted (e.g. Todo), Started (e.g. In Progress), Completed (e.g. Done), Cancelled. Create custom states (e.g. "In Review", "Blocked") under Project Settings → States. Work items move between states as work progresses, and the state group drives progress charts.
• Labels are free-form tags. Create them under Project Settings → Labels and apply multiple labels per work item for filtering (e.g. bug, p1, frontend).

4.5 Estimates

Enable Estimates to size work items. Plane supports point-based and category-based estimate systems with custom estimate points (e.g. Fibonacci: 1, 2, 3, 5, 8). Configure them under Project Settings → Estimates, then set an estimate on each work item to power velocity and burn-down analytics.

4.6 Archiving projects

Projects can be archived when work concludes. Archived projects are hidden from the active list but retained and restorable. Find them under the workspace's archived projects area.

5. Work Items

Work items (issues) are the heart of Plane. This section covers everything you can do with them.

5.1 Creating a work item

Create a work item several ways:

• The + New Work Item button in any project.
• Quick add at the bottom of a list or board column.
• The Power-K command palette (Ctrl/⌘ + K) → Create work item.
• Pressing the keyboard shortcut C from within a project.

A work item supports:

5.2 Sub-items (sub-work-items)

Break a work item into a tree of sub-items. A parent shows the roll-up progress of its children. Use this for epics-and-tasks style breakdowns.

Note

Known behavior: in some versions, collapsible sub-items may take multiple clicks to expand (community issue #9124). If a sub-item tree doesn't expand on the first click, click the chevron again.

5.3 Linking and relating work items

• Relations — link two work items as blocking, blocked by, duplicate, or relates to. Relations appear in both items and help you understand dependencies.
• Links — attach external URLs (design files, docs, PRs) to a work item.
• Attachments — upload files directly to a work item. The default per-file limit is 5 MB (configurable by your instance admin via FILE_SIZE_LIMIT).

Warning

Uploading a file larger than the limit returns File too large. Size should not exceed 5 MB. Compress the file or ask your admin to raise FILE_SIZE_LIMIT (see the Admin Guide).

5.4 Comments, reactions, and mentions

Each work item has an activity feed and a comment thread. You can:

• Comment with rich text.
• @mention members to notify them.
• React to comments and work items with emoji.
• Subscribe to a work item to receive notifications on every change, even if you're not assigned.

Every change (state, assignee, label, etc.) is recorded in the activity log for a full audit trail.

5.5 Bulk operations

Select multiple work items in a list or spreadsheet layout to bulk edit — change state, assignee, priority, labels, or delete several at once. (Bulk editing was a long-requested feature, community issue #1134.)

5.6 Drafts

Start a work item and save it as a draft if it isn't ready to publish into the project. Drafts live in your workspace drafts area until you promote them to real work items.

5.7 Work item types (custom types)

Projects can define work item types (e.g. Bug, Story, Task, Epic) with their own icon and, in higher tiers, custom properties. Custom types appear when creating a work item so teams can model their own taxonomy.

6. Layouts: viewing work your way

Plane renders a project's work items in several layouts. Switch between them from the layout selector in any work-item list. The same filters and grouping apply across layouts.

6.1 Filtering, grouping, and display options

Every layout supports a shared set of controls:

• Filters — narrow by state, assignee, priority, label, cycle, module, start/due date, created-by, and more. Filters combine to build precise queries.
• Group by — cluster work items by state, priority, assignee, label, cycle, module, or created-by.
• Display properties — toggle which fields show on each card (estimate, due date, sub-item count, labels, etc.).
• Ordering — sort by manual order, created date, updated date, priority, etc.

Tip

Set up the filters and grouping you use most, then save them as a View (next section) so you don't rebuild them each time.

7. Cycles

Cycles are Plane's sprints — time-boxed iterations with a start and end date.

7.1 Running a cycle

1. Enable Cycles in project features.
2. Create a cycle with a name and date range (e.g. "Sprint 14", Jun 1–Jun 14).
3. Add work items to the cycle (from the work item's cycle field, by dragging, or via bulk edit).
4. Track progress on the cycle's burn-down chart and progress stats as items complete.

7.2 Active cycle and analytics

The active cycle view summarizes the current sprint: completion percentage, scope changes, work by assignee, and by state. Use it in standups to see what's on track and what's at risk.

7.3 Transferring incomplete work

When a cycle ends, move unfinished work items to the next cycle with transfer issues so nothing falls through the cracks. The completed cycle is preserved for historical analytics.

Caution

Archiving a cycle that has no end date has crashed in some versions with a TypeError (community issue #9169). Set an end date on cycles before archiving to avoid this.

7.4 Archiving cycles

Old cycles can be archived to declutter the active list while preserving their data and charts.

8. Modules

Modules group work items by feature or deliverable, independent of time (unlike cycles).

• Create a module (e.g. "Checkout flow") with a lead, members, and a target date.
• Add work items to it.
• Track module progress with its own analytics sidebar and burn-down.
• Set a module status (Planned, In Progress, Paused, Completed, Cancelled) and link related modules.

Use cycles for when work happens and modules for what the work builds toward. A work item can belong to one cycle and one module at the same time.

9. Views, Pages, Analytics, and Intake

9.1 Views

A View is a saved configuration of filters, grouping, display options, and layout. Create a view (e.g. "My urgent bugs", "Unassigned this cycle") and reuse it instantly. Views can be project-level or workspace-level (spanning all projects). Share views with your team so everyone works from the same lens.

9.2 Pages

Pages are rich-text documents inside a project for specs, notes, and knowledge.

• Full rich-text editor: headings, lists, tables, callouts, code blocks, images, and embeds.
• Embed work items directly into a page.
• AI assistance for drafting and editing (where enabled on your instance).
• Real-time collaboration — multiple people edit a page simultaneously (powered by Plane's live server).
• Version history — pages keep versions so you can review and restore earlier states.
• Convert page text into actionable work items.

Note

Real-time page collaboration requires the live service to be running on self-hosted instances. If pages don't sync between users, your admin should check the live server (see the Admin Guide).

9.3 Stickies

Stickies are quick personal sticky notes attached to your workspace home — lightweight reminders that don't belong to any project.

9.4 Analytics

Analytics give real-time insight across your data. View work item counts and trends by state, assignee, priority, label, cycle, and more, as charts and tables. Scope analytics to a project or across the whole workspace, and export the underlying data.

9.5 Intake

Intake is a triage inbox for incoming work items (e.g. from external reporters or forms). Items land in Intake with a status (Pending, Accepted, Declined, Duplicate, Snoozed) and you decide whether to accept them into the project as real work items. This keeps unvetted requests out of your active boards until reviewed.

10. Notifications, search, and shortcuts

10.1 Notifications

The notifications inbox (bell icon) collects mentions, assignments, subscribed-item changes, and comments. Filter notifications, mark them read, snooze them, and archive them. You can also set notification preferences to control what reaches your email.

10.2 Search and the command palette

Press Ctrl/⌘ + K to open Power-K, Plane's command palette. From it you can:

• Search work items, projects, pages, cycles, and modules.
• Jump to any part of the app.
• Run actions (create a work item, change a setting, switch project) without leaving the keyboard.

10.3 Common keyboard shortcuts

Tip

Inside any rich-text field (descriptions, pages, comments), type / to open the slash menu for inserting formatting, images, tables, callouts, and embeds without touching the mouse.

11. Self-hosting essentials

This section covers the minimum a self-host user needs after the Quick Start. For the full reference, see the Plane Admin Guide.

11.1 The setup.sh menu

The installer you downloaded is a long-lived management tool. Re-run ./setup.sh any time to:

11.2 Essential settings in plane.env

Before going beyond localhost, edit plane-app/plane.env:

Important

If you start Plane and the API fails with APP_BASE_URL or WEB_URL is not set, you have not set WEB_URL in plane.env. This value is mandatory.

11.3 Becoming the instance admin (God mode)

A self-hosted instance has an instance admin who controls instance-wide settings (authentication methods, AI, email, image search) through the God mode admin panel at /god-mode. Promote your account once after install — see the Admin Guide's "Instance administration" section for the exact create_instance_admin / configure_instance commands.

12. The Plane API (for users)

Plane ships a documented REST API so you can automate work — create work items from scripts, sync external systems, or build integrations.

12.1 Getting an API token

1. Open Workspace Settings → API Tokens.
2. Create a token. Copy it immediately (it is shown once).
3. Send it on every request in the X-API-Key header.

12.2 Making a request

The external API is rooted at /api/v1/ and is organized around workspaces/{slug}/projects/{project_id}/....

# List your projects in a workspace
curl https://plane.example.com/api/v1/workspaces/my-team/projects/ \
  -H "X-API-Key: $PLANE_API_TOKEN"

# Create a work item in a project
curl -X POST \
  https://plane.example.com/api/v1/workspaces/my-team/projects/$PROJECT_ID/issues/ \
  -H "X-API-Key: $PLANE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Fix the login bug", "priority": "high"}'

12.3 What you can automate

The API exposes the same nouns you use in the UI: projects, work items (issues), cycles, modules, states, labels, members, estimates, intake items, stickies, and assets (file uploads). Each supports list/create/detail operations.

Note

Requests are rate-limited (default 60 requests/minute per token). If you receive HTTP 429, slow down or batch your calls. For the full endpoint reference, request schema, and the interactive Swagger/Redoc docs, see the Plane Admin Guide → REST API.

13. Troubleshooting

Error: APP_BASE_URL or WEB_URL is not set

• Cause: The API container started without a WEB_URL value in your environment file.
• Solution: Set WEB_URL (and CORS_ALLOWED_ORIGINS) in plane-app/plane.env to your instance's address, then restart with ./setup.sh → Restart.
• Prevention: Always configure WEB_URL before the first start; it has no usable default.

Error: File too large. Size should not exceed 5 MB.

• Cause: You tried to attach a file above the upload limit.
• Solution: Compress the file, or ask your instance admin to raise FILE_SIZE_LIMIT.
• Prevention: Keep attachments under the configured limit (5 MB by default).

Invitations or notification emails never arrive (self-hosted)

• Cause: SMTP is not configured on the instance.
• Solution: Ask your admin to set the email settings in God mode (or via env), then test with the instance's email test command.
• Prevention: Configure SMTP during installation if you plan to invite teammates.

Sign-in via Google/GitHub fails with an invalid redirect_uri

• Cause: The OAuth app's redirect URI or the instance's base URL is misconfigured (community issue #5853).
• Solution: Ask your admin to verify WEB_URL and the OAuth provider's allowed callback URL match your actual domain and port.
• Prevention: Set the real public URL before configuring OAuth.

A project opens to a blank/crashing screen in Safari or on iOS

• Cause: A known issue with window.requestIdleCallback on some Safari/iOS versions (community issue #9134).
• Solution: Update to a recent Plane release; try a Chromium-based browser as a workaround.
• Prevention: Keep your instance updated via ./setup.sh → Upgrade.

Creating a project silently fails

• Cause: Special characters in the project name or identifier have caused a client crash in some versions (community issue #8969); a workspace slug must also be valid (Slug is not valid).
• Solution: Use plain alphanumeric characters for the project identifier and workspace slug.
• Prevention: Keep identifiers short, uppercase, and alphanumeric.

Self-host install script fails on RHEL-based systems

• Cause: The setup script has failed on some RHEL/x86_64 systems (community issue #9199).
• Solution: Ensure Docker and Docker Compose are installed and your shell is bash; check the project's deployment docs for OS-specific notes.
• Prevention: Use a supported OS (Ubuntu / Linux AMI / macOS) with a current Docker.

API returns Given API token is not valid

• Cause: The X-API-Key header is missing, mistyped, or the token was revoked.
• Solution: Regenerate the token in Workspace Settings → API Tokens and send it in the X-API-Key header.
• Prevention: Store tokens securely; rotate if leaked.

API returns HTTP 429 Too Many Requests

• Cause: You exceeded the per-token rate limit (default 60/minute).
• Solution: Add backoff/retry to your client and batch requests where possible.
• Prevention: Stay under the configured API_KEY_RATE_LIMIT.

14. FAQ

Q: What's the difference between a "work item" and an "issue"? They are the same object. The UI calls them work items; the API, URLs, and older docs call them issues.

Q: When should I use a Cycle vs. a Module? Use cycles for when (time-boxed sprints with start/end dates and burn-down). Use modules for what (a feature or deliverable, regardless of timeline). A work item can be in one of each.

Q: Can a work item be in more than one cycle? No — a work item belongs to a single cycle at a time. You move it between cycles (e.g. transferring unfinished work at sprint end).

Q: How do I share a project or view with people outside my workspace? Use published views / spaces (DeployBoards). A project or view can be published to Plane's public Spaces site so external viewers can see it without a workspace seat.

Q: Is there a difference between the open-source version and Plane Cloud? This guide covers the open-source Community Edition. Plane Cloud and paid tiers add features (advanced work-item types/properties, additional integrations, enterprise SSO, etc.). Core project management — workspaces, projects, work items, cycles, modules, views, pages, analytics — is in the Community Edition.

Q: Which browsers are supported? Modern Chromium-based browsers (Chrome, Edge), Firefox, and Safari. Keep your instance updated, as some Safari/iOS issues are fixed in newer releases.

Q: Can I import data from Jira/Linear/other tools? Plane includes an importer framework. Availability of specific importers depends on your edition and version; check Workspace Settings → Imports.

Q: How do I export my work items? Use Analytics/Exports or the export options in workspace settings. Plane can export work items to CSV, JSON, and XLSX.

Q: Where is my data stored when self-hosting? In your own PostgreSQL database (work items, projects, etc.) and your object store (MinIO or S3) for file attachments. Nothing leaves your infrastructure.

Q: How do I update a self-hosted instance? Run ./setup.sh and choose Upgrade. Always back up first (the Backup Data action).

Q: How do I run a sprint retrospective? Use a completed cycle's analytics (completion %, scope changes, work by assignee) plus a Page to capture notes and action items, converting decisions into new work items.

15. Quick reference

Hierarchy

Workspace → Project → Work Item (+ sub-items)
                    → Cycle / Module / View / Page

Where things live

Key shortcuts

Self-host one-liner

mkdir plane-selfhost && cd plane-selfhost
curl -fsSL -o setup.sh https://github.com/makeplane/plane/releases/latest/download/setup.sh
chmod +x setup.sh && ./setup.sh   # choose 1) Install, then 2) Start