Setting up your Chat environment with Stream CLI

3 min read

In this tutorial, we’ll look at how you can initialize the environment of your newly created Stream Chat application using the Stream CLI.

Jeroen L.
Jeroen L.
Published December 20, 2022

Previously, in Get up and Running With Stream Chat, we looked at how to register your organization, and get an API key and secret for your Stream Chat app. Now it's time to create your first users and channels in this environment.

One of the ways of doing that is by using our friendly stream-cli tool. This gives you simple command line access to the Stream APIs, and provides helpful conversational prompts to input your parameters. Let's see how it works.

Installing the tool

The Stream CLI is written in Go and pre-compiled into a single binary. It doesn't have any prerequisites.

Download the binaries

You can find the binaries in the Release section of this repository. We also wrote a short script to download them and put it to your $PATH.

Bash (MacOS and Linux)

$ /bin/bash -c "$(curl -fsSL"

PowerShell (Windows)

$ Invoke-WebRequest -Uri "" -OutFile "install.ps1"; powershell.exe -ExecutionPolicy Bypass -File ./install.ps1


For MacOS users, it's also available via Homebrew:

$ brew tap GetStream/stream-cli
$ brew install stream-cli

Compile yourself

$ git clone
$ cd stream-cli
$ go build ./cmd/stream-cli

Confirm the CLI is working

You can confirm that it's installed correctly by running the stream-cli --version command.

Configure the CLI

To configure your authentication details, run stream config:set. This will prompt you for details such as your API key and secret, which will be used to perform the actions on your behalf.

You'll notice along the way that you get suggestions for default values where possible - just hit Return to accept these.

If you're not in the default region, see the Multi-region Support page to find the correct URL. You will need to set a different base URL.

Creating users

To create a user, run the stream-cli chat upsert-user command, which takes a JSON dictionary in which you can enter a user ID and a role for the user:

$ stream-cli chat upsert-user --properties "{\"id\":\"my-user-1\", \"role\": \"user\"}"

You can update existing users to add more details, such as the name and profile image URL using the same command.

Check the Go SDKs 'User' struct for the properties that you can use here.

type User struct {
    ID       string   `json:"id"`
    Name     string   `json:"name,omitempty"`
    Image    string   `json:"image,omitempty"`
    Role     string   `json:"role,omitempty"`
    Teams    []string `json:"teams,omitempty"`
    Language string   `json:"language,omitempty"`

    Online    bool `json:"online,omitempty"`
    Invisible bool `json:"invisible,omitempty"`

    CreatedAt  *time.Time `json:"created_at,omitempty"`
    UpdatedAt  *time.Time `json:"updated_at,omitempty"`
    LastActive *time.Time `json:"last_active,omitempty"`

    Mutes                    []*Mute                `json:"mutes,omitempty"`
    ChannelMutes             []*ChannelMute         `json:"channel_mutes,omitempty"`
    ExtraData                map[string]interface{} `json:"-"`
    RevokeTokensIssuedBefore *time.Time             `json:"revoke_tokens_issued_before,omitempty"`

You can query already existing objects, for example, you can look up the full details of a user with stream-cli chat query-users. This is useful not only to check that you've correctly created your users, but also for quickly debugging their state later on.

$ stream-cli chat query-users --filter '{"id": {"$eq": "my-user-1"}}'

Creating channels

After creating your users, it's time to create channels for them to talk in. The flow here is very similar to what you've used before, just invoke stream-cli chat create-channel this time.

$ stream-cli chat create-channel --type messaging --id redteam --user my-user-1

Once you have a channel, you can add members to it using stream-cli chat add-members.

$ stream-cli chat add-members --type messaging --id red-team my-user-1

And of course, you can always check the channel's current status using stream-cli chat get-channel.

Checking created data on the dashboard

Having completed the previous steps, you should now have some users and channels available in your Stream Chat app. You can go to the Explorer page of the dashboard to check these out.

Opening the Stream Chat Explorer on the dashboard

Here, you'll be able to list your users and their details.

Looking at the list of users in the Explorer

You also see the list of available channels, and you can dig down into the members inside an individual channel to see that you've correctly added your users to them.

Inspecting the details of a channel in the Explorer

Check out the full list of chat commands and arguments that the CLI supports to learn more.


That's a wrap. You now have the ability to easily interact with the Stream Chat API via your command line, to create and manage users and channels. The CLI also lets you interact with messages, reactions, user devices, and more. Keep exploring it by visiting its GitHub page.

To move on to creating your own chat app, check out our tutorials for various platforms. Since you now have your own app and users/channels, you can use those details while going through the tutorials.

Other client libraries:

decorative lines
Integrating Video With Your App?
We've built an audio and video solution just for you. Launch in days with our new APIs & SDKs!
Check out the BETA!