Skip to main content

CLI Commands

OPS Beginner

Command-line interface reference for EZ-Console server.

Overview​

EZ-Console provides a command-line interface built with Cobra. All configuration options can be set via command-line flags, environment variables, or configuration files.

Basic Usage​

Start Server​

# Basic start
./server --global.encrypt-key=your-secret-key-16bytes

# With config file
./server --global.encrypt-key=your-secret-key-16bytes --config=config.yml

# Show help
./server --help

Global Flags​

Encryption Key​

Required: Encryption key for sensitive data encryption.

--global.encrypt-key=string
  • Length: Must be 0, 8, 16, 24, or 32 bytes
  • Example: --global.encrypt-key=1234567890123456 (16 bytes)
  • Warning: Never change this key after initial setup or encrypted data will be unrecoverable

Config File​

--config=string
  • Default: ./config.yaml
  • Example: --config=/etc/myapp/config.yml

Server Flags​

Port​

--server.port=string
  • Default: 8080
  • Example: --server.port=9090

Host​

--server.host=string
  • Default: 0.0.0.0
  • Example: --server.host=127.0.0.1

Mode​

--server.mode=string
  • Options: debug, release
  • Default: release
  • Example: --server.mode=debug

Root URL​

--server.root_url=string
  • Default: "" (empty)
  • Example: --server.root_url=https://example.com

Timeouts​

--server.read_timeout=string      # Default: 10s
--server.write_timeout=string     # Default: 10s
--server.shutdown_timeout=string  # Default: 10s

Examples:

--server.read_timeout=30s
--server.write_timeout=30s
--server.shutdown_timeout=15s

File Upload Path​

--server.file_upload_path=string
  • Default: ./uploads
  • Example: --server.file_upload_path=/var/www/uploads

GeoIP Database Path​

--server.geoip_db_path=string
  • Default: "" (empty, optional)
  • Example: --server.geoip_db_path=./GeoLite2-City.mmdb

Database Flags​

Driver​

--database.driver=string
  • Options: sqlite, mysql, postgres, clickhouse
  • Default: sqlite
  • Example: --database.driver=mysql

SQLite Options​

--database.path=string
  • Default: {app-name}.db
  • Example: --database.path=./data/myapp.db

MySQL/PostgreSQL/ClickHouse Options​

--database.host=string              # Default: localhost
--database.username=string          # Default: root
--database.password=string          # Default: "" (empty)
--database.schema=string            # Default: {app-name} (snake_case)
--database.max_open_connections=int # Default: 100
--database.max_idle_connections=int # Default: 2 (MySQL/ClickHouse), 10 (PostgreSQL)
--database.max_connection_life_time=string # Default: 30s

MySQL Specific:

--database.charset=string      # Default: utf8mb4
--database.collation=string    # Default: utf8mb4_unicode_ci

ClickHouse Specific:

--database.read_timeout=string        # Default: 10s
--database.dial_timeout=string        # Default: 10s
--database.max_execution_time=string  # Default: 60s
--database.enable_compression=string  # Default: true

Common Database Options​

--database.slow_threshold=string  # Default: 3s
--database.table_prefix=string   # Default: t_

Environment Variables​

All flags can also be set via environment variables:

# Global
export GLOBAL_ENCRYPT_KEY=your-secret-key-16bytes

# Server
export SERVER_PORT=8080
export SERVER_HOST=0.0.0.0
export SERVER_MODE=release

# Database
export DATABASE_DRIVER=mysql
export DATABASE_HOST=localhost
export DATABASE_USERNAME=root
export DATABASE_PASSWORD=secure-password
export DATABASE_SCHEMA=myapp

Naming Convention:

  • Convert dots to underscores
  • Use uppercase
  • Example: --server.port → SERVER_PORT

Configuration Precedence​

Configuration is loaded in this order (highest to lowest priority):

  1. Command-line flags (highest priority)
  2. Environment variables
  3. Configuration file (lowest priority)

Examples​

Development Mode​

./server \
  --global.encrypt-key=dev-key-16bytes \
  --server.mode=debug \
  --server.port=8080 \
  --log.level=debug

Production with MySQL​

./server \
  --global.encrypt-key=production-key-32bytes \
  --config=/etc/myapp/config.yml \
  --server.mode=release \
  --server.port=8080 \
  --database.driver=mysql \
  --database.host=db.example.com \
  --database.username=myapp \
  --database.password=${DB_PASSWORD} \
  --database.schema=myapp

Docker Container​

docker run -d \
  -p 8080:8080 \
  -e GLOBAL_ENCRYPT_KEY=your-key-16bytes \
  -e DATABASE_DRIVER=mysql \
  -e DATABASE_HOST=db \
  -e DATABASE_USERNAME=root \
  -e DATABASE_PASSWORD=secure-password \
  myapp:latest

Systemd Service​

[Service]
Environment="GLOBAL_ENCRYPT_KEY=your-key-16bytes"
Environment="SERVER_PORT=8080"
Environment="DATABASE_DRIVER=mysql"
ExecStart=/opt/myapp/server --config=/etc/myapp/config.yml

Help Commands​

Show Help​

./server --help

Show Version​

./server --version

Troubleshooting​

Invalid Encryption Key​

Error: encryption key must be 8, 16, 24, or 32 bytes

Solution: Use correct key length:

# 8 bytes
--global.encrypt-key=12345678

# 16 bytes
--global.encrypt-key=1234567890123456

# 24 bytes
--global.encrypt-key=123456789012345678901234

# 32 bytes
--global.encrypt-key=12345678901234567890123456789012

Port Already in Use​

Error: bind: address already in use

Solution: Use different port:

--server.port=9090

Config File Not Found​

Error: config file not found

Solution: Specify full path or create config file:

--config=/path/to/config.yml

Need help? Ask in GitHub Discussions.