feat: generate docs from cli

apps/engineering/README.md

@@ -13,14 +13,14 @@ pnpm dev
 yarn dev
 ```
 
-Open http://localhost:3000 with your browser to see the result.
+Open <http://localhost:3000> with your browser to see the result.
 
 ## Learn More
 
 To learn more about Next.js and Fumadocs, take a look at the following
 resources:
 
-- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js
+- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js.
   features and API.
 - [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
 - [Fumadocs](https://fumadocs.vercel.app) - learn about Fumadocs

apps/engineering/content/docs/architecture/meta.json

@@ -3,5 +3,5 @@
   "description": "How does Unkey work",
   "icon": "Pencil",
   "root": false,
-  "pages": ["index", "---Services---"]
+  "pages": ["index", "services"]
 }

apps/engineering/content/docs/architecture/services/deploy/index.mdx

@@ -0,0 +1,107 @@
+---
+title: "Deploy Command"
+description: "Deploy a new version or initialize configuration"
+---
+Build and deploy a new version of your application, or initialize configuration.
+
+The deploy command handles the complete deployment lifecycle: from building Docker images to deploying them on Unkey's infrastructure. It automatically detects your Git context, builds containers, and manages the deployment process with real-time status updates.
+
+## Initialization Mode
+
+Use --init to create a configuration template file. This generates an unkey.json file with your project settings, making future deployments simpler and more consistent across environments.
+
+## Deployment Process
+
+1. Load configuration from unkey.json or flags
+2. Build Docker image from your application  
+3. Push image to container registry
+4. Create deployment version on Unkey platform
+5. Monitor deployment status until active
+
+## Command Syntax
+
+```bash
+deploy [flags]
+```
+
+## Examples
+
+### Initialize new project configuration
+
+```bash
+unkey deploy --init
+```
+
+### Initialize with custom location
+
+```bash
+unkey deploy --init --config=./my-project
+```
+
+### Force overwrite existing configuration
+
+```bash
+unkey deploy --init --force
+```
+
+### Standard deployment (uses ./unkey.json)
+
+```bash
+unkey deploy
+```
+
+### Deploy from specific config directory
+
+```bash
+unkey deploy --config=./production
+```
+
+### Override workspace from config file
+
+```bash
+unkey deploy --workspace-id=ws_production_123
+```
+
+### Deploy with custom build context
+
+```bash
+unkey deploy --context=./api
+```
+
+### Local development (build only, no push)
+
+```bash
+unkey deploy --skip-push
+```
+
+### Deploy pre-built image
+
+```bash
+unkey deploy --docker-image=ghcr.io/user/app:v1.0.0
+```
+
+### Verbose output for debugging
+
+```bash
+unkey deploy --verbose
+```
+
+## Flags
+
+| Flag | Description | Type | Default | Environment |
+| --- | --- | --- | --- | --- |
+| `--config` | Directory containing unkey.json config file | string |- |- |
+| `--init` | Initialize configuration file in the specified directory | boolean |`false` |- |
+| `--force` | Force overwrite existing configuration file when using --init | boolean |`false` |- |
+| `--workspace-id` | Workspace ID | string |- |`UNKEY_WORKSPACE_ID` |
+| `--project-id` | Project ID | string |- |`UNKEY_PROJECT_ID` |
+| `--context` | Build context path | string |- |- |
+| `--branch` | Git branch | string |`"main"` |- |
+| `--docker-image` | Pre-built docker image | string |- |- |
+| `--dockerfile` | Path to Dockerfile | string |`"Dockerfile"` |- |
+| `--commit` | Git commit SHA | string |- |- |
+| `--registry` | Container registry | string |`"ghcr.io/unkeyed/deploy"` |`UNKEY_REGISTRY` |
+| `--skip-push` | Skip pushing to registry (for local testing) | boolean |`false` |- |
+| `--verbose` | Show detailed output for build and deployment operations | boolean |`false` |- |
+| `--control-plane-url` | Control plane URL | string |`"http://localhost:7091"` |- |
+| `--auth-token` | Control plane auth token | string |`"ctrl-secret-token"` |- |

apps/engineering/content/docs/architecture/services/healthcheck/index.mdx

@@ -0,0 +1,35 @@
+---
+title: "Healthcheck Command"
+description: "Perform an HTTP healthcheck against a given URL"
+---
+This command sends an HTTP GET request to the specified URL and validates the response. It exits with code 0 if the server returns a 200 status code, otherwise exits with code 1.
+
+## Use Cases
+
+This is useful for health monitoring in CI/CD pipelines, service availability checks, load balancer health probes, and infrastructure monitoring scripts.
+
+## Command Syntax
+
+```bash
+unkey healthcheck [flags]
+```
+
+## Examples
+
+### Check if a service is healthy
+
+```bash
+unkey healthcheck https://api.unkey.dev/health
+```
+
+### Check local service
+
+```bash
+unkey healthcheck http://localhost:8080/health
+```
+
+### Use in monitoring script
+
+```bash
+unkey healthcheck https://example.com/api/status || echo 'Service is down!'
+```

apps/engineering/content/docs/architecture/services/meta.json

@@ -2,5 +2,15 @@
   "title": "Services",
   "icon": "Pencil",
   "root": false,
-  "pages": ["vault", "clickhouse", "clickhouse-proxy"]
+  "pages": [
+    "api",
+    "clickhouse",
+    "clickhouse-proxy",
+    "deploy",
+    "healthcheck",
+    "quotacheck",
+    "run",
+    "vault",
+    "version"
+  ]
 }

apps/engineering/content/docs/architecture/services/quotacheck/index.mdx

@@ -0,0 +1,45 @@
+---
+title: "Quotacheck Command"
+description: "Check for exceeded quotas"
+---
+Check for exceeded quotas and optionally send Slack notifications.
+
+This command monitors quota usage by querying ClickHouse for current usage metrics and comparing them against configured limits in the primary database. When quotas are exceeded, it can automatically send notifications via Slack webhook.
+
+## Configuration
+
+The command requires ClickHouse and database connections to function. Slack notifications are optional but recommended for production monitoring.
+
+## Command Syntax
+
+```bash
+quotacheck [flags]
+```
+
+## Examples
+
+### Check quotas without notifications
+
+```bash
+unkey quotacheck --clickhouse-url clickhouse://localhost:9000 --database-dsn postgres://user:pass@localhost/db
+```
+
+### Check quotas with Slack notifications
+
+```bash
+unkey quotacheck --clickhouse-url clickhouse://localhost:9000 --database-dsn postgres://user:pass@localhost/db --slack-webhook-url https://hooks.slack.com/services/...
+```
+
+### Using environment variables
+
+```bash
+CLICKHOUSE_URL=... DATABASE_DSN=... SLACK_WEBHOOK_URL=... unkey quotacheck
+```
+
+## Flags
+
+| Flag | Description | Type | Default | Environment |
+| --- | --- | --- | --- | --- |
+| `--clickhouse-url` **(required)** | URL for the ClickHouse database | string |- |`CLICKHOUSE_URL` |
+| `--database-dsn` **(required)** | DSN for the primary database | string |- |`DATABASE_DSN` |
+| `--slack-webhook-url` | Slack webhook URL to send notifications | string |- |`SLACK_WEBHOOK_URL` |

apps/engineering/content/docs/architecture/services/run/api/index.mdx

@@ -0,0 +1,39 @@
+---
+title: "Run Api Command"
+description: "Run the Unkey API server for validating and managing API keys"
+---
+Run the Unkey API server for validating and managing API keys
+
+## Command Syntax
+
+```bash
+api [flags]
+```
+
+## Flags
+
+| Flag | Description | Type | Default | Environment |
+| --- | --- | --- | --- | --- |
+| `--http-port` | HTTP port for the API server to listen on. Default: 7070 | integer |`7070` |`UNKEY_HTTP_PORT` |
+| `--color` | Enable colored log output. Default: true | boolean |`true` |`UNKEY_LOGS_COLOR` |
+| `--test-mode` | Enable test mode. WARNING: Potentially unsafe, may trust client inputs blindly. Default: false | boolean |`false` |`UNKEY_TEST_MODE` |
+| `--platform` | Cloud platform identifier for this node. Used for logging and metrics. | string |- |`UNKEY_PLATFORM` |
+| `--image` | Container image identifier. Used for logging and metrics. | string |- |`UNKEY_IMAGE` |
+| `--region` | Geographic region identifier. Used for logging and routing. Default: unknown | string |`"unknown"` |`AWS_REGION` |
+| `--instance-id` | Unique identifier for this instance. Auto-generated if not provided. | string |`"ins_6gi44j"` |`UNKEY_INSTANCE_ID` |
+| `--database-primary` **(required)** | MySQL connection string for primary database. Required for all deployments. Example: user:pass@host:3306/unkey?parseTime=true | string |- |`UNKEY_DATABASE_PRIMARY` |
+| `--database-replica` | MySQL connection string for read-replica. Reduces load on primary database. Format same as database-primary. | string |- |`UNKEY_DATABASE_REPLICA` |
+| `--redis-url` | Redis connection string for rate-limiting and distributed counters. Example: redis://localhost:6379 | string |- |`UNKEY_REDIS_URL` |
+| `--clickhouse-url` | ClickHouse connection string for analytics. Recommended for production. Example: clickhouse://user:pass@host:9000/unkey | string |- |`UNKEY_CLICKHOUSE_URL` |
+| `--otel` | Enable OpenTelemetry tracing and metrics | boolean |`false` |`UNKEY_OTEL` |
+| `--otel-trace-sampling-rate` | Sampling rate for OpenTelemetry traces (0.0-1.0). Only used when --otel is provided. Default: 0.25 | float |`0.25` |`UNKEY_OTEL_TRACE_SAMPLING_RATE` |
+| `--prometheus-port` | Enable Prometheus /metrics endpoint on specified port. Set to 0 to disable. | integer |- |`UNKEY_PROMETHEUS_PORT` |
+| `--tls-cert-file` | Path to TLS certificate file for HTTPS. Both cert and key must be provided to enable HTTPS. | string |- |`UNKEY_TLS_CERT_FILE` |
+| `--tls-key-file` | Path to TLS key file for HTTPS. Both cert and key must be provided to enable HTTPS. | string |- |`UNKEY_TLS_KEY_FILE` |
+| `--vault-master-keys` | Vault master keys for encryption | string[] |- |`UNKEY_VAULT_MASTER_KEYS` |
+| `--vault-s3-url` | S3 Compatible Endpoint URL | string |- |`UNKEY_VAULT_S3_URL` |
+| `--vault-s3-bucket` | S3 bucket name | string |- |`UNKEY_VAULT_S3_BUCKET` |
+| `--vault-s3-access-key-id` | S3 access key ID | string |- |`UNKEY_VAULT_S3_ACCESS_KEY_ID` |
+| `--vault-s3-secret-access-key` | S3 secret access key | string |- |`UNKEY_VAULT_S3_SECRET_ACCESS_KEY` |
+| `--chproxy-enabled` | Enable ClickHouse proxy endpoints for high-throughput event collection | boolean |`false` |`UNKEY_CHPROXY_ENABLED` |
+| `--chproxy-auth-token` | Authentication token for ClickHouse proxy endpoints. Required when proxy is enabled. | string |- |`UNKEY_CHPROXY_AUTH_TOKEN` |

apps/engineering/content/docs/architecture/services/run/ctrl/index.mdx

@@ -0,0 +1,31 @@
+---
+title: "Run Ctrl Command"
+description: "Run the Unkey control plane service for managing infrastructure and services"
+---
+Run the Unkey control plane service for managing infrastructure and services
+
+## Command Syntax
+
+```bash
+ctrl [flags]
+```
+
+## Flags
+
+| Flag | Description | Type | Default | Environment |
+| --- | --- | --- | --- | --- |
+| `--http-port` | HTTP port for the control plane server to listen on. Default: 8080 | integer |`8080` |`UNKEY_HTTP_PORT` |
+| `--color` | Enable colored log output. Default: true | boolean |`true` |`UNKEY_LOGS_COLOR` |
+| `--platform` | Cloud platform identifier for this node. Used for logging and metrics. | string |- |`UNKEY_PLATFORM` |
+| `--image` | Container image identifier. Used for logging and metrics. | string |- |`UNKEY_IMAGE` |
+| `--region` | Geographic region identifier. Used for logging and routing. Default: unknown | string |`"unknown"` |`AWS_REGION` |
+| `--instance-id` | Unique identifier for this instance. Auto-generated if not provided. | string |`"ins_WZy92"` |`UNKEY_INSTANCE_ID` |
+| `--database-primary` **(required)** | MySQL connection string for primary database. Required for all deployments. Example: user:pass@host:3306/unkey?parseTime=true | string |- |`UNKEY_DATABASE_PRIMARY` |
+| `--database-hydra` **(required)** | MySQL connection string for hydra database. Required for all deployments. Example: user:pass@host:3306/hydra?parseTime=true | string |- |`UNKEY_DATABASE_HYDRA` |
+| `--otel` | Enable OpenTelemetry tracing and metrics | boolean |`false` |`UNKEY_OTEL` |
+| `--otel-trace-sampling-rate` | Sampling rate for OpenTelemetry traces (0.0-1.0). Only used when --otel is provided. Default: 0.25 | float |`0.25` |`UNKEY_OTEL_TRACE_SAMPLING_RATE` |
+| `--tls-cert-file` | Path to TLS certificate file for HTTPS. Both cert and key must be provided to enable HTTPS. | string |- |`UNKEY_TLS_CERT_FILE` |
+| `--tls-key-file` | Path to TLS key file for HTTPS. Both cert and key must be provided to enable HTTPS. | string |- |`UNKEY_TLS_KEY_FILE` |
+| `--auth-token` | Authentication token for control plane API access. Required for secure deployments. | string |- |`UNKEY_AUTH_TOKEN` |
+| `--metald-address` **(required)** | Full URL of the metald service for VM operations. Required for deployments. Example: https://metald.example.com:8080 | string |- |`UNKEY_METALD_ADDRESS` |
+| `--spiffe-socket-path` | Path to SPIFFE agent socket for mTLS authentication. Default: /var/lib/spire/agent/agent.sock | string |`"/var/lib/spire/agent/agent.sock"` |`UNKEY_SPIFFE_SOCKET_PATH` |

apps/engineering/content/docs/architecture/services/run/index.mdx

@@ -0,0 +1,16 @@
+---
+title: "Run Command"
+description: "Run Unkey services"
+---
+Run various Unkey services in development or production environments.
+
+This command starts different Unkey microservices. Each service can be configured independently and runs as a standalone process.
+
+## Available Services
+
+- api: The main API server for validating and managing API keys
+- ctrl: The control plane service for managing infrastructure and deployments
+
+## Quick Reference
+- `run api` - Run the Unkey API server for validating and managing API keys
+- `run ctrl` - Run the Unkey control plane service for managing infrastructure and services

apps/engineering/content/docs/architecture/services/version/get/index.mdx

@@ -0,0 +1,25 @@
+---
+title: "Version Get Command"
+description: "Get details about a version"
+---
+Get comprehensive details about a specific version including status, branch, creation time, and associated hostnames.
+
+## Command Syntax
+
+```bash
+get [flags]
+```
+
+## Examples
+
+### Get details for a specific version
+
+```bash
+unkey version get v_abc123def456
+```
+
+### Get details for another version
+
+```bash
+unkey version get v_def456ghi789
+```

apps/engineering/content/docs/architecture/services/version/index.mdx

@@ -0,0 +1,18 @@
+---
+title: "Version Command"
+description: "Manage API versions"
+---
+Create, list, and manage versions of your API.
+
+Versions are immutable snapshots of your code, configuration, and infrastructure settings. Each version represents a specific deployment state that can be rolled back to at any time.
+
+## Available Commands
+
+- get: Get details about a specific version
+- list: List all versions with optional filtering
+- rollback: Rollback to a previous version
+
+## Quick Reference
+- `version get` - Get details about a version
+- `version list` - List versions with optional filtering
+- `version rollback` - Rollback to a previous version