> For the complete documentation index, see [llms.txt](https://tools.docs.sendbird.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://tools.docs.sendbird.com/readme/commands.md).

# CLI reference

Use this reference to:

* Find Sendbird CLI commands
* Read their results
* Use the options shared by all commands

To list the commands in your installed version, run `sendbird --json commands --compact`.

## Command lists

| Commands for                                                   | Reference                                                        |
| -------------------------------------------------------------- | ---------------------------------------------------------------- |
| Login, organizations, apps, profiles, and other account tasks  | [Account commands](/readme/commands/account-and-cli-commands.md) |
| Chat users, channels, messages, SDK operations, and Chat usage | [Chat commands](/readme/commands/command-reference.md)           |
| Calls settings, VoIP push credentials, and usage               | [Calls commands](/readme/commands/command-reference-1.md)        |

The lists show each command's own options. Options that every command accepts are in [Common options](#common-options). To check a command's required inputs, accepted values, and response schema in your build, run `sendbird --json describe COMMAND`.

## Find a command

Start with the short agent guide, then search the catalog for your task:

```bash
sendbird --json agent
sendbird --json commands --compact --search message send
sendbird --json describe chat message send
sendbird help chat message send
sendbird --json workflows first-message
```

`describe` shows a command's required inputs, accepted values, defaults, and authentication. Use the exact command name that search returns. A listed command can still fail if your account or app lacks the permission or feature. A workflow lists the steps of a task; it doesn't run them.

Search understands English and Korean synonyms and spelling variants, but not every natural-language request. To list the whole catalog, page through it:

```bash
sendbird --json commands --compact --limit 100 --offset 0
sendbird --json commands --compact --limit 100 --offset 100
sendbird --json commands --compact --limit 100 --offset 200
```

## Common options

<table><thead><tr><th width="300.04296875">Option</th><th>Purpose</th></tr></thead><tbody><tr><td><code>--profile</code>, <code>--org-id</code>, <code>--app-id</code></td><td>Select the target for this command, overriding saved selections.</td></tr><tr><td><code>--as-user</code></td><td>Run an SDK command as this Chat user.</td></tr><tr><td><code>--json</code>, <code>--raw</code>, <code>--no-color</code></td><td>Select structured, compatibility, or colorless output.</td></tr><tr><td><code>--human</code></td><td>Select readable output.</td></tr><tr><td><code>--dry-run</code></td><td>Preview the request, on commands that support it.</td></tr><tr><td><code>--yes</code></td><td>Confirm an operation that requires approval.</td></tr><tr><td><code>--body-file</code></td><td>Read the JSON body from a file, or from standard input with <code>-</code>.</td></tr><tr><td><code>--project</code></td><td>Apply the <code>sendbird.json</code> file in the current folder. Without this option, the file is ignored.</td></tr><tr><td><code>--example</code>, <code>--response-schema</code></td><td>Show the command's example or response schema offline.</td></tr><tr><td><code>--secret-output</code></td><td>Save a sensitive result to a new private file. Existing files aren't overwritten, and a path in a Git repository must be ignored by Git.</td></tr></tbody></table>

Pass real JSON numbers, booleans, arrays, and objects. `--enabled false` isn't the same as leaving the option out. Don't set the same field in both `--body-file` and an individual option.

### SDK connection options

SDK commands find the selected app's hosts and use the Chat user's existing access token automatically. The CLI doesn't issue a missing token; to issue one, use `chat user token issue`. If the app's token policy is `0`, which allows reading and writing without a token, you can connect without a token by adding `--allow-guest`. This works only for users who have never been issued a token. Check the policy with `sendbird --profile prod app auth-policy get`. Don't use `--allow-guest` to fix an authentication error, because it can create a user.

To override the defaults, use these options:

* `--user-token-file`
* `--sdk-config-file`
* `--sdk-api-host` with `--sdk-ws-host`

A config file and the host options are alternatives. Check `describe` before using them.

* **With the Chat user's token, found automatically:** The CLI checks the app's hosts on every run. A config file or host options must match those hosts.
* **With `--user-token-file` or `--allow-guest`:** Host options let the CLI skip looking up the hosts.

If the CLI reports that the app, environment, or hosts don't match, check the target app, then read the app's SDK settings again with `sendbird --profile prod app sdk-config --raw`.

## Choose an output format

<table><thead><tr><th width="159.36328125">Format</th><th>Output</th></tr></thead><tbody><tr><td>Default</td><td>Readable summaries and tables.</td></tr><tr><td><code>--json</code></td><td>JSON on stdout, errors on stderr, and one JSON line per event for watch commands. API and SDK data is under <code>result</code>.</td></tr><tr><td><code>--raw</code></td><td>The earlier raw-result format, for scripts that expect it.</td></tr><tr><td><code>--no-color</code></td><td>Readable output without color.</td></tr><tr><td><code>--human</code></td><td>Readable output, selected explicitly.</td></tr></tbody></table>

Commands fail instead of prompting when required input is missing. Browser login and `setup` can ask questions.

## Read command results

API and SDK responses include a `status`:

<table><thead><tr><th width="159.8046875">Status</th><th>Meaning</th></tr></thead><tbody><tr><td><code>preview</code></td><td>The request wasn't sent.</td></tr><tr><td><code>accepted</code></td><td>The server accepted a change. Confirm the outcome separately by checking delivery, read status, or the changed resource.</td></tr><tr><td><code>verified</code></td><td>A read completed.</td></tr><tr><td><code>succeeded</code></td><td>A local operation completed.</td></tr><tr><td><code>completed</code></td><td>A watch or other time-limited stream ended.</td></tr></tbody></table>

For example, a trimmed response from sending a Group channel message:

```json
{
  "ok": true,
  "command": "sendbird chat message send",
  "status": "accepted",
  "result": {
    "message_id": 411515552,
    "channel_url": "<CHANNEL_URL>",
    "message": "Are you available?"
  }
}
```

Use `result.message_id` to read or reply to this message.

Discovery commands, such as `agent`, `commands`, `describe`, and `workflows`, return their own structures without `ok` and `result`. Errors go to stderr, so stdout can be empty when a command fails.

Watch commands print one JSON line per event, with the event name at `event.event`. A final `completed` line marks the end of the watch. See [Send and receive messages](/readme/chat/send-and-receive-messages.md).

## Preview and confirm changes

Commands that support `--dry-run` show the request without sending it. A preview doesn't check that the resource exists or that you have permission.

```bash
sendbird --profile prod org create --organization-name "Chat tutorial" --dry-run
```

These commands don't support `--dry-run`:

* `setup`
* Browser login and signup
* `use` and `clear` commands
* `project init`

Skill registration and removal support `--dry-run`.

Some changes, such as deletions, require `--yes`. Check the command's description before running it.

## Connect results to the next command

Pass the organization UIDs, app IDs, channel URLs, and message IDs returned by one command to the next. Don't use placeholder values in real requests.

If a change times out, the change may still have been applied. Read the target resource before retrying, and check these response fields when present:

* `mutation_state`
* `outcome_unknown`
* `recovery`
* `next`
* `safe_to_retry`

Don't resend while `safe_to_retry` is `false`.

## Follow list pagination

<table><thead><tr><th width="200.078125">Result type</th><th>How to get the next page</th></tr></thead><tbody><tr><td>Dashboard list</td><td>Pass the returned token, cursor, offset, or <code>next</code>. Each result is one page.</td></tr><tr><td>SDK query</td><td>Start with <code>--page 1</code> and follow <code>next_page</code>. Pages can repeat earlier results while data changes, and the next page may be unavailable after page 100.</td></tr><tr><td>Message history</td><td>Pass <code>next_before_id</code> as <code>--before-id</code>. Don't combine it with <code>--before</code>.</td></tr><tr><td>Thread replies</td><td>Pages can overlap, so remove duplicate messages by ID.</td></tr></tbody></table>

## Understand saved context

The CLI picks the profile in this order:

1. `--profile`
2. The `SENDBIRD_PROFILE` environment variable
3. The saved active profile

Without any configuration, it uses `prod`.

It picks the organization, app, and region in this order:

1. Explicit options
2. `sendbird.json` in the current folder, when you pass `--project`
3. The profile's saved selections

It doesn't look for `sendbird.json` in parent folders. `project init --yes` writes the current selections to that file without creating an app, and doesn't overwrite an existing file.

Configuration is stored in `~/.config/sendbird`, or in the directory set by `SENDBIRD_CONFIG_DIR`. It holds profiles and selections. Login credentials are stored in your operating system's credential store.

To choose another organization or app, follow [Select your app](/readme/quickstart.md#step-3-select-your-app). Changing the organization clears the selected app, and each login clears the organization, app, and region selections.

To find an app in a long list, search by name or ID. Replace `<NAME>` with part of the app's name or its App ID, and keep the single quotes:

```bash
sendbird --profile prod app list --app-name-or-app-id '<NAME>'
```

To clear the saved selections without deleting anything on the server:

```bash
sendbird --profile prod app clear
sendbird --profile prod org clear
```

## Guided setup

To log in or sign up and then select an organization and app interactively, run:

```bash
sendbird --profile prod setup
```

You can run setup right after you install the CLI. If the `prod` profile doesn't exist, setup creates it first. Run setup in a terminal, because it asks questions. `--json` doesn't turn the questions off.

<table><thead><tr><th width="179.76953125">Stage</th><th>What you do</th></tr></thead><tbody><tr><td>Profile</td><td>Setup uses the profile selected by the command, and creates it if it doesn't exist.</td></tr><tr><td>Account</td><td>Choose <strong>Sign in</strong> for an existing account or <strong>Create a Sendbird account</strong> for a new one. Setup skips this stage if you're already logged in.</td></tr><tr><td>Organization</td><td>Choose an organization. Setup offers to create one only when you have none; otherwise, use <code>org create</code>.</td></tr><tr><td>Application</td><td>Choose an app, page through the list, enter an App ID, or create a Chat app. Setup shows the app's name and App ID.</td></tr><tr><td>Region</td><td>For a new app, choose an available Chat region. For an existing app, you can choose a default region for apps you create later. An app's region can't change after the app is created.</td></tr><tr><td>Review and save</td><td>Review your choices, then save them as defaults or finish without saving. Saving also makes this profile active.</td></tr></tbody></table>

If you choose to create an account:

1. Create the account in the browser.
2. Accept the terms.
3. Approve CLI access.
4. Return to the terminal to continue.

Email verification is a separate step. To sign up without the rest of setup, use `auth signup`.

When you save, setup shows **Chat setup complete**. When you finish without saving, it shows **Chat setup checked**. To check that the profile is active and your app is selected, run:

```bash
sendbird --profile prod profile
sendbird --profile prod app get
```

Canceling or finishing without saving doesn't log you out or delete an organization or app that setup created. Check `defaults_saved` in the result to see whether your choices were saved. Setup returns the follow-up check command in `next_argv` but doesn't run it.

If a command fails, see [Troubleshooting](/readme/troubleshooting.md).