Skip to content

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.

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.
  • A Stream account. Sign up for a free one at getstream.io if you don't have one. It takes about a minute.

Step 1. Install

In your terminal, run:

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:

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:

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

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:

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

The response is JSON:

{
  "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 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:

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:

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:

getstream token alice --ttl 1h
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.

Where to go next