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:

```bash
# 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:

```bash
# 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`](version-management-guide.md).

## Server Control Script

A shell script manages the server lifecycle:

```bash
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:

```bash
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:**

```bash
# 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:

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

Example `config.yaml`:

```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:**

```bash
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

```bash
# 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:

```bash
# 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):

```bash
kill -9 $(lsof -ti :8080)
```

**Verification:**

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