Configuration

All settings live in a single JSON file:

~/.pywacli/config.json

The easiest way to manage it is the wizard — pywacli setup (first run) or pywacli config (edit later). This page documents every section so you know exactly what each option does.

Sections at a glance

Section	Description	Defaults
whatsapp	WebSocket URL, auto-reconnect, local send host/port	ws://localhost:3000, true, 127.0.0.1:8765
media_storage	One or more storage entries (S3 / R2 / B2 / Local) with per-type toggles	Empty
database	SQLite path, or PostgreSQL / MySQL connection	./pywacli.db
dashboard	Refresh interval and theme	1s, default
logging	Log level and output file	INFO, ./pywacli.log
ai_providers	API keys and default provider/model for AI Automate	ollama / llama3

whatsapp

{
  "whatsapp": {
    "websocket_url": "ws://localhost:3000",
    "auto_reconnect": true,
    "send_host": "127.0.0.1",
    "send_port": 8765
  }
}

• websocket_url — where the WhatsApp bridge listens.
• auto_reconnect — reconnect automatically if the socket drops (unless you logged out).
• send_host / send_port — the local command server hosted by a running connect session. The Send flow connects here instead of opening its own WhatsApp socket.

database

PyWacli stores everything through SQLAlchemy, so you can use SQLite (default), an online SQLite file, PostgreSQL, or MySQL.

SQLite (default)PostgreSQLMySQL

{
  "database": {
    "type": "sqlite",
    "path": "./pywacli.db"
  }
}

If you pass a directory, PyWacli places pywacli.db inside it. When no path is set, it falls back to ~/.pywacli/pywacli.db. SQLite runs in WAL mode with foreign keys on.

{
  "database": {
    "type": "postgresql",
    "host": "localhost",
    "port": "5432",
    "name": "pywacli",
    "user": "postgres",
    "password": "secret"
  }
}

{
  "database": {
    "type": "mysql",
    "host": "localhost",
    "port": "3306",
    "name": "pywacli",
    "user": "root",
    "password": "secret"
  }
}

See the Database schema for the table layout.

media_storage

Each entry is a storage target with per-media-type toggles. You can have several at once.

{
  "media_storage": {
    "entries": [
      {
        "id": 1,
        "provider": "s3",
        "store_image": true,
        "store_video": true,
        "store_document": true,
        "endpoint": "http://localhost:4566",
        "access_key_id": "test",
        "secret_access_key": "test",
        "region": "us-east-1",
        "bucket_name": "whatsapp-media",
        "local_path": null
      }
    ]
  }
}

Supported providers: s3 (Amazon S3 / S3-compatible), r2 (Cloudflare R2), b2 (Backblaze B2), and local (filesystem via local_path). See Storage providers.

dashboard

{
  "dashboard": {
    "refresh_interval_sec": 1,
    "theme": "default"
  }
}

Themes: default, dark, light. See the Dashboard guide.

logging

{
  "logging": {
    "level": "INFO",
    "file": "./pywacli.log"
  }
}

Levels follow Python's logging module (DEBUG, INFO, WARNING, ERROR). If a directory is given, PyWacli writes pywacli.log inside it.

ai_providers

{
  "ai_providers": {
    "default_provider": "ollama",
    "default_model": "llama3",
    "openai_api_key": "",
    "google_api_key": "",
    "anthropic_api_key": "",
    "zhipuai_api_key": ""
  }
}

Keys are loaded into the environment when AI Automate starts. You'll be prompted for a missing key the first time you pick a provider that needs one — Ollama runs locally and needs none. See AI skills & providers.

Keep your keys private

config.json holds API keys and database passwords in plain text. Don't commit it to version control, and restrict file permissions on shared machines.