> ## Documentation Index
> Fetch the complete documentation index at: https://gomodel-docs-benchmark-writeup-and-tooling.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI Operations

> Command-line flags for inspecting the GoModel binary and probing a running gateway's health.

## Overview

The `gomodel` binary exposes a small set of command-line flags for operational
tasks. Flags accept both single-dash (`-flag`) and double-dash (`--flag`) forms;
the examples below use the long form.

| Flag               | Description                                                   | Default |
| ------------------ | ------------------------------------------------------------- | ------- |
| `--version`        | Print version information and exit                            | —       |
| `--health`         | Probe the local `/health` (liveness) endpoint and exit        | —       |
| `--health-timeout` | Maximum time to wait for the `--health` probe                 | `2s`    |
| `--ready`          | Probe the local `/health/ready` (readiness) endpoint and exit | —       |
| `--ready-timeout`  | Maximum time to wait for the `--ready` probe                  | `4s`    |

## Version

Print the build version and exit:

```bash theme={null}
gomodel --version
```

## Health probe

`--health` makes the binary act as a health-check client: it loads the same
configuration as the server, requests the local `/health` endpoint, and exits.

```bash theme={null}
gomodel --health
```

* Exits `0` when the endpoint returns HTTP `200` with `{"status":"ok"}`.
* Exits non-zero otherwise (connection refused, non-`200` status, or any other
  status value).

The probe always targets the loopback interface (`127.0.0.1`) since it runs
inside the same container as the server, but it derives the `PORT` and
`BASE_PATH` from configuration instead of hardcoding `8080` and `/health`. Bound
the request with `--health-timeout`:

```bash theme={null}
gomodel --health --health-timeout 5s
```

### Docker `HEALTHCHECK`

Because the probe is built into the binary, container images can report health
without shipping `curl` or `wget` — useful for minimal/distroless runtimes. The
official image wires it up automatically:

```dockerfile theme={null}
HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
  CMD ["/gomodel", "--health"]
```

Orchestrators (Docker, Compose, Kubernetes) can then detect and restart an
unhealthy gateway.

## Readiness probe

`--ready` probes `/health/ready`, which reports whether the instance should
receive traffic. Unlike liveness, readiness checks the dependencies the gateway
owns:

* **Storage** is required. If the backend (SQLite/PostgreSQL/MongoDB) is
  unreachable, readiness reports `not_ready` (HTTP `503`).
* **Redis exact cache** (when configured) is a performance optimization. If it
  is unreachable, readiness reports `degraded` but stays HTTP `200` — the
  gateway still serves requests.

Upstream **provider** reachability is deliberately excluded: a provider outage
must not pull a healthy gateway out of rotation.

```bash theme={null}
gomodel --ready
```

* Exits `0` when the endpoint returns HTTP `200` (`ready` or `degraded`).
* Exits non-zero on `not_ready` (HTTP `503`), connection refused, or an
  unexpected status value.

```json theme={null}
{ "status": "ready", "components": { "storage": "ok", "cache": "ok" } }
```

Liveness (`--health`) is the right signal for a Docker `HEALTHCHECK` (restart on
crash). Readiness (`/health/ready`) is the right signal for a Kubernetes
`readinessProbe` (gate traffic) — point it at the HTTP endpoint directly or run
`gomodel --ready` as an exec probe. Keep `--ready-timeout` larger than the
server's internal per-dependency probe timeout (`2s`) so a slow backend returns
a clean `not_ready` instead of the client timing out first.