# Quickstart with an agent
In the next five minutes we'll install the Stream CLI, link it to one of your apps, and hand it to your AI coding agent. By the end you'll be asking for live Stream data in plain English, and you'll see every command the agent runs on your behalf.
>
> **Tip:** **The fastest way.** Open your project folder in your agent and paste one line:
>
> ```text
> Add chat to my app: getstream.io/SKILL.md
> ```
>
> Your agent fetches `getstream.io/SKILL.md`, installs the CLI, runs `getstream init`, and pulls in the skills. Steps 1–4 below walk through the same setup by hand. Swap `chat` for `video`, `feeds`, or `moderation`. Open the URL yourself first if you want to see exactly what it does.
>
```mermaid
graph LR
s1["1. Install
curl | bash"] --> s2["2. Initialize
getstream init
pick your agent"]
s2 --> s3["3. Start agent
/stream appears"]
s3 --> s4["4. Ask
plain English in
live data out"]
```
You'll need:
- An AI coding agent that reads standard skills locations. Claude Code, Cursor, Codex and most others qualify. No agent? Follow the [Manual quickstart](https://getstream.io/cli/docs/manual-quickstart/) instead.
- A macOS or Linux machine with `curl` and `bash`. On Windows, use [WSL](https://learn.microsoft.com/windows/wsl/install).
- A Stream account. Sign up for a free one at [getstream.io](https://getstream.io/).
## Step 1. Install
In your terminal, run:
```bash
curl -fsSL https://getstream.io/cli.sh | bash
```
Then confirm it worked:
```bash
getstream --version
```
You should see a version number. If you see "command not found", open a new terminal window so your shell picks up the updated `PATH`.
## Step 2. Initialize and pick your agent
`getstream init` links a directory to one of your apps. In real work you run it at the root of the repository your agent works in, the way you'd run `git init`. For this tutorial, make a scratch folder to learn in:
```bash
mkdir my-app
cd my-app
getstream init
```
`init` walks you through the whole setup. The first step happens in your browser; the rest are pickers (arrow keys to move, enter to confirm):
1. **Sign in.** Your browser opens and asks you to authorize the CLI with your Stream account. When the page says you can close the tab, return to the terminal; the session refreshes itself from here on.
2. **Select an organization.** If you just signed up, there's exactly one.
3. **Select an app.** New accounts start with one app. This will create `.stream/creds.yaml`, with your app's key and secret, plus add it to your `.gitignore` (or create one). The CLI reads credentials from this file, so the secret never passes through the agent's context.
4. **Install Stream skills for which tool?** Pick **Claude Code** to install into `.claude/skills`, or **Universal** for `.agents/skills`, the location used by Cursor, Codex and other AGENTS-ecosystem tools. This will install core Stream skills into your project.
Setting up a repo you already initialized without skills? [Install them](https://getstream.io/cli/docs/install-skills/) with `getstream skills --claude` or `--universal`; no need to re-run `init`.
## Step 3. Start your agent
Start your agent in `my-app`. Agents scan their skills directories at startup, so an agent that was already running needs a restart to see the new skills. Check that the skills are there:
```text
❯ /stream
/stream Stream router for Chat, Video, Feeds, and Moderation. Use when
the user wants to build a new app with Stream, scaffold a…
/stream-docs Search live Stream SDK documentation for Chat, Video, Feeds,
and Moderation. Look up how a Stream React/iOS/Android hook…
/stream-builder Build a new app or add Stream products to an existing app.
Scaffold Next.js + Tailwind + Shadcn + Stream SDKs end-to-end…
```
## Step 4. Ask for live data
Ask in plain English. `/stream` translates the question into a `getstream` command and answers from the output:
```text
❯ /stream list my most recent channels
stream: getstream api QueryChannels --request '{
"sort": [{ "field": "last_updated", "direction": -1 }],
"limit": 10
}'
You have 6 channels (sorted by last update). All are messaging type; most are
one-member channels, likely from testing:
┌─────────────────┬─────────┬──────────────┬──────────────────────────────────────┐
│ Channel ID │ Members │ Last updated │ Last message │
├─────────────────┼─────────┼──────────────┼──────────────────────────────────────┤
│ team-chat │ 3 │ Jul 2, 2026 │ "nice, messages are coming through!" │
│ practice-chat │ 1 │ Jul 1, 2026 │ │
│ 3f8c6a12-9d4e-… │ 1 │ Jun 28, 2026 │ "testing 123" │
└─────────────────┴─────────┴──────────────┴──────────────────────────────────────┘
… 3 more rows
The only multi-member channel is messaging:team-chat (3 members). The rest look
like auto-created test channels with a single member, several with no messages
at all.
```
The agent reads the output and reports on the state.
If the app you linked is brand new, the agent reports zero channels instead. Let's create a user and channel.
```text
❯ /stream create a messaging channel "general" with a hello message from a test user alice
stream: getstream api UpdateUsers --request '{"users":{"alice":{"id":"alice","name":"Alice"}}}'
stream: getstream api GetOrCreateChannel --type messaging --id general \
--request '{"data":{"created_by_id":"alice"}}'
stream: getstream api SendMessage --type messaging --id general \
--request '{"message":{"text":"Hello!","user_id":"alice"}}'
Created messaging:general and sent "Hello!" as alice.
```
Every command is in the transcript, and your agent's usual command approval applies before each one runs, so nothing touches your app unseen.
The skill covers Stream's workflows, and the CLI fills the gaps by describing itself: `getstream api --help` lists every endpoint and `--schema` prints any request body, so the agent looks up whatever it doesn't know.
## Where to go next
- To do this for real: run `getstream init` at the root of the repository your agent works in. Same four steps.
- To understand the handoff: [Using the CLI with an agent](https://getstream.io/cli/docs/concepts/agents/) covers the guardrails and the setup for cloud agents with no browser.
- To see what else the skills do: the [Agent Skills docs](https://getstream.io/agent-skills/docs/) cover documentation lookup and app scaffolding too.
- To learn the CLI first-hand: the [Manual quickstart](https://getstream.io/cli/docs/manual-quickstart/) runs the same setup with you at the keyboard.
---
For the most recent version of this documentation, visit [https://getstream.io/cli/docs/quickstart/](https://getstream.io/cli/docs/quickstart/).