> 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/ai-agents.md).

# Use Sendbird CLI with an AI coding agent

Claude Code, Codex, and other AI coding agents can run Sendbird CLI commands for you. This page shows how to teach your agent the CLI, what to ask it, and how to have it work on your app code. The CLI includes features that help agents run commands correctly:

* `sendbird --json agent`: A short guide to the CLI, written for agents
* `sendbird --json commands` and `sendbird --json describe`: A searchable command catalog, and each command's required inputs, accepted values, and defaults
* `--json`: Structured responses, and one JSON line per event for watch commands
* `--dry-run`: A preview of a change that sends no request

## Before you begin

Run the agent on your own computer. Login needs a browser on the same computer, and you approve it yourself, so cloud-hosted agent environments can't complete it. For the other requirements, see the Quickstart [prerequisites](/readme/quickstart.md#prerequisites).

## Choose how the agent learns the CLI

<table><thead><tr><th width="209.5234375">Option</th><th>When to use it</th></tr></thead><tbody><tr><td><a href="/plugins/cli.md">Sendbird CLI plugin</a></td><td>In Claude Code or Codex. The Sendbird CLI plugin setup installs the CLI, logs you in, and has you choose your app.</td></tr><tr><td>Bundled CLI Skill</td><td>In Claude Code or Codex, without the Sendbird CLI plugin. You register the Skill that comes with the CLI.</td></tr><tr><td>Project instructions</td><td>With any agent. You add rules to your project's <code>AGENTS.md</code>, <code>CLAUDE.md</code>, or similar instruction file.</td></tr></tbody></table>

With the Sendbird CLI plugin, follow [its setup steps](/plugins/cli.md#start-the-sendbird-cli-plugin-setup). They install the CLI, log you in, and have you choose your app.

For the other two options, first install the CLI, log in, and select your app by following [Steps 1 to 3 of the Quickstart](/readme/quickstart.md#step-1-install-and-check-the-cli). Then register the Skill or add the rules as described in the next sections.

## Register the bundled CLI Skill

In your project folder, preview the registration, register the Skill, and check its status:

{% tabs %}
{% tab title="Claude Code" %}

```bash
sendbird skills install --agent claude --scope project --dry-run
sendbird skills install --agent claude --scope project
sendbird skills status --agent claude --scope project
```

{% endtab %}

{% tab title="Codex" %}

```bash
sendbird skills install --agent codex --scope project --dry-run
sendbird skills install --agent codex --scope project
sendbird skills status --agent codex --scope project
```

{% endtab %}
{% endtabs %}

The Skill is registered in `.claude/skills/sendbird` for Claude Code or `.agents/skills/sendbird` for Codex. To register it under your home directory instead, use `--scope user`.

After registering, reload Claude Code or Codex, or start a new session, so that it loads the Skill. To check that the Skill is loaded, enter `/skills` in Claude Code or Codex and find `sendbird` in the list. If registration fails or the Skill isn't available, see [Troubleshooting](/readme/troubleshooting.md#find-your-symptom).

To read the Skill without registering it, run `sendbird skills show`. To remove an unchanged registration, run `sendbird skills remove --agent <HOST> --scope project --yes`, replacing `<HOST>` with `claude` or `codex`, without the angle brackets.

## Add rules for the agent

To use project instructions, copy this block into your project's agent instruction file:

```markdown
## Sendbird CLI

- Install Sendbird CLI with `npm install -g @sendbird/cli`. The `sendbird` npm package is the Chat JavaScript SDK, not the CLI.
- Start with `sendbird --json agent`. Find commands with `sendbird --json commands --compact --search <words>` and check inputs with `sendbird --json describe <command>`. Don't guess command names or options.
- Pass `--json` and an explicit profile for remote work. Use `--profile prod` unless the user names another profile. API and SDK responses use `ok` and `result`; discovery commands have their own structures. Read error JSON from stderr.
- Before a write, confirm the target with `sendbird --profile prod app get`.
- Preview supported writes with `--dry-run` and show the preview to the user before running the real command.
- Ask the user before running a command that needs `--yes`, such as a deletion, or that affects billing.
- Use IDs returned by earlier commands. Never use placeholder values such as `<APP_ID>` in a real request.
- If a write times out and the response has `outcome_unknown`, read the target resource before retrying.
- Ask the user to complete browser login. Never ask for passwords, cookies, callback codes, or tokens.
- To confirm delivery, check the send result, the recipient's `message_received` event, and, when needed, the read receipt.
```

## Example requests

After the CLI is installed and you're logged in, describe the task in plain words. Here are three examples of tasks you can ask for.

To check which account you're logged in with and which app is selected, ask:

```
Check my Sendbird login and tell me which app is selected.
```

To test that a message sent by one user reaches another user, ask:

```
Create two test users in my test app and verify that one receives a message from the other.
```

To see the Group channels that a user belongs to, ask:

```
List the Group channels that user alice belongs to.
```

## Choose how to work on your app code

The CLI doesn't write app code. Choose how you want the agent to work on your app code, and tell it which option to use:

<table><thead><tr><th width="325.39453125">Option</th><th>What happens</th></tr></thead><tbody><tr><td>Install the <a href="/plugins/client.md">Sendbird Client plugin</a></td><td>Review the plugin's publisher and permissions, install it, and check that its tools are available in the current session. The agent then uses the plugin to write the code.</td></tr><tr><td>Use the Sendbird Client plugin's guide without installing the plugin</td><td>The agent reads the Sendbird Client plugin's guide from a pinned release or commit on GitHub and edits your app directly. The plugin's hooks don't run. This needs GitHub read access.</td></tr><tr><td>Work without the Sendbird Client plugin</td><td>The agent writes the code with its usual tools and the official Sendbird SDK documentation.</td></tr></tbody></table>

Give the agent:

* Your project
* What you want to build
* The App ID
* The result you expect

Don't include these in your request:

* CLI login credentials
* Management keys
* User tokens
* Private file contents