Skip to main content

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

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

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

StepCommand
Installpip install chattermate-cli (or npm install -g chattermate-cli)
Sign upchattermate signup --name … --domain … --admin-email … --admin-name …
AI modelauto-set to the free ChatterMate model at signup; switch with chattermate ai setup --model-type … --api-key …
Log inchattermate login --email you@acme.com
Tokenchattermate token create <name> [--expires-in-days N]
Agentchattermate 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 …]
Workflowchattermate workflow create --agent-id … --name …

CLI reference

Every command, flag, and environment variable.

MCP Server

Let an AI agent configure ChatterMate over MCP.