Skip to main content

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

​
Sign up

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.
1

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.
2

List your tokens

chattermate token list
Only the non-secret prefix and metadata are shown.
3

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

# 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

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

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

​
Command reference

CommandDescription
chattermate signupCreate an organization and admin user
chattermate loginLog in and store JWT credentials
chattermate logoutRemove stored credentials
chattermate whoamiShow the authenticated user
chattermate token create <name>Create a Personal Access Token
chattermate token listList your tokens
chattermate token revoke <id>Revoke a token
chattermate agent list|get|create|updateManage AI agents (including --transfer-to-human / --ask-for-rating)
chattermate customization show|setShow/configure an agent’s chat widget appearance
chattermate workflow get|create|update|nodes|set-nodesManage workflows
chattermate knowledge add-file|add-url|list|link|unlink|statusManage knowledge sources (local PDFs or URLs)
chattermate widget create|listCreate/list embeddable widgets and get the widget id to embed
chattermate lead-capture show|setShow/configure an agent’s lead capture (Pro)
chattermate ai setup|showSet/show the org’s AI model (defaults to the free ChatterMate model)

​
Configuration & environment

VariablePurpose
CHATTERMATE_API_URLAPI base URL (default https://api.chattermate.chat; set to http://localhost:8000 for local)
CHATTERMATE_TOKENA Personal Access Token (cmat_...) for non-interactive auth
CHATTERMATE_CONFIG_DIROverride the config directory (default ~/.chattermate)
Credentials and the saved API URL live in ~/.chattermate/config.json (written with 600 permissions).

​
Next steps

MCP Server

Let AI agents configure ChatterMate through the Model Context Protocol.

Authentication

Learn how ChatterMate handles users, sessions, and tokens.