docs: multiple accounts in the Chatwoot CLI

cli.mdx

@@ -4,9 +4,10 @@ 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.
 - **[Scripting & output](/cli/scripting)** — JSON / CSV / quiet mode, shell completions, automation recipes.
 
 ## Install
@@ -33,23 +34,32 @@ 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
 ```
 
+## 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:
@@ -74,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).
@@ -82,7 +93,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 +105,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.

cli/accounts.mdx

@@ -0,0 +1,167 @@
+---
+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-<id>` |
+
+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
+```
+
+<Note>
+`chatwoot use` changes the default for every terminal and every script on your machine. To switch for a single session, export `CHATWOOT_ACCOUNT` instead.
+</Note>
+
+`-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/<id>`, including inbox, label, team, mention, and custom-view scoped links | `conv <id>` |
+| `…/contacts/<id>` | `contact <id>` |
+| `…/inbox/<id>` or `…/settings/inboxes/<id>` | `inbox <id>` |
+| 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`).
+
+## 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
+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.

cli/agent-skill.mdx

@@ -24,16 +24,21 @@ 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.
 - **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 <name>` is a case-insensitive substring match, list endpoints paginate.
@@ -50,6 +55,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.