> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chattermate.chat/llms.txt
> Use this file to discover all available pages before exploring further.

# AI Agent Quickstart

> Go from nothing to a live ChatterMate AI agent with a copy-paste CLI path built for AI agents, CI pipelines, and automation, with JSON output on every command.

# AI Agent & Automation Quickstart

This is the fastest, copy-paste path from **nothing** to a **live ChatterMate agent** — designed to
be run by an AI agent, a CI pipeline, or anyone scripting their setup. Every command supports
`--json` for machine-readable output.

> [!NOTE]
>
> Use the **ChatterMate CLI** (`chattermate`) for account, agent, workflow, and knowledge setup. It is
> installed from the `chattermate-cli` Python package. This is **not** the self-host Docker tool
> (`npm install -g chattermate-deploy`) — see [Quickstart → Self-host](https://docs.chattermate.chat/quickstart.md#option-b-self-host-with-docker)
> for that.

## Set up from your AI coding tool

Paste this into Claude Code, Cursor, Codex or Windsurf. You sign up in your own terminal, so your
password never goes through the AI tool; it does the rest.

```text Paste this into your AI tool theme={null}
Set up ChatterMate (AI customer support chat) for my website with its CLI.
1. Install it: pipx install chattermate-cli (or: uv tool install chattermate-cli)
2. Ask me to run this in my own terminal, not through you, so my password stays with me:
   chattermate signup --ref website-ai-prompt
   It asks for my details, a password and the code emailed to me. Wait until I say it is done.
3. Create the agent: chattermate agent create --name "Support" --type customer_support --json
4. Teach it my site: chattermate knowledge add-url --website <my website> --agent-id <agent id>
5. Run chattermate widget create --agent-id <agent id> and add the snippet it
   prints to this project's root layout, just before </body>.
```

> [accordion] Already have an account?
>
> Use this version instead. The dashboard's Create step gives you the same text, ready to copy.
>
> ```text theme={null}
> Set up my ChatterMate support agent and chat widget with its CLI.
> 1. Install it: pipx install chattermate-cli (or: uv tool install chattermate-cli)
> 2. Ask me to run this in my own terminal, not through you, so my password stays with me:
>    chattermate login
>    It asks for my email and password. Wait until I say it is done.
> 3. Find my agent: chattermate agent list --json. Only if I have none, create one:
>    chattermate agent create --name "Support" --type customer_support --json
> 4. Teach it my site: chattermate knowledge add-url --website <my website> --agent-id <agent id>
> 5. Run chattermate widget create --agent-id <agent id> and add the snippet it
>    prints to this project's root layout, just before </body>.
> ```

> [accordion] Self-hosted?
>
> Point the command you run yourself at your server. The CLI saves it for every later command:
>
> ```bash theme={null}
> chattermate --api-url https://api.example.com signup   # or: ... login
> ```
>
> Use your API's origin, without `/api/v1`. Also add `--app-url <your dashboard URL>` to
> `chattermate widget create`, so the snippet loads the widget from your own dashboard. Your
> dashboard's copy of the prompt already includes both.

> [card] [Add MCP to Cursor](https://cursor.com/install-mcp?name=chattermate\&config=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyItLWZyb20iLCJjaGF0dGVybWF0ZS1jbGkiLCJjaGF0dGVybWF0ZS1tY3AiXSwiZW52Ijp7IkNIQVRURVJNQVRFX1RPS0VOIjoiY21hdF95b3VyX3Rva2VuX2hlcmUifX0%3D)
>
> Install the MCP server, then swap in your own token.

> [card] [CLI docs](https://docs.chattermate.chat/features/cli.md)
>
> Every command, flag and environment variable.

> [card] [Prefer the browser?](https://app.chattermate.chat/signup?utm_source=docs\&utm_medium=ai-prompt)
>
> Sign up in the dashboard instead.

## TL;DR

```bash theme={null}
pip install chattermate-cli            # Python
# or:  npm install -g chattermate-cli  # npm wrapper (needs uv or pipx on PATH)

# 1. Create an account — a one-time code is emailed to --admin-email.
#    Pass it with --otp (or enter at the prompt); you're logged in automatically.
#    Self-hosted single-org instance? Add --community to skip OTP.
chattermate signup \
  --name "Acme Inc" \
  --domain acme.com \
  --admin-email admin@acme.com \
  --admin-name "Ada Admin" \
  --otp 123456
  # --admin-password is prompted securely (pass it explicitly for non-interactive use)

# 2. Create an agent
chattermate agent create \
  --name "Support" \
  --type customer_support \
  -i "Be concise and friendly" \
  -i "Escalate billing questions to a human" \
  --json

# 3. Feed it your knowledge (attach to the agent from step 2)
chattermate knowledge add-url \
  --website https://docs.acme.com \
  --pdf-url https://acme.com/guide.pdf \
  --agent-id <agent-id>

# 4. (Optional) mint a long-lived token for headless / MCP use
chattermate token create ci --expires-in-days 90
```

## Prerequisites

* Install the CLI with **pip** (`pip install chattermate-cli`, or `pipx`/`uvx`) — needs Python 3.10+.
  Prefer **npm**? `npm install -g chattermate-cli` installs the identical CLI as a wrapper that runs
  the Python one via `uv`/`pipx`, so you need `uv` or `pipx` on your PATH. See the
  [CLI reference](https://docs.chattermate.chat/features/cli.md#installation) for all install options.
* Nothing else — the CLI targets the hosted API (`https://api.chattermate.chat`) by default. Set
  `CHATTERMATE_API_URL=http://localhost:8000` to target a local/self-hosted backend.

## Step 1 — Authenticate

Pick one:

> [tab] Sign up (new org)
>
> ```bash theme={null}
> chattermate signup --name "Acme Inc" --domain acme.com \
>   --admin-email admin@acme.com --admin-name "Ada Admin"
> ```
>
> Creates an organization + admin user and logs you in. Add `--json` to capture the result.

> [tab] Personal Access Token (headless)
>
> Best for AI agents and CI. Create the token once (from an interactive login), then export it:
>
> ```bash theme={null}
> export CHATTERMATE_TOKEN=cmat_xxxxxxxxxxxxxxxxxxxx
> chattermate whoami --json
> ```
>
> See [CLI → Personal Access Tokens](https://docs.chattermate.chat/features/cli.md#personal-access-tokens).

## Step 2 — Create an agent

```bash theme={null}
chattermate agent create \
  --name "Support" \
  --type customer_support \
  -i "Answer from the knowledge base; be concise" \
  --json
```

`--type` is one of `customer_support`, `sales`, `tech_support`, `general`, `custom`. The `--json`
output includes the new `id` — capture it for the next steps.

## Step 3 — Add knowledge

From a URL, or upload local PDF file(s):

```bash theme={null}
# From a website / PDF URL
chattermate knowledge add-url \
  --website https://docs.acme.com \
  --agent-id <agent-id> \
  --json

# From local PDF file(s) on disk
chattermate knowledge add-file ./guide.pdf ./faq.pdf --agent-id <agent-id> --json

# Track ingestion progress
chattermate knowledge status <queue-id>
```

## Step 4 — Go live with the widget

Create a widget for the agent from the CLI — it prints the **widget id** and the embed snippet:

```bash theme={null}
chattermate widget create --agent-id <agent-id> --name "Website widget"
# already have one? list them:  chattermate widget list <agent-id>
```

Then drop the snippet on any page:

```html theme={null}
<script>
  window.chattermateId='YOUR_WIDGET_ID';
</script>
<script src="https://app.chattermate.chat/webclient/chattermate.min.js"></script>
```

For **authenticated** widgets (per-user tokens), create a [Widget App](https://docs.chattermate.chat/features/widget-apps.md) to get
an API key, then mint short-lived tokens server-side:

```bash theme={null}
curl -X POST https://api.chattermate.chat/api/v1/generate-token \
  -H "Authorization: Bearer $WIDGET_APP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"widget_id":"YOUR_WIDGET_ID","customer_email":"user@customer.com","ttl_seconds":3600}'
```

## Drive it over MCP instead of the shell

Prefer to let your AI agent configure ChatterMate through the Model Context Protocol? The same
package ships an MCP server (`chattermate-mcp`). See the [MCP Server guide](https://docs.chattermate.chat/features/mcp-server.md) for
a ready-to-paste client config — it authenticates with the same `cmat_` Personal Access Token.

## Command reference

| Step | Command |
| - | - |
| Install | `pip install chattermate-cli` (or `npm install -g chattermate-cli`) |
| Sign up | `chattermate signup --name … --domain … --admin-email … --admin-name …` |
| AI model | auto-set to the free ChatterMate model at signup; switch with `chattermate ai setup --model-type … --api-key …` |
| Log in | `chattermate login --email you@acme.com`, or `chattermate login --token` for Google/Microsoft sign-in |
| Token | `chattermate token create <name> [--expires-in-days N]` |
| Agent | `chattermate agent create --name … --type … -i "…"` |
| Knowledge (URL) | `chattermate knowledge add-url --website … [--agent-id …]` |
| Knowledge (local PDF) | `chattermate knowledge add-file ./guide.pdf [--agent-id …]` |
| Workflow | `chattermate workflow create --agent-id … --name …` |

> [card] [CLI reference](https://docs.chattermate.chat/features/cli.md)
>
> Every command, flag, and environment variable.

> [card] [MCP Server](https://docs.chattermate.chat/features/mcp-server.md)
>
> Let an AI agent configure ChatterMate over MCP.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.