---
title: "CLI Reference"
description: "All vibecarbon commands, options, and flags."
order: 2
---

## Install

```bash
npm install -g vibecarbon
```

Installing globally puts the `vibecarbon` command on your PATH. All commands below assume a global install.

## Usage

```bash
vibecarbon                    # show top-level help
vibecarbon <command>          # bare command, opens guided prompts
vibecarbon <command> [seeds]  # positional/flag seeds skip matching prompts
```

**Vibecarbon is interactive-by-default.** Running a bare command always opens a
guided prompt flow, so you never have to memorise flags. Positionals and flags are
*optional prompt seeds*: when present they pre-fill the corresponding prompt and
skip it. When absent, the prompt asks you. CI and piped-stdin contexts that
can't prompt fail with a canonical error that names exactly which flags would
unblock the invocation.

**Flag form:** vibecarbon uses **single-dash flags only** (`-h`, not `--help`).
Multi-letter flags are spelled out (`-env`, `-mode`, `-source`). Only `-h`,
`-v`, `-y`, and `-l` are single-letter.

{/* BEGIN GENERATED: global-flags */}
| Flag | Description |
|------|-------------|
| `-h` | Show help |
| `-v` | Show version number |
{/* END GENERATED: global-flags */}

---

## Deploy modes

The mode sets how many servers an environment runs and where they live. You
choose it per environment at first deploy, and the same app deploys in any of
them.

| Goal | Mode |
|------|------|
| Launch | Single-server Docker Compose |
| Supercharge | Kubernetes |
| Fortify | Kubernetes HA (Compose HA is the same idea for providers without Kubernetes) |

You pay your cloud provider directly for the servers in each mode.

---

# Dev

Local-development primitives. All interactive-by-default.

## next

Show what to do next, and offer to run it.

```bash
vibecarbon ?
vibecarbon next
```

Looks at the current directory, works out where you are on the create, up,
configure, deploy ladder, prints the exact command for the next step, and offers
to run it for you. Once an environment is deployed the ladder is finished, and
the same command turns into a menu of everyday operations: status, scale,
backup, restore, configure, add a feature, deploy another environment, tear one
down.

`?` is the short form. zsh treats a bare `?` as a glob, so quote it there:
`vibecarbon '?'`. bash does the same when a one-character file name exists in
the directory you are standing in. `next` is the same command spelled out, and
it is safe in every shell and in scripts.

Without a terminal, in CI, behind a pipe, or under an agent, it prints the next
command, never asks anything, and exits 0.

{/* BEGIN GENERATED: flags next */}
_No flags beyond -h and -v._
{/* END GENERATED: flags next */}

---

## create

Scaffold a new Vibecarbon project.

```bash
# Interactive (recommended)
vibecarbon create

# Power-user / CI
vibecarbon create my-saas -y -admin-email admin@example.com -admin-password secret123
vibecarbon create my-saas -install
```

Generates secure secrets (auth secret, database and replication passwords), copies the
template, initializes a git repository (with pre-commit + pre-push hooks),
and optionally runs `npm install`. The app creates the admin user the first time it starts.

{/* BEGIN GENERATED: flags create */}
| Flag | Description |
|------|-------------|
| `-y` | Skip prompts (requires -admin-email and -admin-password) |
| `-install` | Run the package manager's install during create (default: deferred to first vibecarbon up) |
| `-skip-lockfile` | Skip lockfile generation (faster; deploy will need `vibecarbon up` first to install) |
| `-pm <name>` | Package manager: npm (default), pnpm, or bun |
| `-admin-email <email>` | Admin email for dashboard access (required with -y) |
| `-admin-password <pw>` | Admin password for dashboard access (required with -y) |
| `-display-name <name>` | Human-facing product name shown in browser titles, the PWA manifest, and emails (default: derived from project name) |
{/* END GENERATED: flags create */}

A git repository is initialized automatically (with pre-commit + pre-push hooks). If `git` isn't on PATH, this step is skipped silently with a hint to run `git init` manually afterwards.

---

## up

Start the local development environment.

{/* BEGIN GENERATED: flags up */}
_No flags beyond -h and -v._
{/* END GENERATED: flags up */}

```bash
vibecarbon up
```

Auto-detects the project's package manager and runs the `dev:start` script,
which boots Docker services (PostgreSQL, Traefik, local S3), runs database
migrations, and starts the Hono API and Vite dev servers. If ports are already
in use, a port offset is applied automatically.

On first run, `up` pins the stack name in your project's `.env` as
`COMPOSE_PROJECT_NAME`. That name ties your containers and database volumes to
the project, so you can rename or move the folder and keep your local database.
`up` notices the old stack, removes its containers (never its volumes), and
recreates them from the new folder. It tells you when it does this, so you know
your data came along.

If you copy a project folder while the original's stack still exists, `up`
refuses to start the copy so the two can't fight over one database. The message
says what to change: give the copy its own `PROJECT_NAME`, or run
`vibecarbon down` in the other folder first.

---

## down

Stop the local development environment.

{/* BEGIN GENERATED: flags down */}
| Flag | Description |
|------|-------------|
| `-orphans` | Remove local stacks whose project folder is gone or moved |
| `-y` | Skip the confirmation |
{/* END GENERATED: flags down */}

```bash
vibecarbon down
```

Stops all Docker Compose services for this project. Volumes (database data) are
preserved.

`-orphans` cleans up after projects you deleted or moved. It lists local stacks
whose project folder is gone, or that were started from files that are no longer
there (and have no running containers). You're asked before the containers and
network are removed, and asked again, separately, before any data volumes are
deleted. That second question defaults to No. `-y` and non-interactive runs
never delete volumes.

To reuse a moved project's data, set `COMPOSE_PROJECT_NAME=<old name>` in the
new folder's `.env` before you run `vibecarbon up`.

---

## reset

Reset the local development environment.

```bash
# Interactive (prompts for confirmation)
vibecarbon reset

# Skip the confirmation prompt
vibecarbon reset -y
```

Removes containers, Docker volumes, and locally-built images. **All local
database data will be lost.** Run `vibecarbon up` afterward to restart.

{/* BEGIN GENERATED: flags reset */}
| Flag | Description |
|------|-------------|
| `-y` | Skip confirmation prompt |
{/* END GENERATED: flags reset */}

---

## status

Show project and deployment status (read-only).

```bash
# Full status
vibecarbon status

# Specific environment
vibecarbon status -env prod

# Machine-readable JSON for CI/scripting
vibecarbon status -json
```

When run outside a project directory, shows a summary of all registered
projects. When run inside a project, shows detailed environment status. Live
server checks require your provider's API token in the environment (for
example `HETZNER_API_TOKEN` or `DIGITALOCEAN_API_TOKEN`).

{/* BEGIN GENERATED: flags status */}
| Flag | Description |
|------|-------------|
| `-env <name>` | Show only a specific environment |
| `-json` | Machine-readable JSON output |
{/* END GENERATED: flags status */}

---

## add

Add an optional service or feature to a Vibecarbon project.

```bash
# Interactive: prompts for which feature
vibecarbon add

# Add a specific feature
vibecarbon add observability

# Add multiple features
vibecarbon add observability redis
```

**Available features:** `observability`, `redis`.

CI/CD and external services (Stripe, OAuth, SMTP, etc.) live in
[`vibecarbon configure`](#configure) instead.

{/* BEGIN GENERATED: flags add */}
| Flag | Description |
|------|-------------|
| `-y` | Skip confirmation prompts |
| `-online` | Fetch the latest bundles from GitHub instead of the packaged copy |
{/* END GENERATED: flags add */}

---

## remove

Remove a feature from a Vibecarbon project.

```bash
# Interactive: prompts for which feature
vibecarbon remove

# Remove a specific feature
vibecarbon remove redis

# Remove without confirmation
vibecarbon remove redis -force
```

Service data (volumes, databases) is preserved; only deployment configs
(Docker / k8s manifests) are removed.

{/* BEGIN GENERATED: flags remove */}
| Flag | Description |
|------|-------------|
| `-y` | Skip confirmation prompts |
| `-force` | Skip confirmation prompt (alias for -y) |
| `-online` | Fetch the latest service definitions from GitHub instead of the packaged copy |
{/* END GENERATED: flags remove */}

---

## configure

Interactive wizard for configuring external services (billing, OAuth, SMTP,
CI/CD).

{/* BEGIN GENERATED: flags configure */}
| Flag | Description |
|------|-------------|
| `-forget <id>` | Only with `storage`: stop denying a deleted app storage key in the bucket fences |
{/* END GENERATED: flags configure */}

```bash
# Configure a new project after creation
vibecarbon configure

# Layer GitOps onto a deployed k8s cluster
vibecarbon configure cicd prod

# Choose which languages the app ships
vibecarbon configure globalization
```

Walks you through enabling features and entering API keys, then writes
everything to `.env.local` and `.env`. Configured credentials are deployed
automatically when you run `vibecarbon deploy`.

**Configurable features:** CI/CD (GitHub Actions), Billing (Stripe / Paddle /
Polar), Google OAuth, Microsoft OAuth, SMTP / Email, Plausible Analytics,
Globalization (which languages the app ships).

### `configure globalization` subcommand

Chooses which languages the app ships. Aliased as `configure languages`.

```bash
vibecarbon configure globalization
```

The locale files in `src/client/locales/` **are** the language set: the app
globs that directory, so there is no separate list to keep in sync and nothing
that can disagree with what actually ships. This command writes and deletes
those files for you.

Projects start with English only, and the language switcher hides itself while
there is just one language, so a single-language app has no dead control in its
navigation. Adding a language seeds every key with its English string, which
means the new file passes the parity check immediately and the command can tell
you exactly how much is still untranslated. Translate by editing the locale
file; the app picks it up on the next build.

English cannot be removed. It is the fallback language, and without it every
key renders as its own path.

Removing a language deletes its locale file, which discards the translations in
it. The command confirms first, and the file is recoverable with
`git checkout`.

### `configure cicd` subcommand

Sets up CI/CD in one or two stages, depending on what the environment runs.
This is the same CI/CD feature the interactive wizard offers; the subcommand
just skips the menu.

```bash
vibecarbon configure cicd          # stage 1 only
vibecarbon configure cicd prod     # stage 1, plus stage 2 if prod is k8s
```

**Stage 1** installs `.github/workflows/vibecarbon-build.yml` and
`.github/workflows/deploy.yml` if missing, points the image references and the
Flux repository URL at your GitHub owner and repo, and marks
`cicdEnabled: true` in `.vibecarbon.json`, where it also records that owner and
repo (`github`). It runs in every deploy mode. `vibecarbon upgrade` reads these
edits as its own, not yours: a file only the CLI changed is upgraded like an
untouched one and keeps your owner and repo.

Before stage 2 changes anything, it checks what Flux would build from your
`k8s/` tree through the cluster file `deploy.yml` applies. Flux applies the
files as they are and can't fill a placeholder such as `{{TRAEFIK_IMAGE}}`, so
if one would reach the cluster, the command stops and names the file and the
placeholder. When your Flux cluster file is older than `k8s/base`, it tells you
to take the new one from `vibecarbon upgrade`; for any other placeholder, it
names the file to fill in. An add-on's volume (redis, n8n, metabase) is not
Flux's: the claim names your provider's storage class, so
`vibecarbon deploy <env>` creates it, like the database's.

**Stage 2** connects to the cluster, installs Flux, seeds the GitHub
Environment secrets/vars, uploads `KUBECONFIG_B64`, and triggers the first
reconcile. For HA clusters the handover runs against both the primary and
standby kubeconfigs. It runs only when the named environment is `k8s` or
`k8s-ha`.

Naming a Compose environment does stage 1 and stops there, successfully.
Compose CD is push-based: the Actions workflow builds and deploys to your
server. Flux is a Kubernetes controller that reconciles from inside the
cluster, so there is nothing for it to do on Compose.

Pre-conditions: the `gh` CLI must be authenticated. For stage 2 the cluster
must already be deployed (`vibecarbon deploy <env>` with `-mode k8s` or
`-mode k8s-ha`).

After stage 2, future commits to `main` reconcile through Flux automatically.
The deploy path itself stays local-first: `vibecarbon deploy` continues to
build and sideload as before; GitOps just runs on top.

---

## upgrade

Update infrastructure files in your project to match the latest template.

```bash
# Preview changes without applying
vibecarbon upgrade -dry

# Interactive upgrade
vibecarbon upgrade

# Non-interactive: update safe files, skip merge files
vibecarbon upgrade -y
```

User source code (`src/**`, `content/**`, `migrations/**`) is never touched.
Files are classified into three categories:

- **Safe**: auto-replaced if you haven't modified them
- **Merge**: always shown for review (e.g. `docker-compose.yml`, `package.json`)
- **Never**: your code, never touched (e.g. `src/**`, `db/migrations/**`, `.env`)

The add-ons you installed with `vibecarbon add` are upgraded too: their compose, Kubernetes and volume files are compared against the add-on as this CLI ships it, under the same three categories. Each add-on's integration doc stays yours.

Some files the CLI edits after `create`: `vibecarbon configure cicd` points the image references and the Flux repository URL at your GitHub owner and repo, and `vibecarbon add` lists an add-on in `k8s/base/kustomization.yaml`. `upgrade` counts those edits as its own, so a file only the CLI changed is replaced like an untouched one, and every version it writes or offers keeps them. If you take one of those edits back out (an add-on entry you removed by hand, say), the file counts as yours and is offered for review. A CI workflow `configure cicd` installed before it was tracked is replaced when it is exactly a copy some release installed; one you changed is offered for review. On a GitOps project, if a file you kept would make Flux apply a placeholder it can't fill, `upgrade` names the file, the placeholder and what to do before you push.

A project created before sign-in moved into the app gets a `BETTER_AUTH_SECRET` in `.env.local` and `.env`, and `upgrade` warns you that a server you already deployed needs a fresh database: accounts are not carried over, and the old tables still point at the previous auth service. Run `vibecarbon backup` if you want a copy of the old data, then `vibecarbon destroy` and `vibecarbon deploy`.

A project created before the per-project state passphrase gets one too. It encrypts the secret values in your deploy state, so `VIBECARBON_STATE_PASSPHRASE` goes into `.env.local` only (never `.env`) and `.vibecarbon.json` records its fingerprint, which you commit. Keep a copy of the passphrase in your password manager.

{/* BEGIN GENERATED: flags upgrade */}
| Flag | Description |
|------|-------------|
| `-y` | Auto-accept safe replacements, skip merge files |
| `-dry` | Preview changes without applying |
| `-force` | Replace all files (creates .upgrade-backup copies) |
{/* END GENERATED: flags upgrade */}

---

## telemetry

Control anonymous usage analytics. `vibecarbon` sends command names,
versions, and (when inside a project) the provider and deploy mode — never
arguments, paths, or personal data — to help prioritize development. The
version update check is separate and always runs (it carries no data).

{/* BEGIN GENERATED: flags telemetry */}
_No flags beyond -h and -v._
{/* END GENERATED: flags telemetry */}

```bash
# Show whether analytics is on, and why (default with no subcommand)
vibecarbon telemetry

# Opt out
vibecarbon telemetry off

# Opt back in
vibecarbon telemetry on
```

Analytics is also disabled automatically when `DO_NOT_TRACK` or `CI` is set
in the environment, or when `VIBECARBON_TELEMETRY_DISABLED=1` is set.

---

# Deploy

Cloud infrastructure primitives.

## deploy

Deploy a Vibecarbon environment to the cloud.

```bash
# Interactive: prompts for env (defaults to prod) and mode
vibecarbon deploy

# Env seeded; prompts for the rest
vibecarbon deploy prod

# Scripted HA k8s deploy to Helsinki
vibecarbon deploy prod -mode k8s-ha -region hel1 -y

# Scripted single-server deploy to a new DigitalOcean environment
vibecarbon deploy prod -provider digitalocean -region nyc3 -mode compose -y

# Scripted compose deploy at an explicit placement (no region default)
vibecarbon deploy prod -region fsn1 -server-type cpx22 -y

# Redo a previously-failed deploy from scratch
vibecarbon deploy prod -full
```

Most settings (server type, S3, DNS, backup schedule, worker bounds) come from
the interactive prompt or `.vibecarbon.json`. Power users who want one-shot
scripted deploys configure `.vibecarbon.json` once and re-run with `-y` to skip
confirmations.

{/* BEGIN GENERATED: flags deploy */}
| Flag | Description |
|------|-------------|
| `-y` | Skip confirmation prompts |
| `-env <name>` | Environment seed (alternative to positional) |
| `-provider <id>` | Cloud provider for a NEW environment (existing environments keep their binding). Required with -y on a new environment. |
| `-region <id>` | Primary region (provider-specific, e.g. hel1 on Hetzner, nyc3 on DigitalOcean) |
| `-standby-region <id>` | HA standby/failover region (defaults to a same-continent partner of -region) |
| `-mode <mode>` | Deploy mode: compose, compose-ha, k8s, or k8s-ha |
| `-server-type <id>` | Server type (provider-specific, e.g. cpx22). Compose: the whole box; k8s: blanket for master/database/worker unless .vibecarbon.json sets them per role. Without it a scripted deploy takes the region default. |
| `-full` | Clear resume state and redo every step from scratch |
| `-restore <latest\|base\|timestamp>` | Disaster recovery: seed a new database from your wal-g backups in S3. Pass latest for the newest backup and all WAL, a base backup name (e.g. base_000000010000000000000004) for that backup and all WAL, or an ISO-8601 timestamp for point-in-time recovery. The restored database keeps its migration history, so the app applies only newer migrations. k8s and k8s-ha only, onto a fresh or destroyed environment. |
| `-lineage <system-identifier>` | With -restore: the database lineage to restore from. Each database archives in its own folder, so a destroyed and redeployed environment leaves its old backups beside the new database's. Needed only when more than one lineage holds backups; the refusal and restore -l name them. |
| `-allow-degraded` | HA only: proceed even if the standby is not verifiably streaming (warm-standby / degraded DR). By default an HA deploy FAILS unless replication is confirmed streaming. |
{/* END GENERATED: flags deploy */}

Provider support varies by mode: `compose` and `compose-ha` run on all five
providers, and `k8s` and `k8s-ha` run on Hetzner, DigitalOcean, and Linode. See
[Deployment](/docs/deployment#choosing-a-provider) for the full matrix and
the API token each provider reads.

Deploy refuses two cases before it changes anything, so an environment
built by an older vibecarbon is never swapped onto a stack that cannot run
its data:

- **The project was generated by an older CLI** (its `docker-compose.yml`
  still builds the database on the server). Run `vibecarbon upgrade`, review
  the changes, then deploy again.
- **The server's database was created by the older stack** (it has tables
  but no migration ledger, so the app cannot adopt it). The old stack keeps
  running. Take a copy with `vibecarbon backup`, dump the rows you want to
  keep, then `vibecarbon destroy` and `vibecarbon deploy` for a fresh
  database and load the rows by hand. On k8s the same case is refused when
  the cluster still runs the retired Helm chart database.

> Server types, worker bounds, domain, DNS provider, S3 credentials, and backup
> schedules are configured interactively or via `.vibecarbon.json`, and they don't
> have CLI flags. The "does this deserve a flag?" question is the forcing
> function for elegance: anything you'd set once and forget belongs in the
> config file.

---

## destroy

Tear down a cloud environment. **This is irreversible.**

```bash
# Interactive: prompts for env
vibecarbon destroy

# Env seeded; still prompts for confirmation
vibecarbon destroy prod

# Skip confirmation (dangerous!)
vibecarbon destroy prod -y

# Also delete its backups and uploads
vibecarbon destroy prod -y -purge

# Scripted production destroy (the typed confirmation as a flag)
vibecarbon destroy prod -y -confirm myapp-prod
```

The following are deleted from the environment's cloud provider: servers and
all data on them, volumes (orphaned PVCs), firewalls, and SSH keys (deployment
keys only) — plus DNS records and health checks at whichever DNS provider the
environment uses, and GitHub environment secrets.

> Production environments (`prod` or `production`) require a type-to-confirm
> prompt **even with `-y`**. This is a hard guard that can't be bypassed —
> scripts supply the value with `-confirm <project>-<env>`; without it, and
> with no terminal to type in, the command exits instead of waiting.

Each storage region of a project normally has one backups bucket, shared by
the project's environments in that region. An environment that already keeps
backups in a bucket, even one in another region, stays with it, so its backups
are never split. `-purge` deletes this environment's folder in its bucket, and
the bucket when no other environment keeps backups in it.

The Pulumi state bucket is kept and recorded as `retainedStateBucket` in
`.vibecarbon.json` so a redeploy resumes the same warm state backend; `-purge`
deletes it with the project's last live environment, since every environment's
stack lives in it.

{/* BEGIN GENERATED: flags destroy */}
| Flag | Description |
|------|-------------|
| `-y` | Skip confirmation prompts (does not skip the prod type-to-confirm) |
| `-env <name>` | Environment seed (alternative to positional) |
| `-orphans` | Destroy stray Pulumi stacks not tracked in config |
| `-purge` | Also delete this environment's backups and uploads, and the backup and state buckets once nothing else uses them (default: all kept) |
| `-force` | Destroy even when the pre-destroy backup fails or is skipped (default: the destroy stops) |
| `-confirm <value>` | Production only: supply the type-to-confirm value (project and env joined by a dash, like my-saas-prod) on the command line (scripts / no TTY) |
{/* END GENERATED: flags destroy */}

---

## backup

Create or manage database backups. Backups are wal-g base backups plus
continuous WAL archiving into your object-storage bucket; `create` pushes a
fresh base backup, `list` shows the restore points.

```bash
# Interactive: prompts for env and action
vibecarbon backup

# Env seeded; prompts for action
vibecarbon backup prod

# List backups for prod
vibecarbon backup prod -l

# Scripted base backup
vibecarbon backup prod -action create -y
```

{/* BEGIN GENERATED: flags backup */}
| Flag | Description |
|------|-------------|
| `-y` | Skip confirmation prompts |
| `-l` | List backups (read-only; equivalent to -action list) |
| `-env <name>` | Environment seed (alternative to positional) |
| `-action <verb>` | Action seed (skips the action prompt): create, list, or download |
| `-source <file>` | Backup filename for -action download (legacy backup-pod dumps only, k8s without object storage; wal-g environments restore with `vibecarbon restore`) |
{/* END GENERATED: flags backup */}

---

## restore

Restore the database to a point in time. Restore is wal-g-native: it fetches
the latest base backup from object storage and replays WAL either to the
present (`latest`) or to an ISO-8601 instant (point-in-time recovery). There
is no "restore this file" — backups are not files.

```bash
# Interactive: prompts for env and restore point
vibecarbon restore

# List restore points for prod
vibecarbon restore prod -l

# Latest base backup + all WAL, non-interactively
vibecarbon restore prod -y -source latest

# Point-in-time recovery
vibecarbon restore prod -source 2026-06-22T14:30:00Z

# Scripted production restore (the typed confirmation as a flag)
vibecarbon restore prod -y -source latest -confirm prod

# One base backup by name (that base + all WAL), as backup -l lists it
vibecarbon restore prod -source base_000000010000000000000004

# A lineage other than the current database (after a destroy and redeploy)
vibecarbon restore prod -source latest -lineage 7699032860122738725
```

Restore reads the backup bucket from your machine, so the bucket's
object-storage keys must be set locally; without them it stops and names the
variables. Each database archives under its own lineage (its system
identifier). When more than one lineage holds backups, restore asks for
`-lineage` and lists them.

Restoring a production environment asks you to type its name to confirm,
even with `-y`; `-confirm <env>` supplies it for scripts (without it, and
with no terminal, the command exits instead of waiting). Planner statistics
are rebuilt (`ANALYZE`) once the restored cluster promotes.

{/* BEGIN GENERATED: flags restore */}
| Flag | Description |
|------|-------------|
| `-y` | Skip confirmation prompts |
| `-l` | List available backups (read-only; does not restore) |
| `-env <name>` | Environment seed (alternative to positional) |
| `-source <latest\|base-name\|ISO-timestamp>` | Restore point: `latest` (newest base backup + all WAL), a base backup name (that base + all WAL), or an ISO-8601 timestamp (PITR) |
| `-lineage <system-identifier>` | The database lineage to restore from. Each database archives in its own folder, so a destroyed and redeployed environment leaves its old backups beside the new database's. Needed only when more than one lineage holds backups and -source does not name a base backup that only one of them has; the refusal names them. |
| `-confirm <value>` | Production only: supply the type-to-confirm value on the command line (scripts / no TTY) |
{/* END GENERATED: flags restore */}

---

## failover

Promote the standby region of an HA deployment to primary.

```bash
# Interactive: prompts for env
vibecarbon failover

# Preview the failover plan
vibecarbon failover prod -dry

# Execute without confirmation
vibecarbon failover prod -y
```

Behavior depends on deployment topology:

| Topology | Behavior |
|----------|----------|
| HA + Cloudflare DNS | Promotes standby DB, switches DNS A record automatically |
| HA + provider DNS (Hetzner, DigitalOcean, Linode, Vultr, Scaleway) | Promotes standby DB, switches DNS A record automatically |
| HA + manual DNS | Promotes standby DB, prints DNS update instructions |
| Single server | Prints backup/restore recovery steps (failover is a no-op) |

{/* BEGIN GENERATED: flags failover */}
| Flag | Description |
|------|-------------|
| `-y` | Skip confirmation prompts |
| `-dry` | Show plan without executing |
| `-force-unproven` | Primary is dead and nothing proves the standby holds its data: promote it anyway (unplanned only) |
| `-force-unplanned` | Your machine cannot reach the primary but the standby still sees it streaming: fail over anyway, knowing the old primary may still be serving |
| `-allow-degraded` | Only applies together with -force-unproven (refused on its own): also accept a standby the last deploy flagged degraded |
| `-abort` | Call off a failover that is stuck mid-flight: stops the standby database, and the old primary serves again |
| `-env <name>` | Environment seed (alternative to positional) |
| `-server-type <id>` | Worker server type override for pilot-light failover provisioning (e.g. cx33) |
| `-confirm <value>` | Production only: supply the type-to-confirm value on the command line (scripts / no TTY) |
{/* END GENERATED: flags failover */}

---

## scale

Adjust instance types post-deploy without re-running the full deploy flow.

```bash
# Interactive: prompts for env and changes
vibecarbon scale

# Env seeded; prompts for changes
vibecarbon scale prod

# Scripted: resize all roles (cx33 is a Hetzner server type)
vibecarbon scale -env prod -type cx33 -y
```

| Topology | What you can change |
|----------|---------------------|
| Compose / Compose HA | VPS server type (blue-green; the app pauses for the cutover) |
| Kubernetes | Worker / master / database server types (in-place) |
| Kubernetes | Worker bounds (autoscaler floor + ceiling) |

A compose scale builds the new server, fences writes on the old one, pushes
a base backup, restores it on the new server and moves DNS. The app pauses
from the fence until the new server serves. It needs the backup bucket's
object-storage keys on your machine (the refusal names the variables), since
the new server is seeded from a backup. Compose scale is not available on
Scaleway yet: resize the server in the Scaleway console instead.

If a scale stops part way through the cutover (a killed terminal, a lost
connection), run it again. It reads where it stopped, finishes the move to
the new server, or rolls back to the old one if DNS never moved. Deploy,
destroy and the next backup refuse until it has:

```bash
vibecarbon scale prod
```

{/* BEGIN GENERATED: flags scale */}
| Flag | Description |
|------|-------------|
| `-y` | Skip confirmations (required with -type) |
| `-env <name>` | Environment seed (alternative to positional) |
| `-direct` | Compose: build the app image on the new server instead of on this machine. A deploy run with -direct already does this; use it when this machine's docker cannot build amd64 |
| `-type <id>` | Server type to scale to, from the environment's own provider catalog (e.g. cx33 on Hetzner, s-4vcpu-8gb on DigitalOcean). Compose: resizes the VPS. K8s: resizes all roles. |
{/* END GENERATED: flags scale */}

---

# Debug & Access

Operator tools for cluster introspection and access management.

## shell

Drop into an interactive bash with cluster context exported.

{/* BEGIN GENERATED: flags shell */}
_No flags beyond -h and -v._
{/* END GENERATED: flags shell */}

```bash
# Default to prod
vibecarbon shell

# Specific environment
vibecarbon shell staging
```

Exports `KUBECONFIG`, `VC_SSH_KEY`, `VC_KNOWN_HOSTS`, `VC_ENV`, and the
environment provider's own CLI token variable, so `kubectl` and that provider's
CLI "just work" against the named environment. On Hetzner that is
`HCLOUD_TOKEN` plus `HCLOUD_NETWORK`; a provider whose controller manager reads
its network identity from instance metadata instead (DigitalOcean, for example)
exports the token alone. Use SSH directly for per-node debug. The master IP and
SSH key path are in the welcome banner.

---

## diagnose

Dump full cluster state for an environment.

{/* BEGIN GENERATED: flags diagnose */}
_No flags beyond -h and -v._
{/* END GENERATED: flags diagnose */}

```bash
# Full dump (excludes the heavy egress probe)
vibecarbon diagnose prod

# Just one section
vibecarbon diagnose prod network
vibecarbon diagnose prod flux

# Why a certificate is pending (cert-manager objects + controller log)
vibecarbon diagnose prod tls

# Heavy egress probe (netshoot DNS + MTU + route battery)
vibecarbon diagnose prod egress
```

Streams sections to stdout AND writes the full report to
`~/.vibecarbon/diag-<env>-<timestamp>.txt`.

**Sections:** `nodes`, `pods`, `tls`, `network`, `flux`, `hcloud`, `egress`, `all`
(default, excludes `egress`). `tls` lists every Certificate, CertificateRequest,
Order and Challenge with its reason, and the last two hours of the cert-manager
controller log: when an order fails, the reason Let's Encrypt gave is on its
Challenge, not on the Order.

---

## console

Open Hetzner's web VNC console for a node. A last-resort debug helper for when
SSH is broken (firewall change, cloud-init failure, kernel panic). Hetzner-only
today: on an environment deployed elsewhere it exits with an unsupported-provider
error, and you reach for that provider's own web console instead.

{/* BEGIN GENERATED: flags console */}
_No flags beyond -h and -v._
{/* END GENERATED: flags console */}

```bash
# Open the noVNC URL for the master node
vibecarbon console master

# Specific server by full name
vibecarbon console myproject-prod-db
```

The `<node>` argument is a substring matched against server names. Tries
`hcloud server request-console` (which prints the noVNC URL directly) when
available; otherwise prints the Hetzner Cloud Console URL and the server ID
so you can click through. Does NOT auto-open a browser.

---

## access

Manage the operator-CIDR allowlist that locks SSH (port 22) and the Kubernetes
API (port 6443) on the cloud firewall. The allowlist push assumes one provider
per project and targets the Hetzner Cloud firewall today.

{/* BEGIN GENERATED: flags access */}
_No flags beyond -h and -v._
{/* END GENERATED: flags access */}

```bash
# List current CIDRs (default)
vibecarbon access

# Add a CIDR + push to all firewalls
vibecarbon access add 5.6.7.8/32

# Remove a CIDR + push to all firewalls
vibecarbon access remove 5.6.7.8/32

# Drop entries with lastUsedAt > 90 days, push
vibecarbon access prune
```

Every interactive command that needs SSH or k8s-API access (`deploy`, `shell`,
`diagnose`, `scale`, `failover`, `backup`, `restore`) auto-detects the
operator's public IP, persists it under `operatorCidrs` in `.vibecarbon.json`,
and patches the live firewall via the environment's provider API. Subsequent
commands from the same IP are silent.

**Non-interactive (`-y`) flows do *not* auto-detect**. CI runners have
ephemeral IPs that would pollute the list. Either commit a populated
`operatorCidrs` to `.vibecarbon.json` or set
`ALLOWED_SSH_IPS="1.2.3.4/32,5.6.7.8/32"` once on the first deploy.

If you somehow lock yourself out (no Hetzner API token, API unreachable), use
[`vibecarbon console <node>`](#console): Hetzner's web VNC bypasses the
firewall entirely.

---

## Environment Variables

| Variable | Description |
|----------|-------------|
| `HETZNER_API_TOKEN`, `DIGITALOCEAN_API_TOKEN`, `LINODE_API_TOKEN`, `VULTR_API_TOKEN`, `SCALEWAY_SECRET_KEY` | Your environment provider's API token — enables live server status checks and deployment. You only need the one for the provider that environment uses. |
| `CLOUDFLARE_API_TOKEN` | Required for Cloudflare DNS operations |
| `ALLOWED_SSH_IPS` | Bootstrap CIDRs for non-interactive deploys (CI) |
| `DEV_PORT_OFFSET` | Port offset for local development (set by `vibecarbon up`) |
