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.

stream

preflight.md

stream

bootstrap.md

stream api

bootstrap.md

cli-cookbook.md

--body

Credential resolution (before any

stream api

call)

1. .env

   in cwd has

   STREAM_API_KEY

   -> credentials are local. The CLI auto-resolves from env vars - you're querying this project's app.
2. No

   .env

   -> check

   stream config list

   for configured org/app -> use those. Mention which app you're querying: "Querying app

   <name>

   (configured via CLI)."
3. Nothing -> tell the user: "No Stream credentials found. Run

   stream auth login

   to connect, or

   cd

   into a project with a

   .env

   ."

.env

CLI Workflow

1. Resolve credentials (see above). If none found, stop and guide the user.
2. 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.
3. Check required params. If missing, ask - never guess.
4. Always run with

   --safe

   :

   stream --safe api <endpoint> [params]

   . This is the only permitted form on the first attempt.
5. 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

   .
6. If the command fails, check exit code and recover (see below).
7. Summarize the response concisely.

--jq '<query>'

--safe

--safe

Exit Code Recovery

2

stream auth login

3

4

stream api --refresh

5

--safe

Parameter syntax

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)

app_id

org_id

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

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)

1. Endpoint discovery:

   ~/.stream/cache/API.md

   first - never

   --list

   for discovery. Refresh if missing.
2. Help:

   stream --safe api <endpoint> --help

   for parameters after you know the endpoint name.
3. Lazy auth - if exit code 2,

   stream auth login

   then retry.
4. Missing params - ask; never invent IDs.
5. First attempt always

   --safe

   - exit 5 -> explain mutating op -> retry without

   --safe

   .
6. Summarize API responses concisely for the user.