> ## 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](/quickstart#option-b-self-host-with-docker)
  for that.
</Note>

## 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](/features/cli#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:

<Tabs>
  <Tab title="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>

  <Tab title="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](/features/cli#personal-access-tokens).
  </Tab>
</Tabs>

## 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](/features/widget-apps) 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](/features/mcp-server) 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`                                                                        |
| 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 …`                                                             |

<CardGroup cols={2}>
  <Card title="CLI reference" icon="terminal" href="/features/cli">
    Every command, flag, and environment variable.
  </Card>

  <Card title="MCP Server" icon="plug" href="/features/mcp-server">
    Let an AI agent configure ChatterMate over MCP.
  </Card>
</CardGroup>