### Start development environment with vibecarbon up

Source: https://vibecarbon.com/docs/getting-started

Starts the entire development environment: Docker services (PostgreSQL, Supabase, Traefik), database migrations, and dev servers (Hono API on port 3000, Vite on port 5173). Run from the project directory created earlier.

```bash
cd my-app
vibecarbon up
```

--------------------------------

### Start the local development environment with vibecarbon up

Source: https://vibecarbon.com/docs/cli

The up command boots Docker services, runs migrations, and starts the API and frontend servers.

```bash
vibecarbon up
```

--------------------------------

### SQL migration example for a new table with RLS (00002_my_table.sql)

Source: https://vibecarbon.com/docs/database

Example migration file demonstrating the creation of a table, index, RLS policies for CRUD, and an updated_at trigger. Follows the conventions of using zero-padded naming, enabling row-level security, adding timestamps, and adding indexes for foreign keys.

```sql
-- supabase/migrations/00002_my_table.sql

CREATE TABLE IF NOT EXISTS my_table (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  user_id UUID NOT NULL REFERENCES auth.users(id) ON DELETE CASCADE,
  name TEXT NOT NULL,
  created_at TIMESTAMPTZ DEFAULT NOW(),
  updated_at TIMESTAMPTZ DEFAULT NOW()
);

CREATE INDEX IF NOT EXISTS idx_my_table_user_id ON my_table(user_id);

-- Enable RLS
ALTER TABLE my_table ENABLE ROW LEVEL SECURITY;

-- CRUD policies
CREATE POLICY "Users can view their own items"
  ON my_table FOR SELECT
  USING (user_id = (SELECT auth.uid()));

CREATE POLICY "Users can create their own items"
  ON my_table FOR INSERT
  WITH CHECK (user_id = (SELECT auth.uid()));

CREATE POLICY "Users can update their own items"
  ON my_table FOR UPDATE
  USING (user_id = (SELECT auth.uid()));

CREATE POLICY "Users can delete their own items"
  ON my_table FOR DELETE
  USING (user_id = (SELECT auth.uid()));

-- Auto-update updated_at
CREATE TRIGGER my_table_updated_at
  BEFORE UPDATE ON my_table
  FOR EACH ROW
  EXECUTE FUNCTION update_updated_at();
```

--------------------------------

### Install the VibeCarbon CLI

Source: https://vibecarbon.com/docs/getting-started

Installs the VibeCarbon CLI globally to make the vibecarbon command available on your system PATH.

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

--------------------------------

### Deploy, restore, and verify commands

Source: https://vibecarbon.com/docs/deployment

Deploy to the new placement, restore the backup, and verify. The new server starts with an empty database, so restore is required. Use -source latest and -confirm for scripted restore.

```bash
vibecarbon deploy prod -y
```

```bash
vibecarbon restore prod -l
vibecarbon restore prod -source latest                 # type "prod" to confirm
vibecarbon restore prod -y -source latest -confirm prod   # scripted
```

```bash
vibecarbon status prod
vibecarbon backup prod                    # wal-g works from the new server
```

--------------------------------

### Reset and cold start development environment

Source: https://vibecarbon.com/docs/development

Commands to remove all Docker containers, volumes, and built images, then cold start with Docker, migrations, and dev servers. dev:reset does not restart services; run dev:start afterward.

```bash
npm run dev:reset  # Remove containers, volumes, and built images
npm run dev:start  # Cold start: Docker + migrations + dev servers
```

--------------------------------

### Docker Compose Production Deployment

Source: https://vibecarbon.com/docs/deployment

Starts the application with the production overlay, which adds environment variables, resource limits, restart policies, Traefik SSL, and host-based routing.

```bash
docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d
```

--------------------------------

### vibecarbon deploy command examples

Source: https://vibecarbon.com/docs/cli

Shows various ways to deploy a Vibecarbon environment: interactive, with env seed, scripted HA k8s, scripted single-server, and full redo. Use -y for scripted deploys, -mode for deploy mode, -provider for new environments, and -full to redo a failed deploy.

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

```bash
# Env seeded; prompts for the rest
vibecarbon deploy prod
```

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

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

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

--------------------------------

### vibecarbon upgrade command examples

Source: https://vibecarbon.com/docs/cli

Shows how to preview, run interactively, or auto-accept safe replacements with the vibecarbon upgrade command. Use -dry to preview changes, no flags for interactive upgrade, and -y to update safe files while skipping merge files. User source code is never touched.

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

```bash
# Interactive upgrade
vibecarbon upgrade
```

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

--------------------------------

### vibecarbon backup command examples

Source: https://vibecarbon.com/docs/cli

Shows usage of the 'vibecarbon backup' command. Supports interactive mode, environment seeding, listing backups, and scripted downloads. Flags: -h shows help, -y skips confirmation, -l lists backups (equivalent to -action list), -env seeds environment, -action sets action (create, list, download), -source specifies backup filename (required for non-interactive download).

```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 download
vibecarbon backup -env prod -action download -source myapp_20260507.tar.gz
```

--------------------------------

### Kubernetes Deployment Commands

Source: https://vibecarbon.com/docs/deployment

Deploy to Kubernetes using the `vibecarbon` CLI. The bare command opens a guided prompt; the seeded command specifies environment and mode for scripted deployment.

```bash
# Bare command opens a guided prompt for env, mode, region, etc.
vibecarbon deploy

# Or seed env + mode for a scripted deploy
vibecarbon deploy prod -mode k8s
```

--------------------------------

### vibecarbon configure cicd command usage

Source: https://vibecarbon.com/docs/cli

Sets up CI/CD in one or two stages. Stage 1 installs GitHub Actions workflows and marks cicdEnabled: true; stage 2 connects to the cluster, installs Flux, and triggers the first reconcile. Stage 2 runs only when the named environment is k8s or k8s-ha. Naming a Compose environment does stage 1 only. Pre-conditions: gh CLI authenticated; for stage 2, cluster must be deployed with -mode k8s or -mode k8s-ha.

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

--------------------------------

### Define a new API route

Source: https://vibecarbon.com/docs/development

Create a route file in src/server/routes/v1/ using Hono and Zod for validation. This example demonstrates fetching and creating items via Supabase.

```typescript
import { Hono } from 'hono';
import { z } from 'zod';
import type { HonoVariables } from '../../types';

const items = new Hono<{ Variables: HonoVariables }>();

const createSchema = z.object({
  name: z.string().min(1).max(100),
});

items.get('/', async (c) => {
  const user = c.get('user');
  if (!user) return c.json({ error: 'Unauthorized' }, 401);

  const supabase = c.get('supabase');
  const { data, error } = await supabase.from('items').select('*');
  if (error) return c.json({ error: 'Failed to fetch items' }, 500);
  return c.json(data);
});

items.post('/', async (c) => {
  const user = c.get('user');
  if (!user) return c.json({ error: 'Unauthorized' }, 401);

  const body = await c.req.json();
  const result = createSchema.safeParse(body);
  if (!result.success) {
    return c.json({ error: result.error.issues.map((e) => e.message).join(', ') }, 400);
  }

  const supabase = c.get('supabase');
  const { data, error } = await supabase
    .from('items')
    .insert(result.data)
    .select()
    .single();
  if (error) return c.json({ error: 'Failed to create item' }, 500);
  return c.json({ item: data }, 201);
});

export { items };
```

--------------------------------

### Activate license and deploy with vibecarbon

Source: https://vibecarbon.com/docs/getting-started

Activates a license key for the project (writes .vibecarbon.license) and then deploys. Required for Kubernetes or HA environments; single-server Docker Compose can skip activation. The deploy command opens a guided prompt for environment, mode (compose, k8s, k8s-ha), and region.

```bash
vibecarbon activate <your-key>
vibecarbon deploy
```

--------------------------------

### vibecarbon failover command examples

Source: https://vibecarbon.com/docs/cli

Shows interactive, dry-run, and non-interactive usage of the vibecarbon failover command. The -dry flag previews the failover plan without executing, and -y skips confirmation prompts.

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

# Preview the failover plan
vibecarbon failover prod -dry

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

--------------------------------

### Stop and restart services without losing data

Source: https://vibecarbon.com/docs/development

Commands to stop services while preserving data in volumes, restart services with existing data, and start dev servers.

```bash
npm run docker:down # Stop services, data preserved in volumes
npm run docker:up  # Restart services with existing data
npm run dev        # Start dev servers
```

--------------------------------

### vibecarbon usage forms

Source: https://vibecarbon.com/docs/cli

Shows the three usage forms for the vibecarbon CLI. Running a bare command opens a guided prompt flow; positionals and flags are optional prompt seeds that pre-fill and skip the corresponding prompt. In CI or piped-stdin contexts that cannot prompt, the command fails with a canonical error naming the flags that would unblock the invocation.

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

--------------------------------

### vibecarbon restore command examples

Source: https://vibecarbon.com/docs/cli

Shows interactive and non-interactive usage of the vibecarbon restore command. The -source flag accepts a local file path, an S3 backup name, or the literal 'latest' to fetch the most recent S3 backup. The -l flag lists available backups without restoring.

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

# List available backups for prod
vibecarbon restore prod -l

# Restore a specific backup from S3
vibecarbon restore prod -source myapp_20260507.tar.gz

# Restore from a local file
vibecarbon restore prod -source ./backup.tar.gz -y

# Restore the most-recent S3 backup, non-interactively
vibecarbon restore prod -y -source latest
```

--------------------------------

### vibecarbon destroy command examples

Source: https://vibecarbon.com/docs/cli

Shows usage of the 'vibecarbon destroy' command. The command is irreversible and deletes servers, volumes, firewalls, SSH keys, DNS records, health checks, and GitHub environment secrets. Production environments require a type-to-confirm prompt even with -y. Flags: -y skips confirmation (not prod type-to-confirm), -env seeds environment, -orphans destroys stray Pulumi stacks, -purge deletes backup S3 bucket.

```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 the backup S3 bucket
vibecarbon destroy prod -y -purge
```

--------------------------------

### Build client and server for production

Source: https://vibecarbon.com/docs/deployment

Run this command to build the client and server for production. It produces static assets in dist/client/ and a bundled API server in dist/server/.

```bash
npm run build
```

--------------------------------

### Get authenticated user in route handler

Source: https://vibecarbon.com/docs/authentication

Use inside a route handler after middleware validation. Returns 401 Unauthorized if no user is present.

```typescript
const user = c.get('user');
if (!user) return c.json({ error: 'Unauthorized' }, 401);
```

--------------------------------

### Create a new VibeCarbon project

Source: https://vibecarbon.com/docs/getting-started

Scaffolds a new full-stack application in the specified directory. You will be prompted for an admin email and password during the process.

```bash
vibecarbon create my-app
```

--------------------------------

### Deploy with mode, region, and provider flags

Source: https://vibecarbon.com/docs/environments

Deploy with explicit mode, region, provider, and skip prompts. -provider selects the cloud for a new environment; -region takes that provider's region ids. An environment keeps its first provider, so later deploys don't repeat the flag.

```bash
# Pick mode interactively, including k8s/k8s-ha and worker bounds
vibecarbon deploy prod

# Scripted: explicit mode, region, and skip prompts (hel1 is a Hetzner region)
vibecarbon deploy prod -mode k8s-ha -region hel1 -y

# A new environment on a different cloud (nyc3 is a DigitalOcean region)
vibecarbon deploy staging -provider digitalocean -region nyc3 -mode compose -y
```

--------------------------------

### Use service role client to bypass RLS

Source: https://vibecarbon.com/docs/authentication

Import supabaseAdmin for admin tasks or webhooks that need to bypass Row Level Security. Example queries all organizations.

```typescript
import { supabaseAdmin } from '@/server/lib/supabase';

const { data } = await supabaseAdmin.from('organizations').select('*');
```

--------------------------------

### Backup and restore commands

Source: https://vibecarbon.com/docs/environments

Manage backups: create a manual backup, list backups with -l, and restore interactively. Backups run automatically on a schedule that differs by environment.

```bash
# Create a manual backup
vibecarbon backup staging

# List backups
vibecarbon backup prod -l

# Restore (interactive picker)
vibecarbon restore staging
```

--------------------------------

### Scaffold a new project with vibecarbon create

Source: https://vibecarbon.com/docs/cli

Use the create command to scaffold a new project. The interactive mode is recommended, while the power-user flags allow for non-interactive CI usage.

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

--------------------------------

### Sign up with email, password, and optional display name

Source: https://vibecarbon.com/docs/authentication

Uses the useAuth hook's signUp method to create a new account. The name parameter is stored in user_metadata.full_name. After sign-up, the user is signed in and redirected to onboarding.

```typescript
const { signUp } = useAuth();

await signUp('user@example.com', 'password', 'Jane Smith');
// User is signed in and redirected to onboarding
```

--------------------------------

### Run database migrations with npm

Source: https://vibecarbon.com/docs/database

Use `npm run db:migrate` to apply SQL migrations located in the `supabase/migrations/` directory.

```bash
npm run db:migrate
```

--------------------------------

### vibecarbon configure globalization command

Source: https://vibecarbon.com/docs/cli

Chooses which languages the app ships. Aliased as 'configure languages'. The locale files in src/client/locales/ are the language set; this command writes and deletes those files. Projects start with English only, and English cannot be removed. Removing a language deletes its locale file (recoverable with git checkout).

```bash
vibecarbon configure globalization
```

--------------------------------

### Set environment variables for self-hosted Plausible

Source: https://vibecarbon.com/docs/analytics

Configure the Plausible domain and script URL for a self-hosted instance. Replace the script URL with your own domain.

```bash
VITE_PLAUSIBLE_DOMAIN="yourdomain.com"
VITE_PLAUSIBLE_SCRIPT_URL="https://analytics.yourdomain.com/js/script.js"
```

--------------------------------

### Baseline and backup commands

Source: https://vibecarbon.com/docs/deployment

Run these commands to check status and create a fresh backup before moving. The -l flag lists backups, and the new backup appears at the top.

```bash
vibecarbon status
vibecarbon backup prod
vibecarbon backup prod -l          # new backup is at the top
```

--------------------------------

### vibecarbon console: open Hetzner web VNC console

Source: https://vibecarbon.com/docs/cli

Open Hetzner's web VNC console for a node. The <node> argument is a substring matched against server names. Tries hcloud server request-console when available; otherwise prints the Hetzner Cloud Console URL and server ID. Does NOT auto-open a browser. Hetzner-only; exits with unsupported-provider error elsewhere.

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

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

--------------------------------

### Set environment variables for Plausible Cloud

Source: https://vibecarbon.com/docs/analytics

Configure the Plausible domain and script URL for the cloud service. Set these in your environment before building.

```bash
VITE_PLAUSIBLE_DOMAIN="yourdomain.com"
VITE_PLAUSIBLE_SCRIPT_URL="https://plausible.io/js/script.js"
```

--------------------------------

### vibecarbon diagnose: dump cluster state

Source: https://vibecarbon.com/docs/cli

Dump full cluster state for an environment. Full dump excludes the heavy egress probe; pass a section name to get just that section. The egress probe runs a netshoot DNS + MTU + route battery. Streams sections to stdout and writes the full report to ~/.vibecarbon/diag-<env>-<timestamp>.txt.

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

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

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

--------------------------------

### Activate a license key with vibecarbon activate

Source: https://vibecarbon.com/docs/cli

Run inside the project directory containing .vibecarbon.json. The key is bound to the project's id and writes .vibecarbon.license; commit that file so others and CI can deploy without holding the key. A key is bound to one project at a time; activating in a second project is refused until released with deactivate.

```bash
# Prompts for the key
vibecarbon activate

# Key seeded
vibecarbon activate vc-...
```

--------------------------------

### Add observability stack with vibecarbon add observability

Source: https://vibecarbon.com/docs/deployment

Run this command to add the observability stack, which includes Prometheus for metrics collection, Grafana for dashboards, and Loki for log aggregation. Access Grafana at https://grafana.your-domain.com, which requires the 'super_admin' role in production.

```bash
vibecarbon add observability
```

--------------------------------

### Kubernetes Directory Structure

Source: https://vibecarbon.com/docs/deployment

Shows the layout of the `k8s/` directory with base manifests and overlays for staging and production.

```text
k8s/
├── base/                # Shared manifests
│   ├── app/             # App deployment, service, ingress
│   ├── supabase/        # Supabase services
│   └── kustomization.yaml
└── overlays/
    ├── staging/         # Staging-specific config
    └── production/      # Production-specific config
```

--------------------------------

### vibecarbon backup and restore commands

Source: https://vibecarbon.com/docs/deployment

Commands to create, list, and restore database backups. The backup command without arguments prompts for environment and action; specifying an environment creates a backup; -l lists backups; restore uses an interactive picker.

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

# Create a backup for a specific env
vibecarbon backup prod

# List existing backups
vibecarbon backup prod -l

# Restore from a backup (interactive picker)
vibecarbon restore prod
```

--------------------------------

### vibecarbon configure command usage

Source: https://vibecarbon.com/docs/cli

Interactive wizard for configuring external services (billing, OAuth, SMTP, CI/CD). Use without arguments to configure a new project, specify 'cicd prod' to layer GitOps onto a deployed k8s cluster, or use 'globalization' to choose which languages the app ships. Writes to .env.local and .env; configured credentials deploy automatically with vibecarbon deploy.

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

--------------------------------

### Deploy with DigitalOcean provider

Source: https://vibecarbon.com/docs/deployment

Deploys a new environment named 'prod' to DigitalOcean in the nyc3 region using compose mode. The -provider flag is required with -y for non-interactive creation, and -region must match the provider's region id.

```bash
vibecarbon deploy prod -provider digitalocean -region nyc3 -mode compose -y
```

--------------------------------

### Show project and deployment status with vibecarbon status

Source: https://vibecarbon.com/docs/cli

Shows project and deployment status. Use -env to filter by environment and -json for machine-readable output. Live server checks require provider API tokens like HETZNER_API_TOKEN or DIGITALOCEAN_API_TOKEN.

```bash
# Full status
vibecarbon status

# Specific environment
vibecarbon status -env prod

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

--------------------------------

### vibecarbon scale: interactive and scripted instance resizing

Source: https://vibecarbon.com/docs/cli

Adjust instance types post-deploy. Interactive mode prompts for env and changes; with -env prod it prompts for changes only. Scripted mode uses -env, -type, and -y to resize all roles (cx33 is a Hetzner server type). -y is required with -type.

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

--------------------------------

### Schedule a custom job with cron.schedule

Source: https://vibecarbon.com/docs/background-jobs

Create a new scheduled task by defining a unique name, a cron expression, and the SQL logic to execute within a migration file.

```sql
-- supabase/migrations/XXXXXX_my_custom_job.sql

SELECT cron.schedule(
  'my-job-name',           -- unique job name
  '*/30 * * * *',          -- cron expression (every 30 minutes)
  $$
  DO $$
  DECLARE
    affected INTEGER;
  BEGIN
    -- Your SQL logic here
    DELETE FROM some_table WHERE expired_at < now();
    GET DIAGNOSTICS affected = ROW_COUNT;

    -- Log the result
    PERFORM public.log_cron_job('my-job-name', 'succeeded',
      'Processed ' || affected || ' rows');
  EXCEPTION WHEN OTHERS THEN
    PERFORM public.log_cron_job('my-job-name', 'failed', NULL, SQLERRM);
  END $$;
  $$
);
```

--------------------------------

### Updated .vibecarbon.json configuration

Source: https://vibecarbon.com/docs/deployment

Add back the environments.prod entry with the new region and serverType. Set serverType explicitly to avoid the medium-tier default.

```json
"environments": {
  "prod": {
    "provider": "hetzner",
    "envName": "prod",
    "deployMode": "compose",
    "domain": "app.example.com",
    "dnsProvider": "cloudflare",
    "dns": { "provider": "cloudflare", "zoneId": "…" },
    "backupS3": { "bucket": "<project>-<salt>-backups", "region": "fsn1",
                  "endpoint": "https://fsn1.your-objectstorage.com" },
    "backup": { "schedule": "0 */6 * * *", "retentionDays": 30 },
    "region": "fsn1",
    "serverType": "cpx22"
  }
}
```

--------------------------------

### Deploy to named environments

Source: https://vibecarbon.com/docs/environments

Deploy to named environments. The environment name is free-form; prod (alias production) is the only special name and unlocks production-grade defaults.

```bash
vibecarbon deploy prod      # Production
vibecarbon deploy staging   # Staging
vibecarbon deploy dev       # Dev / preview
```

--------------------------------

### Client-side Supabase queries with RLS

Source: https://vibecarbon.com/docs/database

Shows how to fetch and insert data from the client using the Supabase client, with Row Level Security enforced automatically.

```typescript
import { supabase } from '@/lib/supabase';

// Fetch data (RLS enforced automatically)
const { data: items, error: fetchError } = await supabase
  .from('my_table')
  .select('*');

// Insert data
const { data: newItem, error: insertError } = await supabase
  .from('my_table')
  .insert({ name: 'New item' })
  .select()
  .single();
```

--------------------------------

### Reset local development environment with vibecarbon reset

Source: https://vibecarbon.com/docs/cli

Removes containers, Docker volumes, and locally-built images. All local database data will be lost. Use -y to skip the confirmation prompt. Run 'vibecarbon up' afterward to restart.

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

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