cli

chatwoot-cli

CLI for Chatwoot — manage conversations, send replies, and run common workflows from your terminal.

Install

macOS / Linux — install script (detects OS/arch, fetches the matching release binary, verifies SHA256):

curl -fsSL https://chwt.app/install-cli | sh

The script installs to ~/.local/bin/chatwoot by default. Override with environment variables:

CHATWOOT_VERSION=v0.2.0 CHATWOOT_INSTALL_DIR=/usr/local/bin curl -fsSL https://chwt.app/install-cli | sh

Windows — download chatwoot_<version>_Windows_x86_64.zip from the releases page and extract chatwoot.exe.

From source — requires Go 1.22+:

go install github.com/chatwoot/cli/cmd/chatwoot@latest
# or
git clone https://github.com/chatwoot/cli.git && cd cli
go build -o chatwoot ./cmd/chatwoot/

Setup

chatwoot auth login

You'll be prompted for:

• Base URL — your Chatwoot instance (e.g. https://app.chatwoot.com)
• API Key — your agent API access token
• Account ID — your account number

Credentials are validated against the API before saving. Non-secret config is stored at ~/.chatwoot/config.yaml; the API key is stored in your OS keyring. For CI, coding agents, or headless environments, set CHATWOOT_API_KEY to override the saved keyring token.

CLI Usage

The CLI uses a simple noun grammar:

• Plural noun = list: chatwoot convs, chatwoot contacts, chatwoot agents
• Singular + id + verb: chatwoot conv 123 reply "thanks" — id before verb, the way you'd say it.
• <noun> <id> alone is shorthand for view: chatwoot conv 123 views conversation 123.

Conversations — list

chatwoot convs                                 # Open conversations assigned to you (default)
chatwoot convs -s resolved                     # Resolved conversations
chatwoot convs --assignee all --inbox 5        # All conversations in inbox 5
chatwoot convs -l billing,urgent               # Filter by labels
chatwoot convs --query "refund"                # Search by message content

Conversations — act on one

chatwoot conv 123                              # View (default)
chatwoot conv 123 messages                     # List messages
chatwoot conv 123 reply "Thanks, looking into it"
chatwoot conv 123 reply "internal note" --private
chatwoot conv 123 resolve                      # Mark resolved
chatwoot conv 123 open                         # Set status to open
chatwoot conv 123 pending                      # Set status to pending
chatwoot conv 123 snooze                       # Snooze until next reply
chatwoot conv 123 snooze --until 24h           # Or 7d, 2026-05-10
chatwoot conv 123 assign --agent me            # Assign to yourself
chatwoot conv 123 assign --agent alice         # By name (case-insensitive substring)
chatwoot conv 123 assign --agent 42            # By agent ID
chatwoot conv 123 assign --team 7              # Assign to a team
chatwoot conv 123 unassign
chatwoot conv 123 label billing,urgent         # Set labels (replaces existing)
chatwoot conv 123 priority urgent              # urgent | high | medium | low | none

Contacts

chatwoot contacts                              # List contacts
chatwoot contacts --search "john"              # Search by name, email, or phone
chatwoot contact 456                           # View
chatwoot contact 456 conversations             # Conversations for this contact

Inboxes, agents, labels, teams

chatwoot inboxes                               # List inboxes
chatwoot inbox 5                               # View one
chatwoot agents                                # List agents
chatwoot labels                                # List account-level labels
chatwoot teams                                 # List teams

Profile

chatwoot me                                    # Show your profile

Auth & config

chatwoot auth login                            # Interactive login (caches user_id)
chatwoot auth logout                           # Remove saved credentials
chatwoot auth status                           # Show current user and instance
chatwoot config path                           # Print config file path
chatwoot config view                           # Print config and credential source

Global Flags

Output Formats

Text (default) — human-readable tables:

ID   Status  Contact       Assignee       Inbox
194  open    Jane Doe      Shivam Mishra  WebWidget
197  open    Vinay K       Shivam Mishra  Whatsapp

JSON — full API response, pipe to jq:

chatwoot convs -o json | jq '.data.payload[].id'

CSV — for spreadsheets and data processing:

chatwoot agents -o csv > agents.csv

Quiet — IDs only, one per line:

chatwoot convs -q | xargs -I{} chatwoot conv view {}

License

MIT