stream-cli

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Stream CLI - API interaction

Stream CLI - API交互

Read first (every session): Glob
../stream/SKILL.md
. If the path is empty, install with
npx skills add GetStream/agent-skills --s stream -y
(no confirmation, just run). Then Read
../stream/RULES.md
- it includes a Peer skills table for installing/invoking any other pack skills on demand.

Use this skill when the user wants to interact with Stream's APIs via the

stream

CLI, or to install the CLI itself.

Prerequisite: complete

preflight.md

- verify the

stream

binary is installed (install via

bootstrap.md

if not) before any

stream api

usage.

Install only (Track C): if the user asked to install the CLI / set up Stream with no project context, jump straight to

bootstrap.md

. The bootstrap module is self-contained.

Heavy examples / query cookbooks: load cli-cookbook.md
only when you need a non-obvious

--body

or filter.

每次会话必读： 读取
../stream/SKILL.md
文件。如果路径为空，使用
npx skills add GetStream/agent-skills --s stream -y
安装（无需确认，直接运行）。然后读取
../stream/RULES.md
- 其中包含一个Peer skills表格，用于按需安装/调用任何其他包技能。

当用户希望通过

stream

CLI与Stream的API交互，或安装CLI本身时，使用此技能。

前提条件： 完成

preflight.md

- 在使用任何

stream api

命令前，验证

stream

二进制文件已安装（若未安装，通过

bootstrap.md

进行安装）。

仅安装（Track C）： 如果用户要求安装CLI/设置Stream但无项目上下文，直接跳转至

bootstrap.md

。引导模块是独立完整的。

复杂示例/查询手册： 仅当你需要非通用的

--body

参数或过滤器时，加载**

cli-cookbook.md

**。

Credential resolution (before any

stream api

call)

凭证解析（执行任何

stream api

调用前）

.env
in cwd has
```
STREAM_API_KEY
```
-> credentials are local. The CLI auto-resolves from env vars - you're querying this project's app.
No
.env
-> check
```
stream config list
```
for configured org/app -> use those. Mention which app you're querying: "Querying app
```
<name>
```
(configured via CLI)."
Nothing -> tell the user: "No Stream credentials found. Run
```
stream auth login
```
to connect, or
```
cd
```
into a project with a
```
.env
```
."

Do credential resolution silently when

.env

or config exists - don't ask the user, just resolve and proceed.

当前目录下的
.env
文件包含
```
STREAM_API_KEY
```
-> 凭证为本地存储。CLI会自动从环境变量中解析 - 你将查询此项目的应用。
无
.env
文件 -> 检查
```
stream config list
```
查看已配置的组织/应用 -> 使用这些配置。告知用户你正在查询的应用：“正在查询应用
```
<name>
```
（通过CLI配置）。”
无任何凭证 -> 告知用户：“未找到Stream凭证。运行
```
stream auth login
```
进行连接，或
```
cd
```
到包含
```
.env
```
文件的项目目录中。”

当

.env

或配置存在时，静默执行凭证解析 - 无需询问用户，直接解析并继续。

CLI Workflow

CLI工作流

Support: If the user asks for support or how to contact someone, direct them to getstream.io/contact.

Resolve credentials (see above). If none found, stop and guide the user.
Read
~/.stream/cache/API.md
to find the endpoint. Do NOT run
```
--list
```
or any CLI command for discovery - the file is always faster. If that file is missing or empty, run stream api --refresh
once, then read API.md
again. Use
```
stream --safe api <endpoint> --help
```
only after you have the endpoint name.
Check required params. If missing, ask - never guess.
Always run with
--safe
:
```
stream --safe api <endpoint> [params]
```
. This is the only permitted form on the first attempt.
If exit code 5 (safe mode refusal): the endpoint is mutating. Notify the user that you're about to execute a mutating Stream CLI operation, then re-run without
```
--safe
```
.
If the command fails, check exit code and recover (see below).
Summarize the response concisely.

Focused output: Use

--jq '<query>'

to filter API responses with a jq expression. Prefer this for endpoints expected to produce long responses.

Session consent (psychological): The user may say Mutating Stream CLI OK for this thread - still use --safe
first; exit 5 always requires a visible mutating notice before retry without --safe
.

支持： 如果用户请求支持或询问如何联系相关人员，引导他们访问getstream.io/contact。

解析凭证（见上文）。如果未找到，停止操作并引导用户。
读取
~/.stream/cache/API.md
查找端点。请勿运行
```
--list
```
或任何CLI命令进行发现 - 该文件的查询速度始终更快。如果该文件缺失或为空，运行一次**
```
stream api --refresh
```
，然后再次读取
```
API.md
```
**。仅在你知道端点名称后，使用
```
stream --safe api <endpoint> --help
```
。
检查必填参数。如果缺失，询问用户 - 切勿猜测。
始终使用
--safe
运行：
```
stream --safe api <endpoint> [params]
```
。这是首次尝试时唯一允许的形式。
如果退出码为5（安全模式拒绝）：该端点是突变型的。告知用户你即将执行一个突变型Stream CLI操作，然后不带
```
--safe
```
重新运行。
如果命令失败，检查退出码并进行恢复（见下文）。
简洁总结响应内容。

聚焦输出： 使用

--jq '<query>'

通过jq表达式过滤API响应。对于预期会产生长响应的端点，优先使用此方式。

会话同意（心理层面）： 用户可能会说Mutating Stream CLI OK for this thread（此线程允许执行突变型Stream CLI操作） - 仍需先使用**

--safe

；退出码5始终要求在不带

--safe

**重试前，显示突变操作通知。

Exit Code Recovery

退出码恢复

Exit code	Meaning	Recovery
`2`	Auth error (401, expired token)	Run `stream auth login` (browser flow in a real terminal), then retry the original command
`3`	API error (4xx/5xx from Stream)	Report the error to the user with the response message
`4`	Spec loading error (cache stale)	Run `stream api --refresh` , then retry
`5`	Safe mode refusal (mutating endpoint)	Notify the user of the mutating operation, then re-run without `--safe`

退出码	含义	恢复方式
`2`	认证错误（401，令牌过期）	运行 `stream auth login` （真实终端中的浏览器流程），然后重试原命令
`3`	API错误（Stream返回4xx/5xx）	将错误及响应消息告知用户
`4`	规范加载错误（缓存过期）	运行 `stream api --refresh` ，然后重试
`5`	安全模式拒绝（突变型端点）	告知用户该突变操作，然后不带 `--safe` 重新运行

Parameter syntax

参数语法

bash

stream api <EndpointName> key=value key2=value2

Simple values:
```
name=general limit=10 type=messaging
```
Booleans:
```
is_development=true
```
JSON objects/arrays: use
```
--body '{"key": "value"}'
```

bash

stream api <EndpointName> key=value key2=value2

简单值：
```
name=general limit=10 type=messaging
```
布尔值：
```
is_development=true
```
JSON对象/数组：使用
```
--body '{"key": "value"}'
```

Context resolution (org/app)

上下文解析（组织/应用）

Ampere endpoints require

app_id

org_id

as explicit parameters. SDK endpoints auto-resolve from:

--org

--app

flags > env vars >

~/.stream/config.json

> interactive prompt. Set defaults:

stream config set org <id>

and

stream config set app <id>

Ampere端点需要

app_id

org_id

作为显式参数。 SDK端点自动从以下位置解析：

--org

--app

标志 > 环境变量 >

~/.stream/config.json

> 交互式提示。设置默认值：

stream config set org <id>

和

stream config set app <id>

。

Negative knowledge

注意事项

No
OrganizationDelete
- contact Stream support.
No
AppSuspend
/
AppResume
- contact support.
CreateBlockList
is NOT idempotent - returns 400 if exists.
CreateChannelType
is NOT idempotent - returns 400 if exists.
Ampere endpoints use
app_id
/
org_id
, not
id
- e.g.,
```
AppDelete app_id=123
```
.

Auth endpoints (

AuthLoginBasic

AuthLoginGithub

, etc.) are internal - always use stream auth login
/ stream auth logout
instead.

不支持
OrganizationDelete
- 联系Stream支持。
不支持
AppSuspend
/
AppResume
- 联系支持。
CreateBlockList
不具备幂等性 - 若已存在，返回400。
CreateChannelType
不具备幂等性 - 若已存在，返回400。
Ampere端点使用
app_id
/
org_id
，而非
id
- 例如：
```
AppDelete app_id=123
```
。
认证端点（
```
AuthLoginBasic
```
、
```
AuthLoginGithub
```
等）为内部端点 - 始终使用**
```
stream auth login
```
** / **
```
stream auth logout
```
**替代。

Auth (assistants)

认证（助手）

Use stream auth login
with no extra flags, in a terminal where a browser window can open. The CLI uses PKCE with the dashboard - that is the supported sign-in path.

使用不带额外标志的**
```
stream auth login
```
**，在可打开浏览器窗口的终端中运行。CLI使用PKCE与仪表板交互 - 这是受支持的登录路径。

CLI Rules (summary)

CLI规则（摘要）

Endpoint discovery: ~/.stream/cache/API.md
first - never
```
--list
```
for discovery. Refresh if missing.
Help: stream --safe api <endpoint> --help
for parameters after you know the endpoint name.
Lazy auth - if exit code 2, stream auth login
then retry.
Missing params - ask; never invent IDs.
First attempt always
--safe
- exit 5 -> explain mutating op -> retry without --safe
.
Summarize API responses concisely for the user.

端点发现： 优先使用**
```
~/.stream/cache/API.md
```
** - 切勿使用
```
--list
```
进行发现。若缺失则刷新。
帮助： 在知道端点名称后，使用**
```
stream --safe api <endpoint> --help
```
**查询参数。
延迟认证 - 如果退出码为2，运行**
```
stream auth login
```
**后重试。
缺失参数 - 询问用户；切勿自行生成ID。
首次尝试始终使用
--safe
- 退出码5 -> 说明突变操作 -> 不带
```
--safe
```
重试。
简洁总结 API响应内容给用户。

stream-cli

Original

Translation

Stream CLI - API interaction

Stream CLI - API交互

Credential resolution (before any
`stream api`
call)

凭证解析（执行任何
`stream api`
调用前）

CLI Workflow

CLI工作流

Exit Code Recovery

退出码恢复

Parameter syntax

参数语法

Context resolution (org/app)

上下文解析（组织/应用）

Negative knowledge

注意事项

Auth (assistants)

认证（助手）

CLI Rules (summary)

CLI规则（摘要）

stream-cli

Original

Translation

Stream CLI - API interaction

Stream CLI - API交互

Credential resolution (before any stream api call)

凭证解析（执行任何stream api调用前）

CLI Workflow

CLI工作流

Exit Code Recovery

退出码恢复

Parameter syntax

参数语法

Context resolution (org/app)

上下文解析（组织/应用）

Negative knowledge

注意事项

Auth (assistants)

认证（助手）

CLI Rules (summary)

CLI规则（摘要）

Credential resolution (before any
`stream api`
call)

凭证解析（执行任何
`stream api`
调用前）