polylane-cli

Polylane CLI — Agent 技能指南

polylane 为 Polylane 平台提供了一组便于 Agent 使用的命令。顶层命令对应 Agent 实际会执行的任务；如需使用完整的 API 功能，可通过 polylane api 访问。

本文介绍各项约定和工作流；有意不列出命令清单。帮助信息最具权威性——它反映了已安装的版本：

polylane --help                                  # resource list
polylane <resource> --help                       # verbs for a resource
polylane <resource> <verb> --help                # flags + examples for one 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]

概念、架构和限制：https://docs.polylane.com（可供模型阅读，无需身份验证；索引位于 /llms.txt）。

前提条件

# Install the reviewed CLI version (Node.js 20 or later)
npm install -g @coreplane/[email protected]

# 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 密钥会保存到 ~/.polylane/config.json；OAuth 和注册会话令牌会保存到 ~/.polylane/credentials.json（自动刷新）。注册后，如需长期供 Agent 访问，请创建 API 密钥，并通过 polylane auth logout --yes && polylane auth login --api-key <key> 切换到该密钥：全局 --api-key 标志和 POLYLANE_API_KEY 的优先级高于已保存的会话令牌，但通过 auth login --api-key 保存到配置文件的密钥不具备此优先级。注册/登录之外的账户生命周期管理请在 Web 控制台中进行。

配置优先级：标志 > 环境变量（POLYLANE_API_KEY、POLYLANE_WORKSPACE_ID、POLYLANE_OUTPUT 等）> ~/.polylane/config.json > 默认值。完整变量列表：https://docs.polylane.com/tools/cli/configuration。遥测：使用 polylane telemetry status / disable，或设置 DO_NOT_TRACK=1。

Agent 标志

在非交互式（Agent / CI）环境中可组合使用：

标志	用途
--non-interactive	缺少参数时立即失败，而不是提示输入
--quiet	不显示加载动画 — stdout 保持为纯数据
--output json	无论 TTY 状态如何，都强制输出 JSON（stdout 被管道重定向时，默认已是 JSON）
--full	关闭列表命令中的精简投影
--no-wait	对 thread ask / continue 执行即发即弃
--yes	跳过破坏性操作确认提示
--dry-run / --verbose	预览请求 / 记录 HTTP 流量
--api-key / --workspace / --timeout	按次调用覆盖设置

约定

stdout 只输出纯数据（JSON、表格行、流式令牌、URL — 可安全用于管道）；stderr 输出进度、提示和错误。错误会打印 Error: <message> + Hint: <how to fix it, often the exact command>；JSON 模式下，stderr 会输出 {"error": {"code", "message", "hint"}}，其中 code 为退出码，没有提示时会省略 hint。

退出码（稳定 — 根据 $? 分支处理）：0 成功 · 1 一般错误 · 2 用法错误 · 3 身份验证错误 · 4 速率限制 / 计划限制 · 5 超时 · 6 网络错误 · 7 待处理（AWS 堆栈仍在创建，或计划升级仍在完成）· 130 已中断。

API 对象包含 _html_url（控制台深层链接）和 _links（后续操作）— 单个对象会渲染为 Console: / Next: 页脚；JSON 模式下则保留原始字段。

核心工作流

调查问题

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

入门设置

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

直接运行 Agent 工具

无需打开对话线程，即可使用 Polylane 自有 Agent 使用的相同工具 — 跨所有已连接提供方查询遥测、遍历图谱、搜索代码：

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

默认只读；写入操作需要具有 agent_tools:write 范围的凭据，并加上 --write。

与 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>"

配置编码 Agent

polylane setup [--agent claude|cursor|opencode|codex|…] [--project] 会在每个检测到的（或指定的）Agent 配置中注册 MCP 服务（https://mcp.polylane.com/mcp），并为会加载技能的 Agent（claude、cursor、opencode、codex、pi、warp）将此技能安装为 skills/polylane-cli/SKILL.md。该操作可重复执行，不会造成重复配置。

文档未提及的注意事项

• 浏览器流程连接（OAuth 风格提供商使用 integration connect、cloud connect）会将 URL 输出到标准输出。在交互式终端中，随后会轮询，直到连接出现（约 5 分钟；AWS 为 15 分钟）：超时会以状态码 1 退出；按 Ctrl+C 会以状态码 0 退出，同时浏览器中的设置仍会继续。使用 --output json、--non-interactive、--dry-run 或没有 TTY 时，只要输出 URL 就会以状态码 0 退出。无论哪种情况，都应使用 list / show 重新查询以确认。
• 部分成功仍以状态码 0 退出：连接类操作可能会返回 { accounts: [...], failures: [...] } — 请检查 failures。
• --since 有两种含义：在 service logs / service metrics / feed 中表示时长字符串（1h、7d），但在 issue list 中表示 Unix 毫秒数（--from / --to 在所有命令中也是如此）。
• 非交互模式下，破坏性命令的行为不一致：cloud disconnect / integration disconnect 未指定 --yes 时会以状态码 2 退出，但 memory delete、note delete、artifact delete 和 auth logout 会直接执行，不会询问。取消确认时会以状态码 0 退出，并在标准错误中显示 Cancelled. Nothing changed.。
• 对于密码匹配的现有用户，auth signup 具有幂等性 — 可以安全地重新运行以续订会话。
• thread ask / continue 最多等待 10 分钟：超时后仍会以状态码 0 退出（JSON status: "pending"）— 请使用 polylane thread show <id> 跟进。--stream 已弃用，不会产生任何作用。