Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 21 additions & 2 deletions cli.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -4,9 +4,9 @@ description: Install and configure the Chatwoot CLI to manage your inbox from th
sidebarTitle: Overview
---

A terminal client for Chatwoot. Most things you'd do in the agent dashboard (read conversations, reply, assign, resolve) work as commands you can script or pipe into other tools. It's also handy with coding agents: tools like Claude Code or Cursor can call `chatwoot` directly to look up conversations, post replies, or automate repetitive triage, without needing a custom integration.
A terminal client for Chatwoot. Most things you'd do in the agent dashboard (read conversations, reply, assign, resolve) work as commands you can script or pipe into other tools. You can also search help center articles from the terminal. It's handy with coding agents: tools like Claude Code or Cursor can call `chatwoot` directly to look up conversations, post replies, search help center content when asked, or automate repetitive triage, without needing a custom integration.

- **[Commands](/cli/commands)** — the full command reference: conversations, contacts, inboxes, agents.
- **[Commands](/cli/commands)** — the full command reference: conversations, contacts, inboxes, agents, help centers.
- **[Scripting & output](/cli/scripting)** — JSON / CSV / quiet mode, shell completions, automation recipes.

## Install
Expand Down Expand Up @@ -73,6 +73,25 @@ Restart your shell (or `source` your rc file). Tab-completion works for commands
chatwoot --help
chatwoot conv --help
chatwoot convs --help
chatwoot hc --help
```

Issues and feedback: [github.com/chatwoot/cli](https://github.com/chatwoot/cli).

## Uninstalling

```bash
chatwoot auth logout # remove API key from the OS keyring
rm -rf ~/.chatwoot # delete config (~/.chatwoot/config.yaml)
rm "$(command -v chatwoot)" # delete the binary
```

If you set up shell completions, also remove them:

```bash
rm -f ~/.local/share/bash-completion/completions/chatwoot # bash
rm -f ~/.config/fish/completions/chatwoot.fish # fish
# zsh: delete the `source <(... completion zsh -c)` line from ~/.zshrc
```

On Windows, delete the extracted `chatwoot.exe` and the `%USERPROFILE%\.chatwoot` folder. If `CHATWOOT_API_KEY` is set in your environment, unset it in your shell rc — `auth logout` can't remove env-provided credentials.
6 changes: 4 additions & 2 deletions cli/agent-skill.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ description: Install the Chatwoot CLI agent skill so coding tools like Claude Co
sidebarTitle: Agent skill
---

The Chatwoot CLI ships with an [agent skill](https://skills.sh) — a small instruction file that teaches AI coding tools (Claude Code, Cursor, Codex, Gemini CLI, and 50+ others) how to use `chatwoot` correctly. With the skill installed, a prompt like _"find conversations tagged refund and assign the unassigned ones to me"_ runs the right commands, parses JSON properly, and pauses for confirmation before sending customer-visible replies.
The Chatwoot CLI ships with an [agent skill](https://skills.sh) — a small instruction file that teaches AI coding tools (Claude Code, Cursor, Codex, Gemini CLI, and 50+ others) how to use `chatwoot` correctly. With the skill installed, a prompt like _"find conversations tagged refund and assign the unassigned ones to me"_ runs the right commands, parses JSON properly, and pauses for confirmation before sending customer-visible replies. It can also search help center articles when you explicitly ask for knowledge-base context.

## Install

Expand All @@ -20,7 +20,7 @@ The skills CLI auto-detects the coding agents you have installed and offers to i
npx skills add chatwoot/cli --global
```

The skill activates automatically when you ask the agent to do something Chatwoot-related — _"triage my inbox"_, _"reply to conv 123"_, _"find conversations tagged refund"_.
The skill activates automatically when you ask the agent to do something Chatwoot-related — _"triage my inbox"_, _"reply to conv 123"_, _"find conversations tagged refund"_, _"search the help center for API channel docs"_.

## Authenticate the agent

Expand All @@ -34,6 +34,7 @@ export CHATWOOT_API_KEY=your_token_here

- **The id-first grammar** — `chatwoot conv 123 reply "..."` instead of guessing flag layouts.
- **The output contract** — parse `-o json`, never the human-readable text format.
- **Help center lookup** — use `hc articles` and `hc article` when the user asks for help center content, without making it the default step for ordinary triage.
- **Safety rules** — `reply` is customer-visible and irreversible, so the agent shows the full text and asks before sending.
- **Common pitfalls** — `label` replaces rather than appends, `--query` searches message content (not contacts), `assign --agent <name>` is a case-insensitive substring match, list endpoints paginate.
- **Composable patterns** — `-q | xargs` for bulk operations, `jq` chaining for lookups.
Expand All @@ -47,6 +48,7 @@ Once the skill is installed, prompts like these work without further setup:
- _"What's in my open inbox today? Group by priority."_
- _"Find conversations tagged `refund` that have been pending for more than 48 hours and assign them to Alice."_
- _"Read the last five messages on conv 412 and draft a reply — show it to me before sending."_
- _"Search the help center for API channel setup docs."_
- _"Resolve every open conversation tagged `spam`."_

The agent composes `chatwoot` commands, parses JSON, and stops to confirm before any write that affects customers.
Expand Down
15 changes: 15 additions & 0 deletions cli/commands.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -87,6 +87,21 @@ chatwoot labels # list account-level labels
chatwoot teams # list teams
```

## Help centers

`hc articles` uses the saved default help center and locale. Pass `--portal` or `--locale` when you want to override them for one command.

```bash
chatwoot hcs # list help centers
chatwoot hc default user-guide # save default help center and locale
chatwoot hc default # show current default
chatwoot hc default --clear # clear current default
chatwoot hc articles --query "api channel" # search articles
chatwoot hc articles --category channels # list/search within a category
chatwoot hc article 1677839703-how-to-create-an-api-channel-inbox
chatwoot hc articles --portal user-guide --locale en
```

## Profile

```bash
Expand Down
Loading