Plot CLI

Programmatic access to Plot workspaces for agents. The CLI is built around stable handles and compact output so coding agents can inspect and update Plot data without scraping the web app.

Agent Quick Start

# Authenticate. Use OAuth for an interactive shell, or a PAT for headless agents.
plot login
plot login --token "$PLOT_API_TOKEN"

# Confirm identity and choose a workspace.
plot whoami
plot workspace list --format json
plot workspace use scalespark-media

# Pull orientation data before changing work.
plot workspace info --format json
plot commands --format json
plot help identifiers

# Use @me and none anywhere nullable assignee or owner handles are accepted.
plot task list --assignee @me --format json
plot task create --name "Follow up" --team ENG --assignee @me
plot project update checkout-redesign-a1b2c3d4e5f6 --owner @me
plot task update ENG-042 --assignee none
plot project update checkout-redesign-a1b2c3d4e5f6 --owner none

# Install or refresh Plot's bundled agent skill.
plot setup
plot setup --yes

Agent Operating Contract

• Prefer --format json for reads. It is the default for most read commands and is the safest shape for agents to parse.
• Run plot commands --format json when you need the current command manifest.
• Run plot help identifiers before resolving copied Plot URLs or user-provided handles.
• Prefer handles over UUIDs: task pathId (ENG-042), team publicId (ENG), project/document slug or trailing publicId, collection slug, and user @username.
• Use @me anywhere an assignee or project owner handle is accepted. It resolves to the active authenticated user from local credentials.
• Use none anywhere a nullable assignee or project owner field is accepted to clear that field. Omitting the field is also treated as unassigned/no owner during create commands.
• Read responses expose the reusable root handle as id for every entity: task pathId, team/project/document publicId, collection/workspace slug, and user @username.
• Mutation commands print a short success sentence regardless of --format, for example Updated task ENG-042. plot batch and plot task create-tree keep structured JSON.
• Switch workspaces explicitly with plot workspace use <slug> when a copied URL contains a different workspace slug.
• Batch dependent writes through plot batch or plot task create-tree to reduce round trips and keep outputs machine-readable.
• Treat every non-zero exit as structured failure. The CLI writes errors as JSON with error, code, message, and (when applicable) a hint describing the next step an agent can take.
• Pass --quiet to suppress spinners and progress messages — stdout will only contain the formatted result.
• In CI or tight automation loops, set PLOT_CLI_SKIP_UPDATE_CHECK=1 to suppress the background self-update check and keep the per-invocation overhead minimal.
• Run plot setup to install the bundled plot-cli agent skill into supported local agent roots. Interactive first-run setup is skipped for CI and non-TTY sessions.

Requirements

• The plot binary installed and available on PATH.
• A Plot account with access to the workspace you want to inspect or update.
• Network access to Plot.
• For headless agents, a Plot Personal Access Token.

End users do not need Bun, pnpm, Node.js, repository source code, or internal service configuration.

Authentication

plot login                         # OAuth with local callback on 127.0.0.1:7568-7578
plot login --token "$PLOT_API_TOKEN"
plot whoami
plot auth status --format json
plot logout

Credentials are stored locally by the CLI. Use plot logout to remove the active workspace credentials.

Common Workflows

Orient In A Workspace

plot workspace info --format json
plot team list --format json
plot user list --format json
plot search "launch checklist" --format json
plot search "blocked launch work" --type task --project checkout-redesign-a1b2c3d4e5f6 --assignee @alice --format json

Inspect And Update Tasks

plot task list --team ENG --limit 20 --format json
plot task list --parent none --limit 20 --format json     # only top-level (non-subtask) tasks
plot task list --parent ENG-042 --format json             # subtasks of ENG-042
plot task get ENG-042 --format json
plot task update ENG-042 --status Done
plot task update ENG-042 --add-labels label_abc,label_def
plot task update ENG-042 --remove-labels label_xyz
plot task update ENG-042 --set-labels label_abc,label_def   # replace label set; pass "" to clear
plot comment add --entity task --id ENG-042 --body "Implemented and verified."

task update label semantics: --add-labels appends, --remove-labels detaches, --set-labels replaces the full set. --add-labels/--remove-labels can be combined; --set-labels cannot be combined with the other two. --labels is kept as a back-compat alias for --add-labels.

Create A Task With Dependencies

plot task create \
  --name "Write checkout regression tests" \
  --team ENG \
  --project checkout-redesign-a1b2c3d4e5f6 \
  --blocked-by ENG-041

task create is all-or-nothing: labels, dependencies, parent, status, priority, dates, and visibility are created through one composite mutator.

Create A Parent Task Tree

cat <<'JSON' | plot task create-tree --format json
{
  "name": "Ship checkout polish",
  "team": "ENG",
  "project": "checkout-redesign-a1b2c3d4e5f6",
  "subtasks": [
    { "name": "Fix empty state", "ref": "empty-state" },
    { "name": "Add regression coverage", "blockedBy": ["@empty-state"] }
  ]
}
JSON

create-tree supports one level of subtasks. Subtasks inherit team, project, assignee, and visibility unless overridden.

Batch Commands

plot batch reads a JSON array from stdin and executes entries sequentially.

cat <<'JSON' | plot batch
[
  {
    "command": "task",
    "action": "create",
    "args": {
      "name": "Triage checkout logs",
      "team": "ENG"
    }
  },
  {
    "command": "task",
    "action": "list",
    "args": {
      "team": "ENG",
      "limit": 5
    }
  }
]
JSON

Supported batch keys: task.create, task.update, task.delete, task.get, task.list, and project.update.

Commands

Run plot <command> --help for command-specific options.

| Command | Purpose | | ----------------------------------------------------------------------------- | --------------------------------------------------------------------------- | | login, auth login | Authenticate with OAuth or --token. | | logout, auth logout | Remove stored credentials. | | whoami, auth whoami | Print current user and workspace. | | auth status | Show active workspace and credential storage status. | | setup | Install or refresh the bundled Plot agent skill. | | workspace list | List authenticated workspaces. | | workspace use <slug> | Set the active workspace. | | workspace info | Print workspace orientation data. | | task list | List recent tasks with filters. | | task get <id> | Get task details with hydrated relations. | | task create | Create a task. | | task create-tree | Create a parent task with subtasks and dependencies. | | task update <id> | Update mutable task fields. | | task delete <id> | Soft-delete a task. | | task add-dependency | Mark one task as blocked by another. | | task remove-dependency | Remove a blocking relationship. | | task set-parent <id> | Convert a task into a subtask. | | task remove-parent <id> | Promote a subtask back to a top-level task. | | project list | List projects. | | project get <id> | Get project details. | | project summary <id> | Print project health. | | doc list, doc get, doc create, doc update | Read and mutate documents. | | collection list, collection get, collection create, collection update | Read and mutate collections. | | team list, team get <id> | List and inspect teams. | | task-status list --team <handle> | List valid task statuses for a team. | | label list --team <handle> | List task labels for a team. | | user list, user get <id>, user by-team <team> | Discover users. | | user combined-members | List users with access across projects, teams, and/or a task. | | activity list | List activity feed entries. | | inbox list, inbox read <id>, inbox archive <id> | Read and manage notifications. | | search <query> | Semantic/hybrid search across tasks, projects, documents, teams, and users. | | comment list, comment add | List or add comments on tasks and projects. | | batch | Execute a JSON command array from stdin. | | commands | Print the machine-readable command manifest. | | help identifiers | Print handle and URL parsing conventions. |

Identifiers

Use the shortest stable handle the CLI accepts.

| Entity | Preferred handle | Example | | ---------- | --------------------------- | -------------------------------- | | Task | pathId | ENG-042 | | Team | publicId | ENG | | Project | slug or trailing publicId | checkout-redesign-a1b2c3d4e5f6 | | Document | slug or trailing publicId | launch-checklist-78utu4m1d7iz | | Collection | slug | growth | | User | @username | @abraham |

Copied Plot URLs follow:

https://go.plot.app/{workspaceSlug}/{entityType}/{identifier}/{optionalContext}

Extract the workspace slug first. If it differs from the active workspace, run plot workspace use <workspaceSlug>.

Output And Errors

Most read commands accept --format json or --format markdown. JSON is the default. Mutation commands ignore --format and print a short success sentence such as Created task ENG-042 or Deleted task ENG-042.

Root Handles

Read responses use id for the agent-facing handle on the root entity:

{
  "id": "ENG-042",
  "name": "Write checkout regression tests",
  "status": "In Progress"
}

The value is the canonical handle to reuse in later CLI calls: task pathId, team/project/document publicId, collection/workspace slug, or user @username.

List Envelope

Every list command (e.g., task list, project list, team list, doc list, collection list, user list, inbox list, comment list, activity list, search) returns the same pagination envelope shape in JSON:

{
  "<itemsKey>": [...],
  "count": 3,
  "startAt": 0,
  "limit": 20,
  "hasMore": false,
  "nextStartAt": null
}

The <itemsKey> is the plural entity name (tasks, projects, teams, documents, collections, users, notifications, comments, entries, results). Markdown output renders each item, then a footer line:

_count: 3, startAt: 0, limit: 20, hasMore: false_

Empty lists still render the footer.

Quiet Mode

Pass --quiet (or -q) to suppress spinners and progress messages on any data-loading command. Stdout will only contain the formatted result, which lets agents pipe --format json --quiet directly into a JSON parser without filtering chrome.

Errors are structured. When the failure is recoverable, an optional hint field describes the concrete next step an agent should take.

{
  "error": true,
  "code": "AUTH_REQUIRED",
  "message": "No active workspace. Run `plot login` to authenticate.",
  "hint": "Run 'plot login' to authenticate."
}

{
  "error": true,
  "code": "NOT_FOUND",
  "message": "Task \"NOPE-999\" not found.",
  "hint": "Run 'plot help identifiers' for handle formats, or 'plot task list' to discover ids."
}

The hint field is optional. Agents should prefer it when present, but fall back to code + message for branching.

Error code groups:

| Exit | Meaning | | ---- | ---------------------------------------------------------------------- | | 1 | Validation, not found, forbidden, not implemented, or unknown failure. | | 2 | Authentication required or expired. | | 3 | Network or sync failure. |

Runtime Notes

The CLI manages its own local runtime state. The first data command after login may take longer while Plot data is prepared locally; later commands should be faster.

Use these commands when a session appears stale:

plot auth status --format json
plot logout
plot login

Self-Update Behavior

The CLI checks for new releases at most once per day in the background, on a best-effort basis (failures are silent and never block the current command). To force an immediate check and install the latest release, run:

plot update

After a successful update, the CLI refreshes the bundled plot-cli agent skill when ~/.plot/skills.json has autoUpdate: "always". Run plot setup to configure the installed agents, install scope, and auto-update preference. The setup flow writes skill files beneath detected roots such as ~/.claude/skills/plot-cli, ~/.agents/skills/plot-cli, and ~/.cursor/skills/plot-cli; missing or unwritable roots are skipped without failing the command.

In CI or batch automation loops, set PLOT_CLI_SKIP_UPDATE_CHECK=1 to suppress the background check entirely.

Security Notes

• Personal access tokens and OAuth credentials grant access to Plot workspace data. Do not paste them into prompts, logs, comments, or issues.
• plot help identifiers prints URL parsing examples. Check copied links before sharing output externally.