The Stream CLI By Example

The Stream CLI is a powerful tool for communicating and debugging your Stream Chat setup with the Stream API.

With the Stream CLI, you can quickly work your chat configuration using all of the features that are baked into the Stream Chat Go SDK, including but not limited to modifying chat channels and messages, setting up push and webhooks, managing users, and more.

In this post, I’ll outline best practices on how to use the Stream CLI, along with common use-cases and code examples, so that you can get up and running quickly.

Installation

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)

1
$ /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/GetStream/stream-cli/master/install/install.sh)"

PowerShell (Windows)

1
$ Invoke-WebRequest -Uri "https://raw.githubusercontent.com/GetStream/stream-cli/master/install/install.ps1" -OutFile "install.ps1"; powershell.exe -ExecutionPolicy Bypass -File ./install.ps1

Homebrew

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

1
2
$ brew tap GetStream/stream-cli https://github.com/GetStream/stream-cli
$ brew install stream-cli

Compile yourself

1
2
3
$ git clone git@github.com:GetStream/stream-cli.git
$ cd stream-cli
$ go build ./cmd/stream-cli

Configuration

Just like the Stream Go Chat SDK or any other Chat SDK for Stream, you will need to obtain credentials to properly execute commands.

Step 1:

Create an account on Stream’s website at https://getstream.io/ and head over to the dashboard. Next, create an application and locate your API key and secret.

Step 2:

Run the following command to initialize your CLI instance. This only needs to be done once as a configuration file is stored in the cache; however, you can always overwrite or add to the configuration should you need to switch projects.

$ stream-cli config new

An interactive prompt will ask you for the following credentials:

• What is the name of your app? (for example prod, staging, testing)
• Your Stream access Key
• Your Stream access Secret
• Your Stream API Base URL (please leave this as the default unless you’re a power user)

Note: You can bypass the prompt by passing values directly with the stream-cli --config command.

Getting Help

Every command offers a --help flag, even at the root level. For example, at the root of the CLI, you can see all available commands by simply passing --help to stream-cli chat.

Channel

All CRUD channel operations are available in the CLI.

Create a channel:

1
2
$ stream-cli chat create-channel -i redteam -t messaging -u joe
Successfully created channel [messaging:redteam2]

Add members to a channel:

1
2
$ stream-cli chat add-members --type messaging --id red-team joe jill jane
Successfully added user(s) to channel

Send a message to a channel:

1
2
$ stream-cli chat send-message --channel-type messaging --channel-id redteam --text "Hello World!" --user joe
Message successfully sent. Message id: [74c63670-f5ea-4b62-a149-98f434f321c1]

Send a reaction:

1
2
$ stream-cli chat send-reaction --message-id 74c63670-f5ea-4b62-a149-98f434f321c1 --user user --reaction-type like
Successfully sent reaction

List channels:

1
2
$ stream-cli chat list-channels -t messaging
< json payload >

Imports

Validate an import file:

1
$ stream-cli chat validate-import data.json

Upload a new import:

1
$ stream-cli chat upload-import data.json --mode insert

GDPR

Delete users:

1
$ stream-cli chat delete-users joe jill

Delete channel:

1
2
3
4
5
6
7
8
$ stream-cli chat delete-channel --type messaging --id redteam
Successfully initiated channel deletion. Task id: 66bbcdcd-b133-43ce-ab63-557c14d2a168

# Wait for the task to complete
$ stream-cli chat watch 66bbcdcd-b133-43ce-ab63-557c14d2a168
Waiting for async task to complete...⏳
Still loading... ⏳
Async operation completed successfully

Moderation

Ban a user:

1
$ stream-cli chat ban-user --target-user-id mike --banned-by admin-user-2 --reason "Bad behavior"

Un-ban a user:

1
$ stream-cli chat unban-user --target-user-id joe

Flag a message:

1
2
$ stream-cli chat flag-message --message-id msgid-1 --user-id userid-1
Successfully flagged message.

Mute a user:

1
2
$ stream-cli chat mute-user --target-user-id joe --muted-by-id admin --expiration 5
Successfully muted user.

Un-mute a user:

1
2
$ stream-cli chat unmute-user --target-user-id joe --unmuted-by-id admin
Successfully unmuted user.

Final Thoughts

I hope this primer helps you get started with the Stream CLI. It’s a truly powerful tool when working with Stream Chat. If you have any questions or would like further examples, please drop them in the comments below. For issues that you may encounter, please create an official issue on GitHub.

If you’re new to Stream Chat, Stream provides detailed documentation for each of the languages and frameworks supported. You can find the official Stream Chat docs here.

Happy Coding. 🤓