CLI
The Plenar CLI connects your repo to a Plenar project and configures Claude Code automatically. It handles authentication, MCP setup, CLAUDE.md instructions, and agent hooks in one flow.
For day-to-day work, use the MCP integration through Claude Code. The CLI is for setup and connection management.
Installation
npm install -g @plenarapp/cliCommands
plenar connect
Connect this repo to a Plenar project. Opens your browser to authenticate, then:
- Signs you in via OAuth
- Lists your projects and lets you pick one
- Writes
.mcp.jsonwith the MCP endpoint and API token - Updates
CLAUDE.mdwith Plenar workflow instructions - Adds agent coordination hooks to
.claude/settings.json - Detects GitHub repo and links it (if applicable)
plenar connectIf a connection already exists, you are prompted to keep it, switch to a different user/project, or disconnect.
Files created or modified:
| File | What it does |
|---|---|
.mcp.json | MCP server config with Plenar endpoint and auth token |
CLAUDE.md | Workflow instructions (start task, complete task, report blocker, link artifacts) |
.claude/settings.json | Agent coordination hooks |
--key <pko_...> — org-key mode. Connect using an organization-level API key instead of OAuth. Use this for CI/CD pipelines or service principals that operate across multiple projects with one credential:
plenar connect --key pko_abc123...The CLI validates the token, writes .mcp.json with org-key mode enabled, and skips the project picker. Org keys span the whole organization (or the projects in their allowlist) and require every MCP call to specify project_id explicitly. Generate org keys from Settings → Authentication → API Keys in the dashboard. See the two-project workflow for the full flow.
--write-config / --no-write-config — control .mcp.json writes. When PLENAR_TOKEN is set in the environment, pass --write-config to force connect to write .mcp.json anyway, or --no-write-config to skip writing it and rely on the env token alone (env-only auth):
plenar connect --write-config
plenar connect --no-write-configplenar disconnect
Remove all Plenar configuration from this repo. Revokes the API token and deletes the config files created by connect.
plenar disconnect
plenar disconnect --globalFiles removed:
- Plenar entry from
.mcp.json - Plenar workflow section from
CLAUDE.mdandAGENTS.md - Agent hooks from
.claude/settings.json - Slash commands, skills, and statusline from
.claude/
--global removes only the global hook, statusline, slash-command, and skills config from ~/.claude/. It leaves project-local files and the token untouched.
Plain plenar disconnect revokes the API token. A --global or org-key disconnect does not revoke the token — an org key may still be wired into other worktrees that need it.
plenar status
Show the current connection status: user, project, and whether the token is valid.
plenar status
plenar status --json--json writes machine-readable JSON to stdout (human-readable output goes to stderr) for scripting.
Output: Connected user email, project name, token validity, signal freshness. Returns a non-zero exit code if not connected or token is expired.
plenar refresh
Re-write the bundled agent artifacts — hooks, slash commands, statusline, skills, and the CLAUDE.md/AGENTS.md workflow blocks — from the locally installed CLI. It does not download anything from a server and does not touch .mcp.json, so active sessions keep their connection. New hooks, statusline, and slash commands apply on the next session start.
plenar refresh
plenar refresh --global--global writes hooks, statusline, slash commands, and skills to ~/.claude/ so every Claude Code session inherits them regardless of directory. It skips the per-project CLAUDE.md/AGENTS.md files and leaves .mcp.json alone.
Use after upgrading the CLI to a version that ships new agent features, or when your local .claude/ config has drifted.
plenar tail
Stream live signals (commits, deploys, test runs) from your project in real time. By default it starts from now and streams forward, like tail -f.
plenar tail
plenar tail --type commit.created --task PLEN-42| Flag | Description |
|---|---|
--type <type> | Filter to one signal type (e.g. commit.created, deploy.completed) |
--task <key> | Filter to one task |
--source <source> | Filter to one signal source |
--since <ISO> | Start from a timestamp instead of now (--since 1970-01-01 replays all history) |
--json | Emit raw JSON lines (no formatting) |
--interval <ms> | Poll interval in milliseconds (default 2000, clamped 500–30000) |
--max <n> | Stop after printing n signals |
--quiet | Suppress status and heartbeat lines |
Useful for watching engineering activity as it happens. Press Ctrl+C to stop.
plenar signal
Emit an engineering signal manually. Used when no automatic emitter covers your case.
plenar signal emit --type <signal-type> [--key value ...]
plenar signal commit| Subcommand | Emits | Notes |
|---|---|---|
commit | commit.created | Reads the current HEAD via git |
task-start | intent.task.started | Requires --task-id |
task-complete | intent.task.completed | Requires --task-id |
token-usage | token.usage | Requires --input, --output, --model |
ci-result | ci.completed (or deploy.completed with --environment) | Requires --status |
deploy | deploy.completed | Requires --status; feeds DORA metrics |
emit | any type | Requires --type; remaining --key value pairs become payload fields |
For emit, numeric-looking values are coerced to numbers, and branch + SHA auto-fill from git. See Insights for what signals power.
plenar doctor
Diagnose common configuration issues: token validity, MCP reachability, file permissions, hook installation.
plenar doctorRun this when something is not working. It checks each component and reports what needs fixing.
plenar export
Export your plan (tasks, goals, milestones) to stdout as markdown or CSV.
plenar export
plenar export --format csv
plenar export --goal "Launch v1" --milestone "Checkout"| Flag | Description |
|---|---|
--format md|csv | Output format (default markdown) |
--goal <filter> | Limit to goals matching a title substring or ID |
--milestone <filter> | Limit to a milestone by title or ID |
Redirect stdout to a file to save it: plenar export --format csv > plan.csv.
plenar import
Import tasks from CSV or Jira. Imported tasks land as a preview — review and apply them from the dashboard before they enter the plan.
plenar import --source csv --file tasks.csv
plenar import --source jira --site https://your-site.atlassian.net --project-key PROJ| Flag | Description |
|---|---|
--source csv|jira | Import source (default csv) |
--file <path> | Path to the CSV file (required for CSV import) |
--site <url> | Jira site URL (required for Jira) |
--project-key <key> | Jira project key (required for Jira) |
--api-token <token> | Jira API token (or set JIRA_API_TOKEN) |
--email <email> | Jira account email (or set JIRA_EMAIL) |
CSV columns: title and estimate_days are required; scope, milestone, depends_on, and description are optional.
plenar run
Wrap any command, emitting a session.started signal before it runs and a session.ended signal after it exits. The wrapped command’s output and exit code pass through unchanged; if Plenar is not connected, the signals are silently dropped and the command still runs.
plenar run <cmd> [args...]Use it to attach Plenar session telemetry to non-MCP agents:
plenar run codex "refactor the auth module"
plenar run aider --message "add tests"Options
| Flag | Description |
|---|---|
-h, --help | Show help |
-v, --version | Show version |
Environment variables
| Variable | Description |
|---|---|
PLENAR_TOKEN | Bearer token for non-interactive use (plt_… or pko_…). Takes precedence over .mcp.json on signal, tail, and run. |
PLENAR_API_URL | Override the API base URL (default https://dashboard.plenar.app). |
PLENAR_TIMEOUT_MS | HTTP timeout in milliseconds for CI-targeted commands (default 10000). |
Authentication flow
The CLI uses browser-based OAuth — no API tokens to copy/paste manually.
plenar connectgenerates a one-time auth code- Opens your browser to
dashboard.plenar.appwhere you sign in - The browser confirms the auth code
- The CLI exchanges the code for a personal API token
- The token is stored locally in
.mcp.json
The token has Planner role and can access all projects in your organization. To pin a default project for MCP calls, use Settings → Profile → “Default project for AI agents” in the dashboard. To change the authenticated user, run plenar connect again.
Manual setup
If you cannot use the CLI (e.g., CI environments or air-gapped networks), see the manual configuration steps in the Connect Claude Code tutorial.