stream-cli

Original：🇺🇸 English

Translated

Query Stream data and run CLI operations against Chat, Video, Feeds, and Moderation: list channels, list calls, show flagged messages, find users, query any Stream resource. Run stream api / stream config / stream auth commands. Install the Stream CLI binary. Use when the user gives operational verbs ('list', 'show', 'find', 'check', 'query') with Stream nouns, or invokes the CLI literally.

15installs

Sourcegetstream/agent-skills

Added on2026-05-07

NPX Install

npx skill4agent add getstream/agent-skills stream-cli

SKILL.md Content

View Translation Comparison →

Stream CLI - API interaction

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.

Credential resolution (before any

stream api

call)

.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.

CLI Workflow

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
.

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`

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"}'
```

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>

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.

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.

CLI Rules (summary)

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.