From 63fb7a2b663558d480b509a78ac8c5a04b8b0270 Mon Sep 17 00:00:00 2001 From: Shivam Mishra Date: Fri, 25 Sep 2026 15:47:31 +0530 Subject: [PATCH 1/3] docs: document multiple accounts in the Chatwoot CLI --- cli.mdx | 19 +++--- cli/accounts.mdx | 163 ++++++++++++++++++++++++++++++++++++++++++++ cli/agent-skill.mdx | 3 + cli/commands.mdx | 30 ++++++-- cli/scripting.mdx | 10 ++- docs.json | 2 +- 6 files changed, 209 insertions(+), 18 deletions(-) create mode 100644 cli/accounts.mdx diff --git a/cli.mdx b/cli.mdx index eef32fba..6cc5a768 100644 --- a/cli.mdx +++ b/cli.mdx @@ -7,6 +7,7 @@ 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. 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, help centers. +- **[Multiple accounts](/cli/accounts)** — several accounts and instances, `@name`, and pasted dashboard links. - **[Scripting & output](/cli/scripting)** — JSON / CSV / quiet mode, shell completions, automation recipes. ## Install @@ -33,19 +34,17 @@ go install github.com/chatwoot/cli/cmd/chatwoot@latest ## Log in ```bash -chatwoot auth login +chatwoot auth login # asks for the URL (default: https://app.chatwoot.com) +chatwoot auth login staging.chatwoot.com # or pass it; any dashboard link works too ``` -You'll be asked for: +You'll be asked for your **access token**, from your profile settings in Chatwoot. The CLI validates it, then registers every account you belong to on that instance under a short name (`acme`, `globex-inc`) and asks which one is your default. Log in again to add another instance; see [Multiple accounts](/cli/accounts). -- **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. +The token 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 status # who am I, which instance and account +chatwoot accounts # your accounts (* = default) chatwoot auth logout # remove saved credentials chatwoot config view # show config and credential source ``` @@ -82,7 +81,7 @@ Issues and feedback: [github.com/chatwoot/cli](https://github.com/chatwoot/cli). ```bash chatwoot auth logout # remove API key from the OS keyring -rm -rf ~/.chatwoot # delete config (~/.chatwoot/config.yaml) +rm -rf ~/.chatwoot # delete config (~/.chatwoot/config.yaml and its backup) rm "$(command -v chatwoot)" # delete the binary ``` @@ -94,4 +93,4 @@ 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. +On Windows, delete the extracted `chatwoot.exe` and the `%USERPROFILE%\.chatwoot` folder. If `CHATWOOT_API_KEY` or `CHATWOOT_ACCOUNT` is set in your environment, unset it in your shell rc — `auth logout` can't remove env-provided credentials. diff --git a/cli/accounts.mdx b/cli/accounts.mdx new file mode 100644 index 00000000..b9764b4a --- /dev/null +++ b/cli/accounts.mdx @@ -0,0 +1,163 @@ +--- +title: Multiple accounts +description: Use the Chatwoot CLI with several accounts and instances, pick an account per command, and act on pasted dashboard links. +sidebarTitle: Multiple accounts +--- + +The CLI works with every account you belong to, across as many Chatwoot instances as you use (Chatwoot Cloud, staging, self-hosted). You log in once per instance, and each account gets a short name you can use on any command. + +## Log in once per instance + +```bash +chatwoot auth login # asks for the URL (default: Chatwoot Cloud) +chatwoot auth login staging.chatwoot.com # or pass it +``` + +After you enter your access token, every account you can see on that instance is registered under its own name: + +``` +✓ Logged in as Shivam Mishra (shivam@chatwoot.com) + + Found 3 accounts: + chatwoot #1 + acme #42 + globex-inc #77 + +Default account (chatwoot): +✓ Default set to chatwoot. Switch per command with @acme, or: chatwoot use acme +``` + +The URL can be a bare host (`staging.chatwoot.com`), a base URL, or any link copied from the dashboard. If the link points at an account (`…/app/accounts/42/…`), that account becomes the default on your first login. + +Chatwoot access tokens belong to your user, not to one account, so one login covers every account you're a member of on that instance. + +## Account names + +Names come from the account name in Chatwoot: lowercased, with spaces turned into dashes (`Globex Inc` → `globex-inc`). + +| Situation | Name | +|---|---| +| Same name on another instance | the host is added: `chatwoot-staging` | +| Same account seen by a second user on the same instance | the user's name is added: `acme-test-agent` | +| Name is empty or only digits | `account-` | + +Names never change once they're given, even if the account is renamed in Chatwoot, so scripts keep working. To pick your own: + +```bash +chatwoot accounts rename chatwoot-staging stg +``` + +## List accounts + +```bash +chatwoot accounts +``` + +``` + NAME HOST ID USER +* chatwoot app.chatwoot.com 1 Shivam Mishra + acme app.chatwoot.com 42 Shivam Mishra + chatwoot-staging staging.chatwoot.com 1 Shivam Mishra +``` + +`*` marks the default. `-o json` and `-q` (names only) work for scripts. + +## Pick an account + +Put `@name` before the command. A unique prefix is enough: + +```bash +chatwoot @acme convs +chatwoot @stg conv 123 reply "on it" +chatwoot @ac convs # error if more than one name starts with "ac" +``` + +The same, as a flag or an environment variable: + +```bash +chatwoot -a acme convs +CHATWOOT_ACCOUNT=acme chatwoot convs # one shell session, or CI +``` + +Without any of these, commands use the **default account**. Change it with `use`: + +```bash +chatwoot use acme # change the saved default +chatwoot use # show the current default +``` + + +`chatwoot use` changes the default for every terminal and every script on your machine. To switch for a single session, export `CHATWOOT_ACCOUNT` instead. + + +`-a` also accepts an account ID, as before: `-a 42` means account 42 on your default account's instance. + +When a command could pick up the account from more than one place, the first match wins: + +1. A pasted dashboard link +2. `@name` or `-a` +3. `CHATWOOT_ACCOUNT` +4. The default account + +## Paste a dashboard link + +Copy a link from the browser, Slack, or an alert and pass it in place of the noun and ID. The link already says which instance, account, and record you mean: + +```bash +chatwoot https://app.chatwoot.com/app/accounts/1/conversations/4521 +chatwoot https://app.chatwoot.com/app/accounts/1/conversations/4521 reply "on it" +chatwoot https://app.chatwoot.com/app/accounts/1/contacts/88 conversations +``` + +| Link | Runs | +|---|---| +| `…/conversations/`, including inbox, label, team, mention, and custom-view scoped links | `conv ` | +| `…/contacts/` | `contact ` | +| `…/inbox/` or `…/settings/inboxes/` | `inbox ` | +| any other page in an account | selects the account; lists conversations if nothing follows | + +If you aren't logged in to that instance yet, the CLI offers to log in first and then runs the command. In a script it stops and prints the `auth login` command to run instead. + +## Stay on the right account + +- A write (`reply`, `resolve`, `assign`, `label`, a non-GET `api` call, …) to an account other than your default prints the target to stderr before it runs, for example `→ acme`. Nothing is printed for the default account, and stdout stays clean for `-o json` and pipes. +- If a token stops working, the error says which user and instance it belongs to and how to log in again. + +## Keep accounts up to date + +Accounts you join or leave after logging in are picked up with: + +```bash +chatwoot accounts --refresh +``` + +``` + app.chatwoot.com + initech #91 + - globex-inc (no longer a member) + staging.chatwoot.com no changes +``` + +You rarely need it: an unknown `@name` refreshes once automatically before failing. + +## More than one user on an instance + +Logging in again on the same instance with **another user's** token adds a second login instead of replacing the first, for example your admin user and a test agent. Accounts both users can see appear twice, once per user (`acme` and `acme-test-agent`). + +## Log out + +```bash +chatwoot auth logout staging.chatwoot.com # one instance: its accounts and tokens +chatwoot auth logout # everything +``` + +## Upgrading from an earlier version + +Nothing to do. On the first run after upgrading, your existing login keeps working as your default account, and the CLI tells you once about any other accounts it found: + +``` +✓ Multiple accounts are here. You also have access to: + acme #42, globex-inc #77 + Use one with: chatwoot @acme convs (see: chatwoot accounts) +``` + +Your previous config is saved as `~/.chatwoot/config.yaml.bak`. Older CLI versions can't read the new config format; to go back to one, restore that file. diff --git a/cli/agent-skill.mdx b/cli/agent-skill.mdx index 8ff8873d..a2ad2c89 100644 --- a/cli/agent-skill.mdx +++ b/cli/agent-skill.mdx @@ -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. +- **Pinning the account** — check `chatwoot accounts`, then put `@name` on every command once it knows which account (or instance, like staging) you mean, and never change your default with `chatwoot use`. - **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 ` is a case-insensitive substring match, list endpoints paginate. @@ -50,6 +51,8 @@ Once the skill is installed, prompts like these work without further setup: - _"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`."_ +- _"On staging, list the unassigned conversations in the Acme account."_ +- _"Summarize https://app.chatwoot.com/app/accounts/1/conversations/4521."_ The agent composes `chatwoot` commands, parses JSON, and stops to confirm before any write that affects customers. diff --git a/cli/commands.mdx b/cli/commands.mdx index f1a5d95e..f2156e5e 100644 --- a/cli/commands.mdx +++ b/cli/commands.mdx @@ -14,6 +14,13 @@ Full command reference. New here? Start with **[Getting started](/cli)**. For ou Verb-first form (`chatwoot conv reply 123 "thanks"`) also works. +Two shortcuts work in front of any command: + +- **`@name` picks the account:** `chatwoot @acme conv 123 reply "thanks"` +- **A pasted dashboard link replaces the noun and id:** `chatwoot https://app.chatwoot.com/app/accounts/1/conversations/123 reply "thanks"` + +See **[Multiple accounts](/cli/accounts)** for how accounts are named and chosen. + ## Conversations ### List @@ -95,7 +102,7 @@ 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. +`hc articles` uses the saved default help center and locale. Defaults are saved per account. Pass `--portal` or `--locale` when you want to override them for one command. ```bash chatwoot hcs # list help centers @@ -127,12 +134,25 @@ chatwoot api --exact /api/v1/profile # non-account-scoped endpoint Use the application Swagger as the endpoint reference before raw API calls: [application_swagger.json](https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json). +## Accounts + +```bash +chatwoot accounts # list accounts (* = default) +chatwoot accounts --refresh # pick up accounts joined or left since login +chatwoot accounts rename chatwoot-staging stg # give an account your own name +chatwoot use acme # change the saved default account +chatwoot use # show the current default +chatwoot @acme convs # use an account for one command +``` + ## 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 auth login # interactive login; registers every account +chatwoot auth login staging.chatwoot.com # log in to another instance +chatwoot auth logout # remove all saved credentials +chatwoot auth logout staging.chatwoot.com # log out of one instance +chatwoot auth status # current user, instance, and account chatwoot config path # print config file path chatwoot config view # print config and credential source ``` @@ -150,7 +170,7 @@ chatwoot --version # same as `version`, as a flag | Flag | Short | Description | |------|-------|-------------| | `--output` | `-o` | Output format: `text`, `json`, `csv` | -| `--account` | `-a` | Override account ID | +| `--account` | `-a` | Account for this command: a name or unique prefix from `chatwoot accounts` (same as `@name`), or an account ID. Env: `CHATWOOT_ACCOUNT` | | `--quiet` | `-q` | Print only IDs (for scripting) | | `--no-color` | | Disable colored output | | `--verbose` | `-v` | Show request/response details | diff --git a/cli/scripting.mdx b/cli/scripting.mdx index a3535f62..c5b324ea 100644 --- a/cli/scripting.mdx +++ b/cli/scripting.mdx @@ -60,17 +60,23 @@ export CHATWOOT_API_KEY=your_token_here chatwoot convs --assignee all -o json ``` -Combine with `--account` to target a specific account: +Name the account on every command in a script, so it doesn't depend on whatever the default happens to be: ```bash -chatwoot --account 42 convs -o csv > convs.csv +chatwoot @acme convs -o csv > convs.csv +chatwoot -a acme convs -o csv > convs.csv # same, as a flag +CHATWOOT_ACCOUNT=acme chatwoot convs -o json # or for the whole job +chatwoot -a 42 convs -o json # an account ID works too ``` +`chatwoot accounts -o json` lists the registered accounts, and `chatwoot accounts -q` prints just their names. See [Multiple accounts](/cli/accounts). + 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. +- Writes to a non-default account print `→ ` to stderr before running. It never touches stdout, so `-o json` and pipes stay clean. - Use `--no-color` when redirecting text output to a file or another program that doesn't strip ANSI codes. - `chatwoot --help` and `chatwoot --help` are exhaustive — the CLI's help is generated from the same definitions that drive the binary. diff --git a/docs.json b/docs.json index 8cbb3a5e..1607050d 100644 --- a/docs.json +++ b/docs.json @@ -40,7 +40,7 @@ "pages": [ { "group": "Getting Started", - "pages": ["cli", "cli/commands", "cli/scripting", "cli/agent-skill"] + "pages": ["cli", "cli/commands", "cli/accounts", "cli/scripting", "cli/agent-skill"] } ] }, From df2500b98f87f69d7a20e7c06faa916f3b39240f Mon Sep 17 00:00:00 2001 From: Shivam Mishra Date: Fri, 25 Sep 2026 15:58:00 +0530 Subject: [PATCH 2/3] docs: surface multiple accounts across the CLI pages --- cli.mdx | 14 +++++++++++++- cli/accounts.mdx | 4 ++++ cli/agent-skill.mdx | 6 +++++- cli/commands.mdx | 23 +++++++++++++++++++++-- cli/scripting.mdx | 21 +++++++++++++++++++++ 5 files changed, 64 insertions(+), 4 deletions(-) diff --git a/cli.mdx b/cli.mdx index 6cc5a768..f95eb1b4 100644 --- a/cli.mdx +++ b/cli.mdx @@ -4,7 +4,7 @@ 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. 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. +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 works across every account you belong to, on as many instances as you use (Chatwoot Cloud, staging, self-hosted), and you can paste a dashboard link straight into a command. 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, help centers. - **[Multiple accounts](/cli/accounts)** — several accounts and instances, `@name`, and pasted dashboard links. @@ -49,6 +49,17 @@ chatwoot auth logout # remove saved credentials chatwoot config view # show config and credential source ``` +## First commands + +```bash +chatwoot convs # your open conversations +chatwoot conv 123 reply "Looking into it" # reply to one +chatwoot @acme convs # same list, in another account +chatwoot https://app.chatwoot.com/app/accounts/1/conversations/123 # paste a dashboard link +``` + +Commands run against your default account unless you name another with `@name`. See [Multiple accounts](/cli/accounts). + ## Shell completions The install script offers to set this up interactively. To do it manually: @@ -73,6 +84,7 @@ chatwoot --help chatwoot conv --help chatwoot convs --help chatwoot hc --help +chatwoot accounts --help ``` Issues and feedback: [github.com/chatwoot/cli](https://github.com/chatwoot/cli). diff --git a/cli/accounts.mdx b/cli/accounts.mdx index b9764b4a..eaeed716 100644 --- a/cli/accounts.mdx +++ b/cli/accounts.mdx @@ -143,6 +143,10 @@ You rarely need it: an unknown `@name` refreshes once automatically before faili Logging in again on the same instance with **another user's** token adds a second login instead of replacing the first, for example your admin user and a test agent. Accounts both users can see appear twice, once per user (`acme` and `acme-test-agent`). +## Scripts and agents + +In a script, name the account on every command instead of relying on the default, and never call `chatwoot use`. [Scripting & output](/cli/scripting) has recipes, including running a command across every account. The [agent skill](/cli/agent-skill) teaches coding agents the same rules. + ## Log out ```bash diff --git a/cli/agent-skill.mdx b/cli/agent-skill.mdx index a2ad2c89..b0ba9c51 100644 --- a/cli/agent-skill.mdx +++ b/cli/agent-skill.mdx @@ -24,12 +24,16 @@ The skill activates automatically when you ask the agent to do something Chatwoo ## 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: +Coding agents run commands non-interactively, so `chatwoot auth login` has to be run separately. Once you've logged in, the agent can use every account you have, and it will name the account on each command (`@acme`) rather than relying on your default. Mention the account or instance in your prompt ("on staging…") when it matters, or paste a dashboard link. + +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 ``` +That token applies to every account, so it only works for accounts on the instance it was created on. + ## What the skill teaches the agent - **The id-first grammar** — `chatwoot conv 123 reply "..."` instead of guessing flag layouts. diff --git a/cli/commands.mdx b/cli/commands.mdx index f2156e5e..10a5286c 100644 --- a/cli/commands.mdx +++ b/cli/commands.mdx @@ -32,6 +32,7 @@ chatwoot convs --assignee all # me (default) | unassigned | all chatwoot convs --inbox 5 # filter by inbox ID chatwoot convs -l billing,urgent # filter by labels chatwoot convs --query "refund" # search by message content +chatwoot @acme convs --assignee all # any command: @name runs it in another account ``` ### Act on one @@ -41,6 +42,17 @@ chatwoot conv 123 # view (default) chatwoot conv 123 messages # list messages ``` +Copied a link from the dashboard, Slack, or an alert? Use it in place of `conv 123`. It carries its own account, so it works whichever account is your default: + +```bash +chatwoot https://app.chatwoot.com/app/accounts/1/conversations/123 messages +chatwoot https://app.chatwoot.com/app/accounts/1/inbox/5/conversations/123 resolve +``` + + +Conversation IDs are only unique within an account, so `conv 123` on staging and production are different conversations. When you write to an account other than your default, the CLI prints `→ ` to stderr first so you can see where it went. + + **Reply:** ```bash @@ -88,6 +100,7 @@ chatwoot contacts # list chatwoot contacts --search "john" # name, email, or phone chatwoot contact 456 # view chatwoot contact 456 conversations # this contact's conversations +chatwoot https://app.chatwoot.com/app/accounts/1/contacts/456 # or from a pasted link ``` ## Inboxes, agents, labels, teams @@ -100,9 +113,11 @@ chatwoot labels # list account-level labels chatwoot teams # list teams ``` +These all list the current account's resources. Add `@name` to look at another account, for example `chatwoot @acme agents`. + ## Help centers -`hc articles` uses the saved default help center and locale. Defaults are saved per account. Pass `--portal` or `--locale` when you want to override them for one command. +`hc articles` uses the saved default help center and locale. Defaults are saved per account, so each account can have its own (`chatwoot @acme hc default acme-help`). Pass `--portal` or `--locale` when you want to override them for one command. ```bash chatwoot hcs # list help centers @@ -120,16 +135,20 @@ chatwoot hc articles --portal user-guide --locale en ```bash chatwoot me # your profile (alias of auth status) chatwoot whoami # same +chatwoot @staging whoami # who you are on another account ``` +The output includes the instance and account the command ran against, which is the quickest way to check where a command will go. + ## Raw API -Use `chatwoot api` for authenticated API calls that do not have a first-class CLI command yet. Account-relative paths are expanded under `/api/v1/accounts/`, so do not include the `/api/v1/accounts/...` prefix. +Use `chatwoot api` for authenticated API calls that do not have a first-class CLI command yet. Account-relative paths are expanded under `/api/v1/accounts/` for the current account (the default, or the one you name with `@name`), so do not include the `/api/v1/accounts/...` prefix. ```bash chatwoot api /conversations/123 # GET /api/v1/accounts//conversations/123 chatwoot api -X PATCH /conversations/123 --data '{"status":"open"}' chatwoot api --exact /api/v1/profile # non-account-scoped endpoint +chatwoot @staging api /conversations/123 # same call, on another account ``` Use the application Swagger as the endpoint reference before raw API calls: [application_swagger.json](https://raw.githubusercontent.com/chatwoot/chatwoot/develop/swagger/tag_groups/application_swagger.json). diff --git a/cli/scripting.mdx b/cli/scripting.mdx index c5b324ea..e1f08c45 100644 --- a/cli/scripting.mdx +++ b/cli/scripting.mdx @@ -51,6 +51,12 @@ chatwoot convs --assignee all -o csv > "convs-$(date +%F).csv" chatwoot convs -q | xargs -I{} chatwoot conv {} resolve ``` +If you use more than one account, name it on **both** sides of the pipe. IDs from one account mean different conversations in another: + +```bash +chatwoot @acme convs -q | xargs -I{} chatwoot @acme conv {} resolve +``` + ## Headless / CI use The OS keyring isn't available in most CI environments. Set `CHATWOOT_API_KEY` to override the saved token: @@ -60,6 +66,10 @@ export CHATWOOT_API_KEY=your_token_here chatwoot convs --assignee all -o json ``` + +`CHATWOOT_API_KEY` replaces the token for **every** account. Tokens belong to one user on one instance, so only use it with accounts on that instance, and set it per job rather than globally if you script against several instances. + + Name the account on every command in a script, so it doesn't depend on whatever the default happens to be: ```bash @@ -71,6 +81,16 @@ chatwoot -a 42 convs -o json # an account ID works too `chatwoot accounts -o json` lists the registered accounts, and `chatwoot accounts -q` prints just their names. See [Multiple accounts](/cli/accounts). +### Across every account + +Loop over `accounts -q` to run the same command in each account: + +```bash +for acct in $(chatwoot accounts -q); do + echo "$acct: $(chatwoot @"$acct" convs --assignee all -s open -o json | jq '.data.meta.all_count')" +done +``` + Add `-v` / `--verbose` to print every HTTP request and response to stderr — handy when something looks wrong. ## Tips @@ -78,5 +98,6 @@ Add `-v` / `--verbose` to print every HTTP request and response to stderr — ha - `-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. - Writes to a non-default account print `→ ` to stderr before running. It never touches stdout, so `-o json` and pipes stay clean. +- Don't call `chatwoot use` from a script: it changes the default for every other terminal and job on the machine. Pass `@name`, `-a`, or `CHATWOOT_ACCOUNT` instead. - Use `--no-color` when redirecting text output to a file or another program that doesn't strip ANSI codes. - `chatwoot --help` and `chatwoot --help` are exhaustive — the CLI's help is generated from the same definitions that drive the binary. From af8353db617d4a0a4756f0f382b4ede6b4696523 Mon Sep 17 00:00:00 2001 From: Shivam Mishra Date: Fri, 25 Sep 2026 15:59:44 +0530 Subject: [PATCH 3/3] docs: fold accounts and links into the CLI grammar --- cli/commands.mdx | 19 +++++++++---------- 1 file changed, 9 insertions(+), 10 deletions(-) diff --git a/cli/commands.mdx b/cli/commands.mdx index 10a5286c..ec544753 100644 --- a/cli/commands.mdx +++ b/cli/commands.mdx @@ -8,18 +8,17 @@ Full command reference. New here? Start with **[Getting started](/cli)**. For ou ## 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 +Every command reads left to right, the way you'd say it: **where**, **what**, **which one**, then **what to do**. -Verb-first form (`chatwoot conv reply 123 "thanks"`) also works. +| Shape | Means | Example | +|---|---|---| +| Plural noun | list | `chatwoot convs`, `chatwoot contacts`, `chatwoot agents` | +| Singular noun + id | view | `chatwoot conv 123` | +| Singular noun + id + verb | act (id before verb, the way you'd say it) | `chatwoot conv 123 reply "thanks"` | +| `@account` + any of the above | the same, in another account (leave it out for your default) | `chatwoot @acme conv 123 reply "thanks"` | +| Dashboard link + verb | the link is account + noun + id in one | `chatwoot https://app.chatwoot.com/app/accounts/1/conversations/123 reply "thanks"` | -Two shortcuts work in front of any command: - -- **`@name` picks the account:** `chatwoot @acme conv 123 reply "thanks"` -- **A pasted dashboard link replaces the noun and id:** `chatwoot https://app.chatwoot.com/app/accounts/1/conversations/123 reply "thanks"` - -See **[Multiple accounts](/cli/accounts)** for how accounts are named and chosen. +Verb-first form (`chatwoot conv reply 123 "thanks"`) also works. See **[Multiple accounts](/cli/accounts)** for how accounts are named and chosen. ## Conversations