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.

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 for that.

TL;DR

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 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:

Sign up (new org)
Personal Access Token (headless)

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.

Best for AI agents and CI. Create the token once (from an interactive login), then export it:

export CHATTERMATE_TOKEN=cmat_xxxxxxxxxxxxxxxxxxxx
chattermate whoami --json

See CLI → Personal Access Tokens.

Step 2 — Create an agent

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):

# 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>

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

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:

<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 to get an API key, then mint short-lived tokens server-side:

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 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 …`

CLI reference

Every command, flag, and environment variable.

MCP Server

Let an AI agent configure ChatterMate over MCP.

Getting Started

Features

Channels

Developer Tools

Deployment

AI Agent Quickstart

AI Agent & Automation Quickstart

TL;DR

Prerequisites

Step 1 — Authenticate

Step 2 — Create an agent

Step 3 — Add knowledge

Step 4 — Go live with the widget

Drive it over MCP instead of the shell

Command reference

CLI reference

MCP Server

​AI Agent & Automation Quickstart

​TL;DR

​Prerequisites

​Step 1 — Authenticate

​Step 2 — Create an agent

​Step 3 — Add knowledge

​Step 4 — Go live with the widget

​Drive it over MCP instead of the shell

​Command reference

CLI reference

MCP Server

AI Agent & Automation Quickstart

TL;DR

Prerequisites

Step 1 — Authenticate

Step 2 — Create an agent

Step 3 — Add knowledge

Step 4 — Go live with the widget

Drive it over MCP instead of the shell

Command reference