polylane-cli

Polylane CLI — Agent Skill Guide

polylane wraps the Polylane platform with agent-friendly commands. Top-level commands map to tasks an agent actually performs; the full API surface is available under polylane api as an escape hatch.

This file teaches the contracts and workflows; it deliberately lists no command inventory. Help is authoritative — it reflects the installed version:

polylane --help                                  # resource list
polylane <resource> --help                       # verbs for a resource
polylane <resource> <verb> --help                # flags + examples for one command

For anything not a first-class command:

polylane api list [--tag <Tag>] [--query <q>]    # every operation
polylane api describe <operation-id>             # its shape
polylane api call <operation-id> [--body '{...}' | --body-file path]

Concepts, schemas, and limits: https://docs.polylane.com (model-readable, no auth; index at /llms.txt).

Prerequisites

# Install the reviewed CLI version (Node.js 20 or later)
npm install -g @coreplane/polylane@0.2.48

# Auth — OAuth is the default; API key where a browser is impossible
polylane auth login                                    # OAuth browser (PKCE)
polylane auth login --no-browser                       # device code (SSH / headless)
polylane auth login --api-key sk_xxxxx                 # scripts / CI
polylane auth signup --email <email> [--password <pw>] # new account (emails a 6-digit code); omit --password to get a generated one, shown once
polylane auth signup --email <email> --code <code>     # finish verification non-interactively
polylane auth status                                   # verify

# Workspace — set once, then forget
polylane workspace use <workspace-id-or-slug>
polylane workspace create --name "My Workspace"        # new + makes default

API keys persist to ~/.polylane/config.json; OAuth and signup session tokens to ~/.polylane/credentials.json (auto-refresh). For long-lived agent access after signup, create an API key and switch to it with polylane auth logout --yes && polylane auth login --api-key <key>: the global --api-key flag and POLYLANE_API_KEY outrank stored session tokens, but the config-file key saved by auth login --api-key does not. Account lifecycle beyond signup/login lives in the web console.

Config precedence: flags > env vars (POLYLANE_API_KEY, POLYLANE_WORKSPACE_ID, POLYLANE_OUTPUT, …) > ~/.polylane/config.json > defaults. Full variable list: https://docs.polylane.com/tools/cli/configuration. Telemetry: polylane telemetry status / disable, or DO_NOT_TRACK=1.

Agent Flags

Combine for non-interactive (agent / CI) contexts:

Flag	Purpose
`--non-interactive`	Fail fast on missing args instead of prompting
`--quiet`	Suppress spinners — stdout stays pure data
`--output json`	Force JSON regardless of TTY state (JSON is already the default when stdout is piped)
`--full`	Disable narrow projection on list commands
`--no-wait`	Fire-and-forget on `thread ask` / `continue`
`--yes`	Skip destructive-action confirmation prompts
`--dry-run` / `--verbose`	Preview the request / log HTTP traffic
`--api-key` / `--workspace` / `--timeout`	Per-call overrides

Contracts

stdout is pure data (JSON, table rows, streamed tokens, URLs — safe to pipe); stderr carries progress, hints, and errors. Errors print Error: <message> + Hint: <how to fix it, often the exact command>; in JSON mode: {"error": {"code", "message", "hint"}} on stderr, where code is the exit code and hint is omitted when there is none.

Exit codes (stable — branch on $?): 0 success · 1 general · 2 usage · 3 auth · 4 rate limit / plan limit · 5 timeout · 6 network · 7 pending (AWS stack still creating, or a plan upgrade still finishing) · 130 interrupted.

API objects carry _html_url (console deep link) and _links (next-step operations) — rendered as a Console: / Next: footer on single objects, kept raw in JSON mode.

Core Workflows

Investigating an issue

polylane issue list --active                      # what's currently flagged
polylane issue show <issue-id>                    # full body + linked investigation
polylane feed list --category change --since 24h  # what changed recently
polylane service find "<query>"                   # locate the service
polylane service logs <service-id> --since 1h --grep error
polylane service metrics <service-id> --since 1h
polylane service graph <service-id> --direction both --depth 1
polylane repo grep <owner/repo> "<pattern>"       # correlate with code
polylane issue note <issue-id> "<what you did>"   # record as you go
polylane memory save "<confirmed finding>"        # teach future runs

Onboarding

polylane integration catalog                      # discover what can connect
polylane integration connect --type <type>        # per-type flags: see --help
polylane cloud connect --provider <provider>      # per-provider flags: see --help
polylane integration list && polylane cloud list && polylane service list   # verify

Running agent tools directly

The same tools Polylane's own agent uses — telemetry queries across every connected provider, graph traversal, code search — without opening a thread:

polylane tools search "<capability>" [--full]      # discover (+ JSON schemas)
polylane tools run <name> --params '{...}'
polylane tools code 'async () => { return await tools.findNodes({ query: "api" }); }'

Read-only by default; writes need a credential with the agent_tools:write scope plus --write.

Talking to the agent

polylane thread ask "<prompt>" [--context <ids>]   # blocking, streams the reply to stdout in text mode; ids typed by prefix (repo_, acc_, thrd_, mem_; anything else is a resource node)
TID=$(polylane thread ask "<prompt>" --no-wait --output json --quiet | jq -r '.id')
polylane thread continue "$TID" "<follow-up>"

Wiring coding agents

polylane setup [--agent claude|cursor|opencode|codex|…] [--project] registers the MCP server (https://mcp.polylane.com/mcp) in each detected (or named) agent's config, and installs this skill as skills/polylane-cli/SKILL.md for agents that load skills (claude, cursor, opencode, codex, pi, warp). Idempotent.

Gotchas No Help Text Confesses

Browser-flow connects (integration connect, cloud connect for OAuth-style providers) print the URL to stdout. In an interactive terminal they then poll until the connection appears (about 5 min; 15 for AWS): a timeout exits 1, Ctrl+C exits 0 while setup continues in the browser. With --output json, --non-interactive, --dry-run, or no TTY they exit 0 as soon as the URL is printed. Either way, re-query with list / show to confirm.
Partial success still exits 0: connect-style operations can return { accounts: [...], failures: [...] } — inspect failures.
--since means two things: a duration string (1h, 7d) on service logs / service metrics / feed, but unix milliseconds on issue list (as are --from / --to everywhere).
Destructive commands are inconsistent when non-interactive: cloud disconnect / integration disconnect exit 2 without --yes, but memory delete, note delete, artifact delete and auth logout proceed without asking. A cancelled confirmation exits 0 with Cancelled. Nothing changed. on stderr.
auth signup is idempotent for an existing user with a matching password — safe to re-run to renew a session.
thread ask / continue wait at most 10 minutes: on timeout they still exit 0 (JSON status: "pending") — follow up with polylane thread show <id>. --stream is deprecated and does nothing.