ChatterMate CLI

The ChatterMate CLI (chattermate) lets you sign up, log in, mint access tokens, and configure agents, workflows, and knowledge sources directly from your terminal — no browser required. It’s ideal for automation, CI pipelines, and scripting your ChatterMate setup.

The CLI and MCP server are part of the enterprise/commercial edition. They authenticate with Personal Access Tokens, which require the enterprise backend.

Not the tool you were looking for? This page is the account CLI — it signs you up and manages agents, workflows, and knowledge against the ChatterMate API. If you want to self-host ChatterMate with Docker, you need the separate self-host CLI (npm install -g chattermate-deploy), documented in the Quickstart → Self-host. Both install a chattermate command, but they are different tools.

Installation

The CLI installs two commands: chattermate (with the alias cmate) and chattermate-mcp. Install it from PyPI (chattermate-cli) or npm (chattermate-cli, a thin wrapper that runs the Python CLI via uvx/pipx).

pipx install chattermate-cli

pip install chattermate-cli

npm install -g chattermate-cli

uvx --from chattermate-cli chattermate --help

The npm package requires uv or pipx on your PATH (it launches the Python CLI). Prefer pure Python? Use pip/pipx directly.

Verify the install:

chattermate --version

Pointing at your instance

By default the CLI talks to the hosted API at https://api.chattermate.chat — no configuration needed. Only set the API URL when targeting a local or self-hosted backend.

# Local / self-hosted backend, per-command
chattermate --api-url http://localhost:8000 whoami

# Or for the whole session
export CHATTERMATE_API_URL=http://localhost:8000

The URL resolves in this order: the --api-url flag, the CHATTERMATE_API_URL environment variable, your saved config, then the default https://api.chattermate.chat.

Authentication

You can authenticate two ways.

Log in (interactive)
Personal Access Token

Best for day-to-day terminal use. Stores JWT access + refresh tokens in ~/.chattermate/config.json (mode 600) and refreshes them automatically.

chattermate login --email you@acme.com
# password is prompted securely

Best for automation, CI, and AI agents. Long-lived and revocable. Pass it via the CHATTERMATE_TOKEN environment variable.

export CHATTERMATE_TOKEN=cmat_xxxxxxxxxxxxxxxxxxxx
chattermate whoami

Create a new organization and admin user without leaving the terminal. Signup emails a one-time code to --admin-email; supply it with --otp or enter it at the prompt:

chattermate signup \
  --name "Acme Inc" \
  --domain acme.com \
  --admin-email admin@acme.com \
  --admin-name "Ada Admin"
# a one-time code is emailed to admin@acme.com — enter it when prompted
# admin password is prompted securely

You’re logged in automatically after signup.

Running a single-org self-hosted instance (no email delivery)? Add --community to create the org directly without OTP verification.

Personal Access Tokens

Personal Access Tokens (PATs) are long-lived, revocable credentials prefixed with cmat_. They are the recommended way to authenticate the MCP server, CI jobs, and any headless automation.

A token’s secret is shown only once, at creation time. Store it somewhere safe — it cannot be retrieved again.

Create a token

chattermate token create laptop-cli
# optionally set an expiry:
chattermate token create ci --expires-in-days 90

The output includes the cmat_... secret and a ready-to-paste MCP client config snippet.

List your tokens

chattermate token list

Only the non-secret prefix and metadata are shown.

Revoke a token

chattermate token revoke <token-id>

PATs are also managed through the API at /api/v1/enterprise/tokens (POST create, GET list, DELETE /{id} revoke).

Managing resources

Every command supports a --json flag for machine-readable output, making the CLI easy to script.

Agents

# List agents
chattermate agent list

# Inspect one
chattermate agent get <agent-id>

# Create an agent (type: customer_support, sales, tech_support, general, custom)
chattermate agent create \
  --name "Support" \
  --type customer_support \
  -i "Be concise and friendly" \
  -i "Escalate billing questions to a human"

# Update instructions / state
chattermate agent update <agent-id> -i "New instruction" --inactive

Workflows

# Get the workflow attached to an agent
chattermate workflow get <agent-id>

# Create a workflow
chattermate workflow create --agent-id <agent-id> --name "Onboarding"

# Update metadata (status: draft, published, archived)
chattermate workflow update <workflow-id> --status published

# Read or replace nodes & connections
chattermate workflow nodes <workflow-id>
chattermate workflow set-nodes <workflow-id> --file nodes.json

Knowledge

# Upload local PDF file(s) (optionally attach to an agent)
chattermate knowledge add-file ./guide.pdf ./faq.pdf --agent-id <agent-id>

# Add website and/or PDF URLs (optionally attach to an agent)
chattermate knowledge add-url \
  --website https://docs.acme.com \
  --pdf-url https://acme.com/guide.pdf \
  --agent-id <agent-id>

# List sources linked to an agent
chattermate knowledge list <agent-id>

# Link / unlink an existing source
chattermate knowledge link <knowledge-id> <agent-id>
chattermate knowledge unlink <knowledge-id> <agent-id>

# Check ingestion progress
chattermate knowledge status <queue-id>

AI model

# New organizations already use the free ChatterMate model by default.
# Switch to your own provider/key at any time:
chattermate ai setup --model-type openai --model-name gpt-4o --api-key sk-...

# Or (re)apply the free ChatterMate model:
chattermate ai setup

# Show the current AI configuration
chattermate ai show

Providers: chattermate (free managed), openai, anthropic, google, groq, mistral, ollama, and more. Custom models require a Pro plan.

Widgets

# Create an embeddable widget for an agent — prints the widget id + embed snippet
chattermate widget create --agent-id <agent-id> --name "Website widget"

# List an agent's widgets (their ids are what you embed)
chattermate widget list <agent-id>

The widget id is what goes in window.chattermateId — see Widget integration.

Lead capture

# Show an agent's lead-capture configuration
chattermate lead-capture show <agent-id>

# Turn lead capture on and choose which details to collect
chattermate lead-capture set <agent-id> --enable --fields email,name,company

# Mark extra fields required and require GDPR consent
chattermate lead-capture set <agent-id> --required email,company --consent

# Turn it off
chattermate lead-capture set <agent-id> --disable

set fetches the current config, applies your flags, and saves the result (custom fields configured in the dashboard are preserved). Email is always collected and required. Lead capture is a Pro feature — see Lead capture.

Chat customization

# Show an agent's chat widget appearance
chattermate customization show <agent-id>

# Colors + design theme
chattermate customization set <agent-id> --accent "#7c3aed" --style GLASS

# Welcome message, quick actions, and toggles
chattermate customization set <agent-id> \
  --welcome-title "Hi there!" \
  --quick-action "Pricing" --quick-action "Book a demo" \
  --collect-email

Options include colors (--accent, --background, --bubble, --text, --icon-color), design theme --style (CHATBOT, ASK_ANYTHING, GLASS, TERMINAL, PLAYFUL, CALM_MINT, AURORA, SUNRISE), --position (FLOATING/FIXED), --font, --custom-css, welcome title/subtitle/message, --quick-action, --initiation-message, --show-citations and --collect-email. Only the options you pass change — the rest keep their current values. See Chat customization.Text limits: welcome title ≤ 100, subtitle ≤ 250, message ≤ 500, and each initiation nudge ≤ 100 characters (nudges are also clamped to 4 lines in the launcher).

Behaviour: transfer to human & ratings

# Let the agent hand off to a human, and ask visitors to rate the chat
chattermate agent update <agent-id> --transfer-to-human --ask-for-rating

# Turn them off
chattermate agent update <agent-id> --no-transfer-to-human --no-ask-for-rating

Help center & FAQs

Manage the public Help Center — FAQs, imports, branding, and custom domain. (Generating FAQs from the knowledge base stays in the dashboard.)

# Create, list and publish FAQs
chattermate help-center faq create \
  --question "How do I reset my password?" \
  --answer "Open **Settings → Security**." --status published
chattermate help-center faq list --status published
chattermate help-center faq publish <faq-id> [<faq-id> ...]

# Import from a URL (qa = AI extraction, articles = crawl as-is) or a PDF
chattermate help-center import url https://help.acme.com --mode articles
chattermate help-center import pdf ./faqs.pdf

# Brand the site and set a logo
chattermate help-center configure --title "Acme Help" --brand-color "#4338CA" --enable
chattermate help-center logo set ./logo.png

# Connect and verify a custom domain (prints the DNS records to add)
chattermate help-center domain set help.acme.com
chattermate help-center domain status
chattermate help-center domain verify

# Track a background import
chattermate help-center jobs list

The help center is a Pro/Enterprise feature. See Help Center.

Command reference

Command	Description
`chattermate signup`	Create an organization and admin user
`chattermate login`	Log in and store JWT credentials
`chattermate logout`	Remove stored credentials
`chattermate whoami`	Show the authenticated user
`chattermate token create <name>`	Create a Personal Access Token
`chattermate token list`	List your tokens
`chattermate token revoke <id>`	Revoke a token
`chattermate agent list\|get\|create\|update`	Manage AI agents (including `--transfer-to-human` / `--ask-for-rating`)
`chattermate customization show\|set`	Show/configure an agent’s chat widget appearance
`chattermate workflow get\|create\|update\|nodes\|set-nodes`	Manage workflows
`chattermate knowledge add-file\|add-url\|list\|link\|unlink\|status`	Manage knowledge sources (local PDFs or URLs)
`chattermate widget create\|list`	Create/list embeddable widgets and get the widget id to embed
`chattermate lead-capture show\|set`	Show/configure an agent’s lead capture (Pro)
`chattermate ai setup\|show`	Set/show the org’s AI model (defaults to the free ChatterMate model)
`chattermate help-center faq\|import\|configure\|logo\|domain\|jobs`	Manage the public help center — FAQs, imports, branding, custom domain (Pro)

Configuration & environment

Variable	Purpose
`CHATTERMATE_API_URL`	API base URL (default `https://api.chattermate.chat`; set to `http://localhost:8000` for local)
`CHATTERMATE_TOKEN`	A Personal Access Token (`cmat_...`) for non-interactive auth
`CHATTERMATE_CONFIG_DIR`	Override the config directory (default `~/.chattermate`)

Credentials and the saved API URL live in ~/.chattermate/config.json (written with 600 permissions).

Getting Started

Features

Channels

Developer Tools

Deployment

CLI

ChatterMate CLI

Installation

Pointing at your instance

Authentication

Personal Access Tokens

Managing resources

Command reference

Configuration & environment

Next steps

MCP Server

Authentication

​ChatterMate CLI

​Installation

​Pointing at your instance

​Authentication

​Sign up

​Personal Access Tokens

​Managing resources

​Command reference

​Configuration & environment

​Next steps

MCP Server

Authentication

ChatterMate CLI

Installation

Pointing at your instance

Authentication

Sign up

Personal Access Tokens

Managing resources

Command reference

Configuration & environment

Next steps