Skip to content

Using the CLI with an agent

An agent can work independently with the CLI. Endpoints describe themselves, output is JSON and nothing needs a human present at the keyboard. This page explains the division of labor and the guardrails worth keeping.

Why an agent can use the CLI

getstream api --help lists every endpoint, and --schema prints an endpoint's request body without calling it, so the agent discovers what it doesn't know instead of guessing.

Stream agent skills

The Stream Agent Skills teach an agent Stream's workflows. This saves an agent having to discover how best to work with Stream in every new session. Install agent skills covers how to install the skills.

Giving your agent access to your app

An agent can't reach your app on its own. It can create its own throwaway app with getstream login --guest, but that never touches yours. Giving it access is your job, and you have two ways to do it:

  • At a keyboard. Run getstream init once per project. It signs you in through the browser the first time (once per machine), then links the app and writes its credentials. The same run offers to install the skills, so one command does the whole handoff.
  • Headless. Write .stream/creds.yaml from your secret store before the agent starts, the way you provision CI. A cloud agent has no browser, so this is its only route. Use in CI has the file format.

Either way, once .stream/creds.yaml exists the agent is self-sufficient: api, token and env run with no further input.

When an agent reports missing credentials, that's your cue to provide them, not the agent's cue to work around it. The skills already behave this way: they stop and walk you through it.

The secret stays out of context

Commands resolve .stream/creds.yaml themselves, so the agent never handles your API secret and no key material passes through its context or its transcript.

Writes stay behind approval

Your agent's command approval rules apply to every getstream call so nothing touches your app unseen. If your agent supports allowlists, getstream api Query* calls are read-only and safe to auto-approve. We recommend leaving mutating calls on manual approval.

Responses land in context

A channel query with full state runs to tens of kilobytes, all of it straight into the agent's context window. --jq filters the output that's sent to your agent so the agent gets ids and counts instead of payloads:

getstream api QueryChannels --request '{"limit":1000}' --jq '.channels | length'
getstream api QueryUsers --request '{"limit":100}' --jq '.users[] | {id, created_at}'

Agent runs are non-interactive, so a raw response shortens long arrays to 25 items - but --jq output never truncates. Agents should use --jq by default; the skills advise this.

Related