@plany/cli

Single-binary CLI for the Plany platform. Browser-based login, project picker, work-item commands, and the Memory MCP server.

Bins

• plany — the CLI. Subcommands: login, logout, whoami, init, status, skill, update, version, memory pull|mcp, items list|show|create|set|assign|priority|due|search|label, and the workspace reads projects, members, teams, labels.
• plany-mcp — stdio MCP server for AI agents (Cursor, Claude Code, OpenCode). Editor configs point here directly.

Install

npm i -g @plany/cli
# or: pnpm add -g @plany/cli

First-time setup

# Browser-based sign-in. Opens the Plany web app, you click Authorize,
# CLI captures the token via a localhost callback. Writes
# ~/.plany/credentials.json.
plany login

# In your code project directory:
plany init           # interactive picker — bind this dir to a Plany project
plany status         # show current creds + binding

Agent skill

The package ships an agent skill (skills/plany/SKILL.md) that teaches coding agents the work-item and memory commands so they use the CLI unprompted. plany init installs it into .claude/skills/ automatically when the repo has .claude/ or CLAUDE.md; install or refresh manually with:

plany skill

The skills/ directory follows the skills.sh layout, so for non-Claude agents (Cursor, Codex, OpenCode, …) you can install it from the published package:

npx skills add ./node_modules/@plany/cli   # or the global install path

Updating

Codex-style startup check: normal CLI commands read a cached latest-version file (~/.plany/version.json) and never wait on the registry; a stale cache is refreshed by a detached background process. TTY sessions only — --json and MCP invocations stay silent. Opt out with PLANY_NO_UPDATE_CHECK=1.

plany update         # reinstalls @plany/cli@latest via npm, pnpm, or bun

Memory

plany memory pull    # refresh the local mirror (.plany/memory.md or your editor's path)
plany memory mcp     # run the Memory MCP server on stdio (same as plany-mcp)

Editor config example (Claude Code, Cursor, OpenCode all use this shape):

{
  "mcpServers": {
    "plany-memory": { "command": "plany-mcp" }
  }
}

The MCP server exposes three tools:

| Tool | Purpose | | ----------------- | --------------------------------------------------------------- | | create_memory | Create a private memory in the bound project. | | update_memory | Update an existing memory by its publicKey (MEM-Kabc1-001). | | search_memories | Body-text search (use when the auto-loaded mirror is stale). |

For AI agents that read context from local files, the mirror file is the primary read surface — it's auto-loaded by Claude Code skills, Cursor rules, and OpenCode. The MCP tools are for write-back and dynamic queries.

Work items

plany items list                    # all items in the current project
plany items list --status inProgress  # filter
plany items set BIE-12 inProgress     # change status (backlog|todo|inProgress|done|cancelled)
plany items assign BIE-12 --to [email protected] --to "Bob"  # replace assignees (email or name)
plany items assign BIE-12 --me        # assign yourself; --clear empties
plany items priority BIE-12 P1        # P0..P4
plany items due BIE-12 2026-08-01     # or: plany items due BIE-12 clear
plany items search "login bug"        # title search, rendered like list
plany items label BIE-12 --add ux --remove backend  # label names, resolved server-side

Workspace

plany projects                      # projects you can access, across workspaces
plany members                       # workspace members + roles, pending invites
plany teams                         # teams you can see (admins/owners: all)
plany labels                        # workspace labels

members and labels are the lookup companions to items assign / items label: check the valid values first instead of relying on the error message to list them.

CLI-driven edits write the same activity events as web edits (workitem.status.changed, workitem.assignees.changed, …), so they show up in the in-app activity feed normally, and new assignees get the usual inbox notification.

Environment

| Variable | Default | Purpose | | --------------- | ------------------------------- | ---------------------------------------------------------- | | PLANY_WEB_URL | https://plany.bielcrystal.app | Web app URL used by plany login; override for local dev. |

Files

~/.plany/credentials.json    {"apiUrl": "...", "token": "plany_pat_..."}
<cwd>/.plany/config.json     Project binding (projectId, workspaceId, mirrorTarget).
<cwd>/.plany/memory.md       Memory mirror (or wherever mirrorTarget points).

Creds file is mode 0600. Revoke a stale device by deleting its row in the Plany web UI under Settings → API Tokens.