# Manual quickstart

In the next five minutes we'll install the Stream CLI, link it to one of your apps, and run our first live API query. By the end you'll have real channel data from your Stream app and you'll know enough to keep going on your own.

```mermaid
graph LR
    s1["1. Install<br/>curl | bash"] --> s2["2. Initialize<br/>getstream init<br/>sign in and link an app"]
    s2 --> s3["3. Query<br/>getstream api<br/>live data from your app"]
    s3 --> s4["4. Create<br/>getstream api<br/>channel and message"]
    s4 --> s5["5. Test token<br/>getstream token"]
```

You'll need:

- 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/) if you don't have one. It takes about a minute.

## Step 1. Install

In your terminal, run:

```bash
curl -fsSL https://getstream.io/cli.sh | bash
```

The script detects your OS, verifies the download's checksum, and installs `getstream` to `~/.local/bin`, adding that directory to your `PATH` if needed.

When it finishes, confirm the install worked:

```bash
getstream --version
```

You should see a version number. If you see "command not found", open a new terminal window and try again. Your shell needs to pick up the updated `PATH`.

## Step 2. Initialize a project

The CLI works with a specific **project**: a directory linked to one of your apps. Every `getstream` command you run inside a project targets its linked app, so you never pass org or app ids by hand.

In real work you run `init` at the root of your app's repository, the way you'd run `git init`. You don't have one of those yet, so make a scratch directory to learn in:

```bash
mkdir my-app
cd my-app
getstream init
```

`init` walks you through the whole setup, including signing in.

The first step happens in your browser; the rest are pickers you move through with the arrow keys and confirm with enter. `/` filters a long list.

1. **Sign in.** The CLI has no session yet, so your browser opens and asks you to authorize it with your Stream account. Click through. When the page says you can close the tab, return to the terminal. You don't need to sign in again on this machine; the session refreshes itself from here on.
2. **Select an organization.** If you just signed up, there's exactly one. Select it.
3. **Select an app.** New accounts start with one app, so select this.
4. **Install Stream skills**. Skills teach an AI coding agent to drive the CLI. Pick your agent if you use one, or "Skip skill installation". You can add skills at any point with [`getstream skills`](https://getstream.io/cli/docs/install-skills/).

>
> **Tip:** No Stream account yet and just want to try the CLI? Run `getstream login --guest` before `init`. It creates a temporary guest account backed by a throwaway app in seconds, with no browser or email, and `init` skips the sign-in step. The rest of this tutorial works the same. When you want to keep your work, [convert the guest to a real account](https://getstream.io/cli/docs/authentication/) with `getstream login --upgrade`; logging out discards a guest account permanently.
>

The CLI then confirms the link between this project and the Stream application you selected:

```text
Project initialized.
┌───────────────────────────────────────┐
│ Organization  acme        ID: 1452158 │
│          App  acme-chat   ID: 1608483 │
│  Environment  Production              │
│       Region  US Ohio                 │
└───────────────────────────────────────┘
```

It also wrote the app's key and secret to `.stream/creds.yaml` and added `.stream/` to `.gitignore`, so the secret can't end up in version control.

## Step 3. Run your first query

List the ten most recent channels in your app:

```bash
getstream api QueryChannels --request '{"limit":10}'
```

The response is JSON:

```text
{
  "channels": [
    {
      "channel": {
        "id": "general",
        "type": "messaging",
        "cid": "messaging:general",
        ...
      },
      ...
    }
  ],
  "duration": "63.12ms"
}
```

If your app is brand new, `channels` is an empty array. Doesn't matter - you've just made a real API call to the live Stream platform! When a response is long, the CLI prints a notice that it truncated some arrays for readability; [`--jq`](https://getstream.io/cli/docs/pipe-output/) selects the full data.

Let's try one more. Most query endpoints take a `filter_conditions` object that lets you filter the response object. This one matches every user that has an id, five at a time:

```bash
getstream api QueryUsers --request '{"filter_conditions":{"id":{"$exists":true}},"limit":5}'
```

Every endpoint in every Stream product is callable this way.

## Step 4. Create a channel and send a message

Reads are half the story. Create a test user, then a channel with a first message, the same way your backend would:

```bash
getstream api UpdateUsers --request '{"users":{"alice":{"id":"alice","name":"Alice"}}}'

getstream api GetOrCreateChannel --type messaging --id general \
  --request '{"data":{"created_by_id":"alice"}}'

getstream api SendMessage --type messaging --id general \
  --request '{"message":{"text":"Hello!","user_id":"alice"}}'
```

Server-side calls act on behalf of a user, so `alice` has to exist first: the channel names her in `created_by_id` and the message in `user_id`. `UpdateUsers` creates or updates, so it's safe to run twice.

Run the Step 3 query again and `messaging:general` is in the response.

## Step 5. Generate a test token

Every user that connects through a Stream SDK needs a token signed with your app's secret. In production your backend signs them, but you can also generate test tokens with the CLI. Sign one for `alice`:

```bash
getstream token alice --ttl 1h
```

```text
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOi...
```

Connect through an SDK with this token and you're `alice`. Tokens also work for ids that don't exist yet; Stream creates the user on first connect.

>
> **Warning:** In production, [generate tokens with your own server](https://getstream.io/cli/docs/test-tokens/).
>

## Where to go next

- To start building your app: pick the [SDK tutorial](https://getstream.io/blog/topic/tutorials/) for your product and platform. [`getstream env`](https://getstream.io/cli/docs/commands/env/) writes the keys it needs into your project.
- To write real queries: [Query data with filters and sorts](https://getstream.io/cli/docs/query-data/) covers the `filter_conditions` syntax.
- To hand this work to your AI agent: the [Quickstart with an agent](https://getstream.io/cli/docs/quickstart/) picks up from the skills step above.

---

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