CLI and Server Options

MikroChat CLI

The mikrochat CLI is installed via the curl oneliner and provides commands for managing your MikroChat installation.

curl -sSL https://releases.mikrochat.com/install.sh | bash

Commands

Command	Description
mikrochat install	Download and install MikroChat to ~/.mikrochat/
mikrochat init	Create config and copy web app to current directory
mikrochat start	Start the MikroChat API server
mikrochat upgrade	Check for updates and upgrade to the latest version
mikrochat version	Show the installed version
mikrochat uninstall	Remove MikroChat from your system
mikrochat docs	Open the documentation in your browser

How It Works

• ~/.mikrochat/ stores the installed API and web app files
• ~/.local/bin/mikrochat is the CLI wrapper script
• mikrochat start runs the API from your current working directory, so mikrochat.config.json and mikrochat_db/ live in your project folder
• mikrochat init copies the web app files to ./app/ in your current directory for easy web server setup

Passing Flags

Any flags after mikrochat start are forwarded to the Node.js server:

mikrochat start --port 4000 --debug

Server Options

MikroChat can also be started directly with Node.js. All configuration can be provided via CLI flags, environment variables, or a configuration file.

# Using the CLI
mikrochat start

# Using Node.js directly
node mikrochat.mjs

# With options
node mikrochat.mjs --port 3001 --debug

Server Flags

Flag	Description	Default
--port	Port to listen on	3000
--host	Host/bind address	localhost
--https	Enable HTTPS	false
--http2	Enable HTTP/2	false
--cert	SSL certificate path	-
--key	SSL private key path	-
--ca	SSL CA certificate path	-
--ratelimit	Enable rate limiting	true
--rps	Requests per minute limit	100
--allowed	Comma-separated allowed domains	-
--debug	Enable debug mode	false

Authentication Flags

Flag	Description	Default
--jwtSecret	JWT signing key	-
--appUrl	Base URL for magic links	-
--magicLinkExpirySeconds	Magic link expiry time	900
--jwtExpirySeconds	JWT expiry time	900
--refreshTokenExpirySeconds	Refresh token expiry	604800
--maxActiveSessions	Max sessions per user	3
--authMode	Auth mode	magic-link
--isInviteRequired	Require admin invite	true

Chat Flags

Flag	Description	Default
--initialUserId	Initial admin user ID	-
--initialUserName	Initial admin username	-
--initialUserEmail	Initial admin email	-
--initialUserPassword	Initial admin password	-
--messageRetentionDays	Days to keep messages	30
--maxMessagesPerChannel	Max messages per channel	100

Email Flags

Flag	Description	Default
--emailSubject	Magic link email subject	Your Secure Login Link
--emailHost	SMTP host	-
--emailUser	SMTP username	-
--emailPassword	SMTP password	-
--emailPort	SMTP port	465
--emailSecure	Use secure connection	true
--emailMaxRetries	Max delivery attempts	2

Storage Flags

Flag	Description	Default
--db	Database directory path	mikrochat_db
--encryptionKey	Encryption key for data at rest	-

Environment Variables

Variable	Description
PORT	Server port
HOST	Server host
DEBUG	Enable debug mode
AUTH_JWT_SECRET	JWT signing key
APP_URL	Base URL for magic links
INITIAL_USER_ID	Initial admin user ID
INITIAL_USER_NAME	Initial admin username
INITIAL_USER_EMAIL	Initial admin email
INITIAL_USER_PASSWORD	Initial admin password
EMAIL_USER	SMTP username
EMAIL_HOST	SMTP host
EMAIL_PASSWORD	SMTP password
STORAGE_KEY	Encryption key

Configuration File

Create mikrochat.config.json in the working directory:

{
  "auth": {
    "jwtSecret": "your-secret-key",
    "authMode": "magic-link",
    "appUrl": "https://chat.example.com",
    "isInviteRequired": true
  },
  "chat": {
    "initialUser": {
      "userName": "admin",
      "email": "admin@example.com",
      "password": ""
    }
  },
  "server": {
    "port": 3000
  }
}

See Configuration for the complete reference.

Configuration Priority

Settings are applied in this order (highest priority first):

1. CLI flags
2. Configuration file (mikrochat.config.json)
3. Default values (which include environment variables)

Examples

Development

# Start with dev mode (from source)
npm start

# Custom port
mikrochat start --port 3001 --debug

Production

# With environment variables
PORT=3000 \
AUTH_JWT_SECRET=your-secret \
EMAIL_HOST=smtp.example.com \
EMAIL_USER=noreply@example.com \
EMAIL_PASSWORD=password \
mikrochat start

# With HTTPS
mikrochat start \
  --https \
  --cert /path/to/cert.pem \
  --key /path/to/key.pem

# With rate limiting
mikrochat start --ratelimit --rps 60

Docker

docker run -d \
  -e PORT=3000 \
  -e AUTH_JWT_SECRET=your-secret \
  -v mikrochat-data:/app/mikrochat_db \
  -p 3000:3000 \
  mikrochat

Development Scripts

When working with the source code:

Script	Description
npm run dev	Start frontend file server (port 8000)
npm run dev:reload	Build frontend + start backend (port 3000)
npm start	Start the backend server
npm run build	Build everything for production
npm run build:web	Build frontend only
npm run build:api	Build backend only
npm test	Run tests
npm run lint	Run linter

Debugging

Enable debug mode to see verbose logs:

# Via CLI flag
mikrochat start --debug

# Via environment variable
DEBUG=true mikrochat start

Debug mode logs:

• Incoming HTTP requests
• Authentication events
• Database operations
• SSE connection lifecycle
• Email delivery attempts

Health Check

The server exposes a health endpoint:

curl http://localhost:3000/health
# Returns: OK

Use this for container health checks and load balancer probes.