feat: add docs for Chatwoot CLI

cli.mdx

@@ -0,0 +1,78 @@
+---
+title: Chatwoot CLI
+description: Install and configure the Chatwoot CLI to manage your inbox from the terminal.
+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.
+
+- **[Commands](/cli/commands)** — the full command reference: conversations, contacts, inboxes, agents.
+- **[Scripting & output](/cli/scripting)** — JSON / CSV / quiet mode, shell completions, automation recipes.
+
+## Install
+
+```bash
+# macOS / Linux
+curl -fsSL https://chwt.app/install-cli | sh
+```
+
+Installs to `~/.local/bin/chatwoot`. Override with `CHATWOOT_VERSION` or `CHATWOOT_INSTALL_DIR`:
+
+```bash
+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](https://github.com/chatwoot/cli/releases/latest) and extract `chatwoot.exe`.
+
+**From source** (Go 1.25+):
+
+```bash
+go install github.com/chatwoot/cli/cmd/chatwoot@latest
+```
+
+## Log in
+
+```bash
+chatwoot auth login
+```
+
+You'll be asked for:
+
+- **Base URL** — your Chatwoot instance, e.g. `https://app.chatwoot.com`
+- **API Key** — from your agent profile → API access token
+- **Account ID** — the number in your dashboard URL
+
+Credentials are validated before saving. The API key is stored in your OS keyring; non-secret config lives at `~/.chatwoot/config.yaml`. For CI or headless use, set `CHATWOOT_API_KEY` to override the saved token.
+
+```bash
+chatwoot auth status     # who am I, which instance
+chatwoot auth logout     # remove saved credentials
+chatwoot config view     # show config and credential source
+```
+
+## Shell completions
+
+The install script offers to set this up interactively. To do it manually:
+
+```bash
+# bash
+chatwoot completion bash -c > ~/.local/share/bash-completion/completions/chatwoot
+
+# fish
+chatwoot completion fish -c > ~/.config/fish/completions/chatwoot.fish
+
+# zsh — append a source line to your .zshrc
+echo 'source <(chatwoot completion zsh -c)' >> ~/.zshrc
+```
+
+Restart your shell (or `source` your rc file). Tab-completion works for commands, subcommands, and flags. Run `chatwoot completion --help` for details.
+
+## Help
+
+```bash
+chatwoot --help
+chatwoot conv --help
+chatwoot convs --help
+```
+
+Issues and feedback: [github.com/chatwoot/cli](https://github.com/chatwoot/cli).

cli/agent-skill.mdx

@@ -0,0 +1,59 @@
+---
+title: Agent skill
+description: Install the Chatwoot CLI agent skill so coding tools like Claude Code, Cursor, and Codex can use chatwoot effectively.
+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.
+
+## Install
+
+The skill is published in the [chatwoot/cli](https://github.com/chatwoot/cli) repository. Use the [skills CLI](https://skills.sh) to install it into whichever AI tool you use:
+
+```bash
+npx skills add chatwoot/cli
+```
+
+The skills CLI auto-detects the coding agents you have installed and offers to install the skill into each. Add `--global` (or `-g`) to install the skill once for every project:
+
+```bash
+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"_.
+
+## Authenticate the agent
+
+Coding agents run commands non-interactively, so `chatwoot auth login` has to be run separately. In certain scenarios, agents might be run in a sandbox environment so the API token may not be accessible to them. In this case, you can set the `CHATWOOT_API_KEY` in your shell or the agent's environment:
+
+```bash
+export CHATWOOT_API_KEY=your_token_here
+```
+
+## What the skill teaches the agent
+
+- **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.
+- **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.
+
+The full skill source lives at [chatwoot/cli/skills/chatwoot-cli](https://github.com/chatwoot/cli/tree/main/skills/chatwoot-cli) read it directly to see exactly what behavior is shaped.
+
+## Example prompts
+
+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."_
+- _"Resolve every open conversation tagged `spam`."_
+
+The agent composes `chatwoot` commands, parses JSON, and stops to confirm before any write that affects customers.
+
+## Remove the skill
+
+```bash
+npx skills remove chatwoot-cli                    # all agents
+npx skills remove chatwoot-cli --agent claude-code  # one agent
+```

cli/commands.mdx

@@ -0,0 +1,118 @@
+---
+title: CLI Commands
+description: Learn the Chatwoot CLI command grammar and commonly used commands.
+sidebarTitle: Commands
+---
+
+Full command reference. New here? Start with **[Getting started](/cli)**. For output formats and automation, see **[Scripting & output](/cli/scripting)**.
+
+## Grammar at a glance
+
+- **Plural noun = list:** `chatwoot convs`, `chatwoot contacts`, `chatwoot agents`
+- **Singular + id = view:** `chatwoot conv 123` shows conversation 123
+- **Singular + id + verb = act:** `chatwoot conv 123 reply "thanks"` — id before verb, the way you'd say it
+
+Verb-first form (`chatwoot conv reply 123 "thanks"`) also works.
+
+## Conversations
+
+### List
+
+```bash
+chatwoot convs                                 # open conversations assigned to you (default)
+chatwoot convs -s resolved                     # by status: open | resolved | pending | snoozed
+chatwoot convs --assignee all                  # me (default) | unassigned | all | <name> | <id>
+chatwoot convs --inbox 5                       # filter by inbox ID
+chatwoot convs -l billing,urgent               # filter by labels
+chatwoot convs --query "refund"                # search by message content
+```
+
+### Act on one
+
+```bash
+chatwoot conv 123                              # view (default)
+chatwoot conv 123 messages                     # list messages
+```
+
+**Reply:**
+
+```bash
+chatwoot conv 123 reply "Thanks, looking into it"
+chatwoot conv 123 reply "internal note" --private
+```
+
+**Status:**
+
+```bash
+chatwoot conv 123 resolve
+chatwoot conv 123 open
+chatwoot conv 123 pending
+chatwoot conv 123 snooze                       # snooze until next reply
+chatwoot conv 123 snooze --until 24h           # 7d, 2026-05-10, ...
+```
+
+**Assignment:**
+
+```bash
+chatwoot conv 123 assign --agent me            # yourself
+chatwoot conv 123 assign --agent alice         # case-insensitive substring on name
+chatwoot conv 123 assign --agent 42            # by agent ID
+chatwoot conv 123 assign --team 7              # assign to a team
+chatwoot conv 123 unassign
+```
+
+**Labels & priority:**
+
+```bash
+chatwoot conv 123 label billing,urgent         # sets labels (replaces existing)
+chatwoot conv 123 priority urgent              # urgent | high | medium | low | none
+```
+
+## Contacts
+
+```bash
+chatwoot contacts                              # list
+chatwoot contacts --search "john"              # name, email, or phone
+chatwoot contact 456                           # view
+chatwoot contact 456 conversations             # this contact's conversations
+```
+
+## Inboxes, agents, labels, teams
+
+```bash
+chatwoot inboxes                               # list inboxes
+chatwoot inbox 5                               # view one
+chatwoot agents                                # list agents
+chatwoot labels                                # list account-level labels
+chatwoot teams                                 # list teams
+```
+
+## Profile
+
+```bash
+chatwoot me                                    # your profile (alias of auth status)
+chatwoot whoami                                # same
+```
+
+## Auth & config
+
+```bash
+chatwoot auth login                            # interactive login (caches user_id)
+chatwoot auth logout                           # remove saved credentials
+chatwoot auth status                           # current user and instance
+chatwoot config path                           # print config file path
+chatwoot config view                           # print config and credential source
+```
+
+## Global flags
+
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--output` | `-o` | Output format: `text`, `json`, `csv` |
+| `--account` | `-a` | Override account ID |
+| `--quiet` | `-q` | Print only IDs (for scripting) |
+| `--no-color` | | Disable colored output |
+| `--verbose` | `-v` | Show request/response details |
+| `--version` | | Print version |
+
+For pipelines and exports using these flags, see **[Scripting & output](/cli/scripting)**.

cli/scripting.mdx

@@ -0,0 +1,76 @@
+---
+title: CLI Scripting
+description: Use Chatwoot CLI output formats and shell recipes to automate support workflows.
+sidebarTitle: Scripting
+---
+
+Everything for automating chatwoot-cli: output formats and headless/CI use. Need a command? See **[Commands](/cli/commands)**. For shell completion setup, see **[Getting started](/cli#shell-completions)**.
+
+## Output formats
+
+Every command takes `-o` / `--output`:
+
+| Format | Flag | Use it for |
+|---|---|---|
+| Text table | *(default)* | reading at a glance |
+| JSON | `-o json` | piping to `jq`, full API response |
+| CSV | `-o csv` | spreadsheets, data exports |
+| IDs only | `-q` / `--quiet` | shell pipelines |
+
+### 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, ready for `jq`:
+
+```bash
+chatwoot convs -o json | jq '.data.payload[].id'
+chatwoot conv 123 -o json | jq '.assignee.name'
+```
+
+### CSV
+
+```bash
+chatwoot agents -o csv > agents.csv
+chatwoot convs --assignee all -o csv > "convs-$(date +%F).csv"
+```
+
+### Quiet — IDs only
+
+`-q` prints just the IDs, one per line — perfect for `xargs`:
+
+```bash
+chatwoot convs -q | xargs -I{} chatwoot conv {} resolve
+```
+
+## Headless / CI use
+
+The OS keyring isn't available in most CI environments. Set `CHATWOOT_API_KEY` to override the saved token:
+
+```bash
+export CHATWOOT_API_KEY=your_token_here
+chatwoot convs --assignee all -o json
+```
+
+Combine with `--account` to target a specific account:
+
+```bash
+chatwoot --account 42 convs -o csv > convs.csv
+```
+
+Add `-v` / `--verbose` to print every HTTP request and response to stderr — handy when something looks wrong.
+
+## Tips
+
+- `-q` is your friend — every list command supports it, every `xargs` pipeline starts with it.
+- Pipe to `jq` early and aggressively; `-o json` returns the full Chatwoot response, not a slimmed-down view.
+- Use `--no-color` when redirecting text output to a file or another program that doesn't strip ANSI codes.
+- `chatwoot --help` and `chatwoot <command> --help` are exhaustive — the CLI's help is generated from the same definitions that drive the binary.

docs.json

@@ -34,6 +34,16 @@
         "icon": "house",
         "pages": ["introduction"]
       },
+      {
+        "anchor": "Chatwoot CLI",
+        "icon": "terminal",
+        "pages": [
+          {
+            "group": "Getting Started",
+            "pages": ["cli", "cli/commands", "cli/scripting", "cli/agent-skill"]
+          }
+        ]
+      },
       {
         "anchor": "Installation & Setup",
         "icon": "server",