•Published: Dec 19, 2022
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.
To install the Stream CLI, you will need to have either NPM or yarn installed on your machine, along with the latest version of Node.js. The CLI is supported on macOS, Linux, and Windows environments.
Note: For extra output, it’s important to install JQ, a lightweight and powerful JSON processor for pretty and easy to read JSON output. On macOS, installing JQ is as easy as running a simple Homebrew command:
brew install jq.
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 https://raw.githubusercontent.com/GetStream/stream-cli/master/install/install.sh)"
$ Invoke-WebRequest -Uri "https://raw.githubusercontent.com/GetStream/stream-cli/master/install/install.ps1" -OutFile "install.ps1"; powershell.exe -ExecutionPolicy Bypass -File ./install.ps1
For MacOS users, it's also available via Homebrew:
$ brew tap GetStream/stream-cli https://github.com/GetStream/stream-cli $ brew install stream-cli
$ git clone email@example.com:GetStream/stream-cli.git $ cd stream-cli $ go build ./cmd/stream-cli
Just like the Stream Go Chat SDK or any other Chat SDK for Stream, you will need to obtain credentials to properly execute commands.
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.
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
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
All CRUD channel operations are available in the CLI.
Create a channel:
$ stream-cli chat create-channel -i redteam -t messaging -u joe Successfully created channel [messaging:redteam2]
Add members to a channel:
$ 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:
$ 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:
$ stream-cli chat send-reaction --message-id 74c63670-f5ea-4b62-a149-98f434f321c1 --user user --reaction-type like Successfully sent reaction
$ stream-cli chat list-channels -t messaging < json payload >
Validate an import file:
$ stream-cli chat validate-import data.json
Upload a new import:
$ stream-cli chat upload-import data.json --mode insert
$ stream-cli chat delete-users joe jill
$ 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
Ban a user:
$ stream-cli chat ban-user --target-user-id mike --banned-by admin-user-2 --reason "Bad behavior"
Un-ban a user:
$ stream-cli chat unban-user --target-user-id joe
Flag a message:
$ stream-cli chat flag-message --message-id msgid-1 --user-id userid-1 Successfully flagged message.
Mute a user:
$ stream-cli chat mute-user --target-user-id joe --muted-by-id admin --expiration 5 Successfully muted user.
Un-mute a user:
$ stream-cli chat unmute-user --target-user-id joe --unmuted-by-id admin Successfully unmuted user.
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. 🤓