CLI Commands

OPS Beginner

Command-line reference for the EZ-Console Cobra CLI: code scaffolding, project init, and HTTP server flags.

Overview

There are two common shapes of binary:

1. Framework repository (github.com/sven-victor/ez-console): the root command exposes generate, init, and a nested server command whose name defaults to ez-console (the first argument to server.NewCommandServer in cmd/root.go). You typically run:

   ez-console ez-console --global.encrypt-key=your-16-byte-key

   Help for the server: ez-console ez-console --help. Codegen: ez-console generate --help, ez-console init --help.

2. Your application (see Quick start): you call consoleserver.NewCommandServer("my-app", …) and compile one root command, so flags go directly on your binary:

   ./my-app --global.encrypt-key=your-16-byte-key

In the sections below, replace <server> with ez-console ez-console for the framework binary, or ./your-app for a scaffolded project.

Configuration can also be set with environment variables and config.yaml; precedence is documented under Configuration precedence.

Code generation and init

Shipped with the framework binary (not the minimal single-command apps unless you add them yourself):

Command	Purpose
ez-console generate controller <Name>	REST-style controller + route registration
ez-console generate model <Name>	GORM model (UUID PK)
ez-console generate service <Name>	Service stub using pkg/db
ez-console init <target-dir>	New backend + Vite web + Makefile

init required flags: --name (service name / default SQLite file), --go-module (module path for backend/go.mod).

init optional flags: --app-version (default 0.1.0), --ez-console-version (default pinned module version), --description.

generate shared flags: --dir (default .), -o / --output, --module, --model-import, --service-import. Entity <Name> must be PascalCase (e.g. Product). Default output without -o is <dir>/<kind>/<snake>.go.

ez-console init ./my-product --name my-product --go-module example.com/my-product/backend
ez-console generate controller Product --dir ./backend

Implementation: cmd/generate.go, cmd/init.go, internal/codegen/.

Start the HTTP server

# Framework repo (nested server subcommand)
ez-console ez-console --global.encrypt-key=your-secret-key-16bytes

# With explicit config file
<server> --config=/etc/myapp/config.yml

# Help for server flags only
<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

Related Topics

• Configuration Reference - All configuration options
• Configuration Guide - Configuration guide
• Deployment - Production deployment
• Quick start - Single-command app layout
• API best practices - After generating controllers, wire OpenAPI / clients

---

Need help? Ask in GitHub Discussions.