dance-lessons-coach/documentation/CLI.md

CLI Management Guide

Complete reference for the dance-lessons-coach CLI, server lifecycle, and configuration. Extracted from the original AGENTS.md (Tâche 6 restructure) for lazy-loading compatibility with Mistral Vibe.

Cobra CLI (Recommended)

dance-lessons-coach includes a modern CLI built with Cobra:

# Show help and available commands
./bin/dance-lessons-coach --help

# Show version information
./bin/dance-lessons-coach version

# Greet someone by name
./bin/dance-lessons-coach greet John

# Start the server
./bin/dance-lessons-coach server

Available Commands:

• version — Print version information
• server — Start the dance-lessons-coach server
• greet [name] — Greet someone by name
• help — Built-in help system
• completion — Generate shell completion scripts

Server Command Flags:

• --config — Config file path
• --env — Environment (dev, staging, prod)
• --debug — Enable debug logging

Version Information

The server provides runtime version information:

# Check version using new CLI
./bin/dance-lessons-coach version

# Check version using server binary
./bin/server --version

# Output:
dance-lessons-coach Version Information:
  Version:   1.0.0
  Commit:    abc1234
  Built:     2026-04-05T10:00:00+0000
  Go:        go1.26.1

For full version management workflow (bump, release, build with version), see version-management-guide.md.

Server Control Script

A shell script manages the server lifecycle:

cd /Users/gabrielradureau/Work/Vibe/DanceLessonsCoach

./scripts/start-server.sh start     # Start the server
./scripts/start-server.sh status    # Check server status
./scripts/start-server.sh test      # Test API endpoints
./scripts/start-server.sh logs      # View server logs
./scripts/start-server.sh stop      # Stop the server
./scripts/start-server.sh restart   # Restart

Available subcommands:

• start — Start the server in background with proper logging
• stop — Stop the server gracefully
• restart — Restart the server
• status — Check if server is running
• logs — Show recent server logs
• test — Test all API endpoints

Manual Server Management

For direct control:

cd /Users/gabrielradureau/Work/Vibe/DanceLessonsCoach
./scripts/start-server.sh start

Expected output:

Server running on :8080
[INF] Starting HTTP server on :8080
[TRC] Registering greet routes
[TRC] Greet routes registered

Features:

• Context-aware server initialization
• Graceful shutdown handling
• Signal-based termination (SIGINT, SIGTERM)
• 30-second shutdown timeout
• Proper resource cleanup

Configuration

Configuration via environment variables with DLC_ prefix:

Option	Environment Variable	Default	Description
Host	DLC_SERVER_HOST	0.0.0.0	Server bind address
Port	DLC_SERVER_PORT	8080	Server listening port
Shutdown Timeout	DLC_SHUTDOWN_TIMEOUT	30s	Graceful shutdown timeout
JSON Logging	DLC_LOGGING_JSON	false	Enable JSON format logging
Log Output	DLC_LOGGING_OUTPUT	""	Log output file path (empty for stderr)

Examples:

# Custom port
export DLC_SERVER_PORT=9090
./scripts/start-server.sh start

# Custom host and port
export DLC_SERVER_HOST="127.0.0.1"
export DLC_SERVER_PORT=8081
./scripts/start-server.sh start

# Custom shutdown timeout
export DLC_SHUTDOWN_TIMEOUT=45s

# Enable JSON logging
export DLC_LOGGING_JSON=true

# Log to file
export DLC_LOGGING_OUTPUT="server.log"

# Combined: JSON logging to file
export DLC_LOGGING_JSON=true
export DLC_LOGGING_OUTPUT="server.json.log"

Configuration File Support:

A config.example.yaml file is provided as a template. By default, the application looks for config.yaml in the current working directory.

To specify a custom config file path, set the DLC_CONFIG_FILE environment variable:

DLC_CONFIG_FILE="/path/to/config.yaml" go run ./cmd/server

Example config.yaml:

server:
  host: "0.0.0.0"
  port: 8080

shutdown:
  timeout: 30s

logging:
  json: false

Configuration Loading Precedence:

1. File-based configuration (highest precedence)
2. Environment variables (override defaults, overridden by config file)
3. Default values (fallback)

All configuration is validated on startup. Invalid configurations cause server startup failure. Configuration values and source are logged at startup.

Verification:

DLC_SERVER_PORT=9090 DLC_SERVER_HOST="127.0.0.1" ./scripts/start-server.sh start

curl http://127.0.0.1:9090/api/health
# Expected: {"status":"healthy"}

Server Status

# Check health endpoint
curl -s http://localhost:8080/api/health

# Check readiness endpoint
curl -s http://localhost:8080/api/ready

Expected responses:

• Health: {"status":"healthy"}
• Readiness (normal): {"ready":true}
• Readiness (during shutdown): {"ready":false} (HTTP 503)

Endpoint Differences:

• Health endpoint (/api/health): Indicates if the application is running and functional
• Readiness endpoint (/api/ready): Indicates if the application is ready to accept traffic

Use Cases:

• Health: Used by load balancers to check if the app is alive
• Readiness: Used by Kubernetes / service meshes to determine if the app can accept new requests

During Graceful Shutdown:

• Health endpoint continues to return {"status":"healthy"}
• Readiness endpoint returns {"ready":false} with HTTP 503 Service Unavailable
• This allows existing requests to complete while preventing new requests

Stopping the Server

To stop the server gracefully:

# Send SIGTERM for graceful shutdown
kill -TERM $(lsof -ti :8080)

# Or send SIGINT (Ctrl+C equivalent)
pkill -INT -f "go run"

Graceful shutdown process:

1. Server receives termination signal
2. Logs shutdown message
3. Stops accepting new connections
4. Waits up to 30 seconds for active requests to complete
5. Closes all connections cleanly
6. Exits with proper cleanup

For force stop (if graceful shutdown hangs):

kill -9 $(lsof -ti :8080)

Verification:

curl -s http://localhost:8080/api/health
# Should return connection refused