capigo-api

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Capigo CLI operator

Capigo CLI 操作指南

Use

capigo

as the normal interface to Capigo. The installed binary is self-documenting and the Public API will continue to grow, so this skill teaches a discovery workflow rather than duplicating the command tree or API reference.

将

capigo

作为与 Capigo 交互的常规接口。已安装的二进制文件自带说明，且 Public API 会继续扩展，因此本 skill 讲授的是一套发现工作流，而不是复制命令树或 API 参考。

1. Preflight the environment and authentication

1. 预检环境与身份验证

Start each new environment or session by resolving the executable with the shell's native lookup (

command -v capigo

in a POSIX shell or

Get-Command capigo

in PowerShell), then run:

bash

capigo version

Use the resolved executable consistently for version, help, preflight, and execution; mixing help from one build with commands sent through another produces false flag and capability errors.

If the shell cannot find

capigo

Inspect the OS, architecture, shell, and available package managers using read-only checks.
Tell the user that the Capigo CLI is not installed and recommend the official installation guide: https://github.com/vtech-com/capigo-api-sdk#installation.
Prefer the installation path that fits the detected machine. For example, when Homebrew is present, suggest
```
brew install --cask vtech-com/tap/capigo
```
; the guide also covers GitHub Releases and Go-based installation with their platform-specific caveats.
Do not install software or change the machine merely because the binary is missing. Wait for the user's authorization, then verify the result with
```
capigo version
```
.

After the version check succeeds, run the read-only authentication and connectivity probe:

bash

capigo health

Interpret it by exit code and its stdout

error

object:

Exit
```
0
```
: the API is reachable and the configured key was accepted. Continue.
Exit
```
2
```
: the key is missing, malformed, or rejected. Run
```
capigo auth login --help
```
, tell the user to create or retrieve their key while signed in at https://platform.capigo.app, and ask them to run the supported login command locally. Then retry
```
capigo health
```
. Code
```
AUTH_MISSING_HEADER
```
is the first-run case — no key is configured at all, so the CLI never reached the API. Nothing about it is transient: do not retry until the user has logged in.
Exit
```
6
```
: connectivity failed. Diagnose DNS, network access, or the configured API URL; do not mislabel it as an authentication problem or ask the user to log in again.
Any other non-zero exit: read the error object and
```
capigo help exit-codes
```
before recommending a recovery step.

Do not use

capigo auth whoami

as a preflight. Its

/me

route is not implemented, so a 404 does not say whether the configured key is valid.

Authentication secrets belong to the user. Never ask them to paste an API key into chat, inspect credential files or environment variables to recover it, print it, place it in examples, or expose it through shell tracing. Guide the user through

capigo auth login --help

and let them enter the key locally through the supported flow.

每个新环境或新会话开始时，使用 shell 的原生查找机制解析可执行文件（POSIX shell 中为

command -v capigo

，PowerShell 中为

Get-Command capigo

），然后运行：

bash

capigo version

版本检查、帮助、预检和执行操作都应使用同一个已解析的可执行文件；将一个构建版本的帮助与另一个构建版本执行的命令混用，会产生错误的参数和能力报错。

如果 shell 找不到

capigo

：

使用只读检查查看操作系统、架构、shell 和可用的包管理器。
告知用户 Capigo CLI 尚未安装，并推荐官方安装指南：https://github.com/vtech-com/capigo-api-sdk#installation。
优先选择适合所检测机器的安装方式。例如，存在 Homebrew 时，建议使用
```
brew install --cask vtech-com/tap/capigo
```
；指南还介绍了 GitHub Releases 和基于 Go 的安装方式及其平台特定注意事项。
不要仅仅因为二进制文件缺失就安装软件或更改机器配置。等待用户授权，然后使用
```
capigo version
```
验证结果。

版本检查成功后，运行只读的身份验证和连通性探测：

bash

capigo health

根据退出码及其 stdout 中的

error

对象进行判断：

退出码为
```
0
```
：API 可以访问，且已配置的密钥已获接受。可以继续。
退出码为
```
2
```
：密钥缺失、格式错误或被拒绝。运行
```
capigo auth login --help
```
，告知用户登录 https://platform.capigo.app 后创建或获取密钥，并请其在本机运行受支持的登录命令。然后重试
```
capigo health
```
。代码
```
AUTH_MISSING_HEADER
```
表示首次使用场景——尚未配置任何密钥，因此 CLI 根本没有到达 API。这不是瞬时问题：在用户登录之前不要重试。
退出码为
```
6
```
：连接失败。诊断 DNS、网络访问或已配置的 API URL；不要将其误判为身份验证问题，也不要再次要求用户登录。
其他任何非零退出码：读取错误对象和
```
capigo help exit-codes
```
，然后再建议恢复步骤。

不要将

capigo auth whoami

用作预检。它的

/me

路由尚未实现，因此返回 404 并不能说明已配置的密钥是否有效。

身份验证机密信息归用户所有。绝不要要求用户在聊天中粘贴 API 密钥，不要检查凭据文件或环境变量来恢复密钥，不要打印密钥，不要将其放入示例，也不要通过 shell trace 暴露密钥。应引导用户查看

capigo auth login --help

，并让用户通过受支持的流程在本机输入密钥。

A key reaches one workspace

一个密钥对应一个工作区

A key is bound to the single workspace it was created in; the platform's API keys page shows which. That bound is enforced server-side on every request, so it holds regardless of what the CLI sends:

Naming another workspace —
```
--tenant
```
,
```
CAPIGO_TENANT
```
, or a
```
default_tenant
```
that belongs to a different key — fails with exit
```
3
```
. The key is valid; the workspace is not its own.
Naming none does not widen the call. The request still reads only the key's workspace, and
```
meta
```
names no tenant, because the CLI reports the tenant it resolved and it resolved none. If the user needs to know which workspace an answer belongs to, pass the key's own workspace as
```
--tenant
```
: same rows, and
```
meta.tenant
```
appears.
```
capigo tenants list
```
is not this key's reach. It lists the workspaces the account belongs to and is not narrowed to the key, so treat it as a directory of the account, never as the set of workspaces the current key can be pointed at.
Older keys may carry no workspace and reach every workspace the account has. Do not infer a key's reach from its prefix or age; take it from the API keys page, or from the exit code of the call you were about to make.

Working in several workspaces therefore takes one key each — one profile per key, or

CAPIGO_API_KEY

and

CAPIGO_TENANT

set per invocation. There is no

--profile

flag, and no command creates a profile: a second one is a hand edit of

~/.capigo/config.json

密钥与其创建时所属的单个工作区绑定；平台的 API 密钥页面会显示该绑定关系。服务端会在每次请求中强制执行此绑定，因此无论 CLI 发送什么内容，该规则都成立：

指定另一个工作区——通过
```
--tenant
```
、
```
CAPIGO_TENANT
```
，或使用属于其他密钥的
```
default_tenant
```
——会触发退出码
```
3
```
。密钥本身有效，但该工作区不属于此密钥。
不指定工作区不会扩大调用范围。请求仍只会读取密钥所属工作区的数据，并且
```
meta
```
不会列出 tenant，因为 CLI 会报告其解析出的 tenant，而此次没有解析出任何 tenant。如果用户需要知道答案属于哪个工作区，请将密钥自身所属的工作区作为
```
--tenant
```
传入：返回的数据行相同，并且会出现
```
meta.tenant
```
。
```
capigo tenants list
```
不代表当前密钥的可访问范围。它会列出账户所属的工作区，并不会按当前密钥进行筛选。因此应将其视为账户目录，而不能视为当前密钥可以指向的工作区集合。
较旧的密钥可能未绑定工作区，并能访问该账户拥有的所有工作区。不要根据密钥前缀或新旧程度推断其访问范围；应从 API 密钥页面获取，或通过即将执行的调用所返回的退出码判断。

因此，在多个工作区中工作时，每个工作区需要一个密钥——每个密钥对应一个 profile，或在每次调用时分别设置

CAPIGO_API_KEY

和

CAPIGO_TENANT

。不存在

--profile

参数，也没有用于创建 profile 的命令：要添加第二个 profile，需要手动编辑

~/.capigo/config.json

。

2. Discover the live command surface

2. 发现当前可用的命令界面

Once

capigo version

succeeds, use built-in help progressively:

bash

capigo --help
capigo <group> --help
capigo <group> <command> --help

Read only the group and command relevant to the user's intent. A runnable command page includes its purpose, usage, flags, constraints, examples, and output. Do not reconstruct a command from memory, guess a flag, or treat this skill as a command inventory.

Pull cross-cutting contracts from the binary when they matter:

bash

capigo help tenancy
capigo help output
capigo help exit-codes
capigo help soft-delete
capigo help versioning

The installed help wins for CLI spelling and behavior because it ships with that exact build. If help and this skill disagree, follow help and report the mismatch for the skill maintainer.

capigo version

成功后，逐步使用内置帮助：

bash

capigo --help
capigo <group> --help
capigo <group> <command> --help

只读取与用户意图相关的命令组和命令。可执行命令的帮助页面包含其用途、用法、参数、限制、示例和输出。不要凭记忆重构命令，不要猜测参数，也不要将本 skill 视为命令清单。

需要时，从二进制文件中获取跨领域的通用约定：

bash

capigo help tenancy
capigo help output
capigo help exit-codes
capigo help soft-delete
capigo help versioning

应以已安装版本的帮助为准，因为它是与该确切构建版本一同发布的。如果帮助内容与本 skill 存在冲突，应遵循帮助内容，并向 skill 维护者报告该不一致。

3. Plan, execute, and verify

3. 规划、执行并验证

Before a call:

Translate the request into one mechanical Capigo intent.
Discover the group and command from help.
Read the leaf command's help before constructing flags or JSON.
Resolve the tenant. If a write's tenant is ambiguous, ask before writing. Do not add a redundant confirmation when the user already authorized the exact resource, change, and tenant. Task creation still follows the separate assignee-choice gate below. Remember that a key is bound to one workspace: on a write, name that workspace explicitly rather than letting the default carry it, so
```
meta.tenant
```
is on stdout to verify afterwards.
Use the conventions in
```
references/cli-conventions.md
```
.

After a call:

Parse the single JSON document on stdout.
Check for an
```
error
```
key before trusting
```
data
```
; partial results can contain both.
On writes, verify
```
meta.tenant
```
and the returned object rather than assuming the intended tenant or mutation was used.
Report the result without exposing credentials, raw auth headers, or unrelated tenant data.

调用前：

将请求转换为单个明确且可机械执行的 Capigo 意图。
通过帮助发现相应的命令组和命令。
在构造参数或 JSON 之前，阅读叶子命令的帮助。
确定 tenant。如果写入操作的 tenant 不明确，应在写入前询问。当用户已经明确授权具体资源、变更和 tenant 时，不要重复确认。任务创建仍须遵循下方单独的受派人选择门槛。请记住密钥仅绑定一个工作区：执行写入操作时，应明确指定该工作区，而不是让默认值隐式决定，以便随后通过 stdout 中的
```
meta.tenant
```
进行验证。
遵循
```
references/cli-conventions.md
```
中的约定。

调用后：

解析 stdout 中的单个 JSON 文档。
信任
```
data
```
之前先检查是否存在
```
error
```
键；部分结果可能同时包含两者。
对于写入操作，验证
```
meta.tenant
```
和返回的对象，不要想当然地认为使用了预期 tenant 或完成了预期变更。
报告结果时，不要暴露凭据、原始身份验证标头或与当前操作无关的 tenant 数据。

4. Handle missing commands and failures

4. 处理命令缺失和故障

If an expected command is absent, re-check the root and relevant group help. A name you guessed is not evidence that the capability is unavailable. The operation may live under a neighboring group, or the installed CLI may be older than the current API.

If a command fails:

Read the stdout
```
error
```
object, especially
```
message
```
,
```
next
```
,
```
request_id
```
, and any
```
capability_note
```
.
Read the leaf command help and
```
capigo help exit-codes
```
.
Use
```
--verbose
```
only when the redacted HTTP trace is actually needed.
Retry only when the error class supports it, such as a transient network or rate-limit response. Do not retry validation, auth, permission, conflict, or ambiguous write outcomes blindly.

A failed write does not prove the API lacks the capability. Do not invent destructive recovery steps such as recreating resources, changing identifiers, or bypassing tenant handling.

如果预期命令不存在，请重新检查根帮助和相关命令组帮助。猜测的命令名并不能证明该能力不可用。该操作可能位于相邻命令组中，或者已安装的 CLI 版本早于当前 API。

如果命令执行失败：

读取 stdout 中的
```
error
```
对象，尤其要关注
```
message
```
、
```
next
```
、
```
request_id
```
和
```
capability_note
```
。
阅读叶子命令帮助和
```
capigo help exit-codes
```
。
只有在确实需要经过脱敏的 HTTP trace 时才使用
```
--verbose
```
。
仅当错误类型支持重试时才重试，例如瞬时网络错误或限流响应。不要盲目重试验证、身份验证、权限、冲突或结果不明确的写入操作。

写入失败并不能证明 API 缺少相应能力。不要擅自采取破坏性的恢复步骤，例如重新创建资源、修改标识符或绕过 tenant 处理。

5. Use the Public API specification sparingly

5. 谨慎使用 Public API 规范

Public specification: https://platform.capigo.app/api/openapi

For ordinary user operations, stop at CLI help and execute through

capigo

. Open the spec only when at least one of these is true:

the user explicitly asks about the Public API contract or is building an integration;
you are developing or reviewing this SDK;
live help confirms a CLI gap and you need to distinguish "not exposed by this CLI" from "not present in the Public API";
a version mismatch or inaccurate help/spec claim must be diagnosed.

When inside the SDK repository, prefer its versioned

api/openapi.json

for the release being worked on; use the public URL to check the currently published contract. The spec defines API paths and schemas, not the installed CLI's flag spelling. Finding an endpoint in the spec does not authorize bypassing the CLI for a routine tenant operation. Report the gap or recommend an upgrade. Call raw HTTP only when the user's task is explicitly to build or test a Public API integration and that work is separately authorized.

Public API 规范：https://platform.capigo.app/api/openapi

对于常规用户操作，应止步于 CLI 帮助并通过

capigo

执行。仅在满足以下至少一项条件时才打开规范：

用户明确询问 Public API 契约或正在构建集成；
正在开发或审查此 SDK；
当前帮助确认 CLI 存在能力缺口，需要区分"此 CLI 未公开"与"Public API 中不存在"；
必须诊断版本不匹配或帮助/规范声明不准确的问题。

在 SDK 仓库中，应优先使用当前开发版本对应的版本化

api/openapi.json

；使用公共 URL 检查当前已发布的契约。规范定义的是 API 路径和数据模式，而不是已安装 CLI 的参数拼写。在规范中找到某个端点，并不代表可以绕过 CLI 执行常规 tenant 操作。应报告能力缺口或建议升级。只有当用户的任务明确是构建或测试 Public API 集成，并且已单独获得授权时，才能调用原始 HTTP。

6. Load special-case guidance only when needed

6. 仅在需要时加载特殊指导

Most operations need no bundled domain guide: leaf help is sufficient.

For an operation that creates, traverses, or changes a relationship, load only the relevant domain reference after reading leaf help:

```
references/domains/products.md
```
for products, variants, product references, and product properties (
```
capigo property-definitions
```
);
```
references/domains/tasks.md
```
for tasks, assignees, subtasks, comments and mentions, and labels (
```
--label
```
,
```
capigo labels list
```
);
```
references/domains/boards.md
```
when placing a task on a board or list, or reading a board by code;
```
references/domains/wms.md
```
for anything under
```
capigo wms
```
: warehouses, locations, availability, and the four stock documents.

For product creation, and for any write to

properties

or a property definition, read

products.md

after the leaf help. For task or subtask creation, or for posting a comment, read

tasks.md

after the relevant leaf help; read

boards.md

as well only for board placement. For any

capigo wms

write, and for reporting a WMS read to the user, read

wms.md

: its verdicts, null costs, and statuses are easy to report wrongly. Do not load a domain reference for unrelated listing or search work.

大多数操作不需要额外加载领域指南：叶子命令帮助已经足够。

对于创建、遍历或更改关系的操作，应在阅读叶子命令帮助后，仅加载相关领域参考：

references/domains/products.md

：产品、变体、产品引用和产品属性（

capigo property-definitions

）；

```
references/domains/tasks.md
```
：任务、受派人、子任务、评论和提及，以及标签（
```
--label
```
、
```
capigo labels list
```
）；
```
references/domains/boards.md
```
：将任务放置到看板或列表，或按代码读取看板；
```
references/domains/wms.md
```
：所有
```
capigo wms
```
操作，包括仓库、库位、可用库存和四种库存单据。

创建产品，以及对

properties

或属性定义执行任何写入操作时，应在阅读叶子命令帮助后读取

products.md

。创建任务或子任务，或者发布评论时，应在阅读相关叶子命令帮助后读取

tasks.md

；只有在涉及看板放置时，才同时读取

boards.md

。对于任何

capigo wms

写入操作，以及向用户报告 WMS 查询结果时，应读取

wms.md

：其中的 verdicts、null costs 和 statuses 很容易被错误汇报。对于无关的列表或搜索操作，不要加载领域参考。

Scope boundary

范围边界

This skill covers Capigo CLI operation and Public API discovery. It does not define an organization's product-code, barcode, naming, approval, or data-governance policies. Apply those from the user's own policy or a separate organization-specific skill.

本 skill 涵盖 Capigo CLI 操作和 Public API 发现，但不定义组织的产品编码、条形码、命名、审批或数据治理策略。应从用户自身的政策或单独的组织专用 skill 中应用这些规则。