# 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](https://getstream.io/agent-skills/docs/) 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](https://getstream.io/cli/docs/install-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](https://getstream.io/cli/docs/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:

```bash
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

- [Quickstart with an agent](https://getstream.io/cli/docs/quickstart/): the handoff in five minutes
- [Install agent skills](https://getstream.io/cli/docs/install-skills/): the skills, or the no-skills pointer
- [Use in CI](https://getstream.io/cli/docs/ci/): headless credentials in full
- [Agent Skills documentation](https://getstream.io/agent-skills/docs/): what each skill teaches

---

For the most recent version of this documentation, visit [https://getstream.io/cli/docs/concepts/agents/](https://getstream.io/cli/docs/concepts/agents/).