Octri CLI

Name: Octri CLI
Author: octri.dev

本地服务

octri.dev开发工具33 周前更新

代码仓库访问官网

关于 Octri CLI

Octri CLI 是用于管理 Octri 项目的命令行工具，可推送 OpenAPI 规范、生成 SDK、发布文档并处理生产错误。它也能通过 MCP 暴露相同操作，并为发布和删除提供显式权限控制。

主要功能

01推送 OpenAPI 规范
02构建并下载多语言 SDK
03发布文档及配置域名
04查看和处理监控错误
05支持 JSON 输出与 MCP 服务

适用场景

01在 CI 中构建并检查 SDK
02发布 API 文档并设置自定义域名
03排查生产错误并查看堆栈信息
04让 AI 助手通过 MCP 操作 API 项目

MCP 相关

`octri mcp serve` 通过 stdio 提供 MCP 服务，将 CLI 命令作为工具开放给客户端。发布和删除操作默认受限，可通过启动参数显式允许。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "dev-octri-cli": {
      "command": "npx",
      "args": [
        "-y",
        "@octri/cli"
      ],
      "env": {
        "OCTRI_API_KEY": "<OCTRI_API_KEY>",
        "OCTRI_PROJECT_ID": "<OCTRI_PROJECT_ID>",
        "OCTRI_PROFILE": "<OCTRI_PROFILE>",
        "HTTPS_PROXY": "<HTTPS_PROXY>",
        "NO_PROXY": "<NO_PROXY>"
      }
    }
  }
}

启动命令npx -y @octri/cli

需要配置的环境变量

OCTRI_API_KEY密钥Octri API key. Not needed if you have signed in with `octri auth login`.

OCTRI_PROJECT_IDProject to use when a tool call names none. Defaults to the CLI's selected project.

OCTRI_PROFILEStored CLI profile to use instead of the current one.

HTTPS_PROXY密钥Proxy for requests to Octri, e.g. http://proxy.internal:3128. Needed behind a corporate proxy, since MCP clients rarely pass your shell's environment through.

NO_PROXYComma-separated hosts that skip HTTPS_PROXY.

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

npm@octri/cli1.0.6stdio

工具

收录的工具列表 · 更新于 2 周前

参数	类型	必填	说明
project_id	string	否	项目 ID。可选；默认使用 CLI 当前选定的项目。

详细介绍

@octri/cli

octri 是 Octri 项目的命令行工具。它能完成仪表板的工作：推送规范、构建 SDK、发布文档，并处理这些 SDK 在生产环境中报告的错误。

Octri 接收 OpenAPI 规范，为你生成文档站点、十种语言的客户端库、MCP 服务，以及对整个 API 的监控。请参阅 octri.dev。

需要 Node 20 或更高版本。

安装

npm install -g @octri/cli
octri --help

从这里开始

octri auth login
octri projects use
octri specs push ./openapi.yaml

auth login 会提示你输入邮箱和密码；如果启用了双重身份验证，还会提示你输入身份验证器代码。不带参数运行 projects use 会打开选择器。

specs push 会等待整个流水线完成，而不只是等待上传完成。你的规范约一秒钟即可解析完成，随后会生成文档页面、搜索索引和更新日志。加载指示器会显示当前阶段。

构建 SDK

octri sdk audit                            # what is costing you, scored
octri sdk build --lang go,typescript --download

在终端中，sdk build 会为每种语言绘制一条进度轨道，并依次刷新显示 generating、verifying、packaging、installing 和 ready 状态。在管道中或 CI 环境下，它会改为输出只追加的行；如果任何一种语言构建失败，则以非零状态码退出，因此无需额外标志即可将其用作构建步骤。

sdk audit 会为规范评分，并标出生成器可以自行修复的问题。octri sdk audit apply <key> 会应用其中一项。

如需查看实际的生成器输出，又不想花费一次构建：

octri sdk preview --lang go
octri sdk preview --lang go --show client.go

发布文档

octri docs versions publish <specId>
octri docs versions label <specId> "Stable"
octri docs domain set docs.example.com

docs domain 会打印需要创建的 CNAME 和 TXT 记录，然后 docs domain verify 会检查这些记录。

监控

读取和分流操作会使用你的会话，因此只需登录即可：

octri monitoring summary
octri monitoring issues --status unresolved
octri monitoring issue <id>
octri monitoring resolve <id>

monitoring issue 会打印堆栈，并标出哪些帧已通过上传的源映射解析。如果没有任何帧解析成功，说明这些错误所属的版本没有符号，CLI 会明确告知。

两个上传命令的工作方式不同。它们使用摄取令牌直接与监控服务通信，因为 CI 作业只有一个机密，无法登录：

# CI
octri monitoring sourcemaps upload ./dist \
  --url "$MONITORING_URL" --token "$MONITORING_TOKEN" \
  --environment "$MONITORING_ENVIRONMENT" --release "$GIT_SHA"

# your own machine, already signed in
octri monitoring sourcemaps upload ./dist

运行 octri monitoring config，获取要保存为 CI 机密的三个值。你上传时使用的版本必须与 SDK 在运行时报告的版本一致，否则服务无法将跟踪与版本配对。

命令

分组	内容
`auth`	`login` · `logout` · `whoami` · `token` · `profiles`
`config`	`list` · `set <k> <v>` · `use <profile>` · `path`
`projects`	`list` · `show` · `create` · `use` · `current`
`specs`	`list` · `push <file\|->` · `import <url>` · `status` · `delete`
`sdk`	`languages` · `operations` · `settings get\|set` · `validate` · `audit` · `preview` · `build` · `builds` · `watch` · `artifacts` · `download` · `retry` · `publish` · `repos` · `stats`
`docs`	`pages [generate\|regenerate\|publish\|title]` · `show <slug>` · `guides` · `nav` · `versions` · `domain` · `changelog`
`monitoring`	`status` · `enable` · `summary` · `issues` · `issue <id>` · `resolve\|ignore\|reopen\|comment` · `logs` · `traces` · `performance` · `releases` · `alerts` · `checks` · `sourcemaps upload` · `sources upload` · `config`
`orgs`	`list` · `show` · `switch` · `usage` · `billing` · `invoices` · `members` · `invites`
`keys`	`list` · `create <name>` · `revoke <id>`
`github`	`status` · `connect <owner/repo>` · `sync` · `auto-sync <on\|off>`
`jobs`	`list` · `show <id>`
`mcp`	`tools` · `serve`

运行 octri <group> --help 可单独查看某个分组的帮助。

全局标志：--project <id>、--profile <name>、--api-url <url>、--json、 --quiet、--plain、--no-color。

输出

模式	适用场景	输出内容
交互式	终端中	彩色输出、加载指示器、实时构建进度轨道、表格
纯文本	输出到管道，或设置了 `CI`	只追加的行，无转义序列
`--json`	按需指定	stdout 输出一个 JSON 文档，stderr 输出错误

编写脚本时应使用 --json：

octri sdk builds --json | jq '.[0].status'
octri monitoring issues --status unresolved --json | jq 'length'

NO_COLOR 和 FORCE_COLOR 均受支持。

配置

状态保存在 ~/.octri/config.json 中，权限模式为 0600，因为其中包含会话令牌。设置 OCTRI_CONFIG_DIR 可更改其位置。

配置文件可并行保存多个环境：

octri config use prod --api-url api.octri.dev
octri config set defaultLanguages go,rust,swift

每个值都按标志、环境变量、存储的配置文件的顺序解析。

变量	作用
`OCTRI_PROFILE`	要使用的配置文件
`OCTRI_API_URL`	API 根地址（`local` 是 `:3001` 的简写）
`OCTRI_TOKEN`	Bearer 令牌，可绕过存储的会话
`OCTRI_API_KEY`	用于公共路由的 API 密钥
`OCTRI_PROJECT_ID`	默认项目
`OCTRI_CONFIG_DIR`	配置和构件缓存的存放位置
`OCTRI_DEBUG`	失败时打印堆栈跟踪

在代理后使用

CLI 和 octri mcp serve 会读取标准代理变量，支持大写或小写，无需额外的 Node 标志。https:// 请求会使用 HTTPS_PROXY；若只设置了 HTTP_PROXY，则使用它。列在 NO_PROXY 中的主机及其子域名会直接连接；* 会关闭代理。

export HTTPS_PROXY=http://user:[email protected]:3128
export NO_PROXY=localhost,127.0.0.1,corp.example
octri specs push ./openapi.yaml

如果代理使用自己的证书颁发机构检查 TLS，请通过 NODE_EXTRA_CA_CERTS=/path/to/ca.pem 指定 Node 使用该 CA。

MCP 客户端通常会以精简的环境启动服务，因此请在服务的 env 块中设置这些变量，而不要依赖 shell 环境。

MCP 服务

octri mcp serve

它通过 stdio 使用 MCP，并提供与输入命令相同的工具。助手可以推送规范、等待构建完成、读取生成的 Go 代码，然后读取该构建导致的生产环境错误。

若要一键将其添加到 Cursor 或 VS Code，可通过 npx 安装，无需全局安装：

该服务使用 octri auth login 中的配置文件，因此请先登录，或在其环境中设置 OCTRI_API_KEY。已列入官方 MCP Registry，名称为 dev.octri/cli。

// Claude Desktop / Cursor
{
  "mcpServers": {
    "octri": {
      "command": "octri",
      "args": ["mcp", "serve"]
    }
  }
}

凭据来自存储的配置文件，助手永远不会看到它们。读取操作不受限制。除非启动服务时指定相应标志，否则会拒绝执行那两项无法撤销的操作：

octri mcp serve --allow-publish   # publishing to package registries
octri mcp serve --allow-delete    # deleting specs

工具失败会作为工具结果返回，而不是协议错误，因此助手可以读取消息并自行纠正。

说明

构建进度通过轮询获取，而非流式传输。/ws/sdk 套接字通过标头或 Cookie 进行身份验证，而 Node 内置的 WebSocket 无法设置这些内容；引入 WebSocket 依赖也只能为一个耗时数分钟的构建节省约一秒。
构件归档由手写的 tar 和 zip 读取器解压，因此无需安装这两种二进制程序。两者都会拒绝写入目标目录之外的条目。
@modelcontextprotocol/sdk 是唯一的运行时依赖。颜色、旋转指示器、进度条、表格和提示词均在本地实现。

Octri 的其他产品

产品	功能
API Studio	将 OpenAPI 规范转化为托管文档站点，附带实时请求演练场，并可逐页编辑。
SDK Studio	将同一规范转化为十种语言的客户端库，并进行版本管理和统一发布。
MCP	根据同一规范生成工具，将你的端点和文档转化为 AI 助手可调用的工具。
Monitoring	为 API 提供错误、跟踪记录、运行时间和发布信息，并关联访问该 API 的 SDK 调用。