@novahelm/cli

The Nova Engine CLI. Scaffold, develop, deploy, and operate NovaHelm projects from the command line.

Installation

The CLI is installed automatically when you create a new NovaHelm project:

npx @novahelm/cli new my-app

Or install globally:

npm install -g @novahelm/cli

Re-linking the local CLI binary (monorepo dev)

The novahelm shell command is a homebrew-installed npm-global at /opt/homebrew/bin/novahelm → /opt/homebrew/lib/node_modules/@novahelm/cli/dist/index.mjs. After making CLI changes in this monorepo, run:

pnpm cli:relink   # alias of cli:install — builds + npm link's local dist

This rebuilds packages/cli/dist and re-links the homebrew binary at /opt/homebrew/bin/novahelm to the local worktree's dist via symlink. After running, which novahelm resolves to /opt/homebrew/bin/novahelm but executes your local source.

If you skip this step after a git pull that touches packages/cli/, you'll be running stale CLI code (the npm-global is whatever was published last, not what's in your worktree).

Commands

Project Scaffolding

novahelm new <name>

Create a new NovaHelm project from a template.

novahelm new my-app
novahelm new my-shop --template commerce
novahelm new my-blog --template content

novahelm generate <type> <name>

Generate boilerplate files (models, routes, components, etc.).

novahelm generate model Post
novahelm generate router posts
novahelm generate page dashboard

Development

novahelm dev

Start the development environment (Docker infra + Next.js dev server).

novahelm dev

novahelm db <subcommand>

Manage the database.

novahelm db push       # Push schema changes
novahelm db seed       # Run seed scripts
novahelm db studio     # Open the NovaHelm schema/data browser

novahelm doctor

Check that your development environment is correctly configured.

novahelm doctor

Environment

novahelm env init [output-path]

Interactively create a .env file for production or development.

novahelm env init                    # Interactive setup
novahelm env init --defaults         # Use all defaults (for CI)
novahelm env init .env.staging       # Custom output path

novahelm env check [env-file]

Validate that required environment variables are set.

novahelm env check
novahelm env check .env.staging

Deploy & Operations

Full walkthrough: Deploy Guide

novahelm deploy

One-command build, migrate, and deploy.

novahelm deploy                              # Auto-detect target (Coolify or Compose)
novahelm deploy --target coolify             # Force Coolify deploy
novahelm deploy --target compose             # Force Docker Compose deploy
novahelm deploy --skip-build                 # Skip image build step
novahelm deploy --skip-migrate               # Skip database migrations
novahelm deploy --force                      # Skip pre-flight checks (env validation, DNS)
novahelm deploy --env-file .env.staging      # Use a specific env file

What it does:

1. Builds Docker images (Compose) or triggers a build (Coolify)
2. Runs drizzle-kit push for database migrations
3. Deploys services (Compose up -d or Coolify restart)
4. Runs health checks (Compose only)

novahelm up

Start the production Docker Compose stack.

novahelm up                     # Start services + run migrations
novahelm up --build             # Rebuild images first
novahelm up --skip-migrate        # Skip migrations
novahelm up --env-file path     # Custom env file

novahelm down

Stop the production stack.

novahelm down                   # Stop services, keep data
novahelm down --volumes         # Stop services AND delete all data (asks for confirmation)

novahelm status

Show a health dashboard of all running services.

novahelm status                 # Production stack (auto-detects Coolify or Compose)
novahelm status --dev           # Development stack
novahelm status --json          # Machine-readable output
novahelm status --watch         # Live refresh every 5s

When Coolify is configured, shows app details and recent deployments. Otherwise shows Docker Compose service table.

Example output:

  NovaHelm Service Status

 Service  | State   | Health  | Ports                    | Uptime
----------+---------+---------+--------------------------+---------
 web      | running | healthy | 0.0.0.0:3000->3000/tcp   | 2 hours
 jobs     | running | —       |                          | 2 hours
 realtime | running | healthy | 0.0.0.0:3001->3001/tcp   | 2 hours
 postgres | running | healthy | 0.0.0.0:5432->5432/tcp   | 2 hours
 redis    | running | healthy | 0.0.0.0:6379->6379/tcp   | 2 hours
 minio    | running | —       | 0.0.0.0:9000-9001->9000… | 2 hours

  Health Endpoints:
    Web API:    OK
    Realtime:   OK

novahelm logs [service]

Stream logs from production services.

novahelm logs                   # All services (auto-detects Coolify or Compose)
novahelm logs web               # Only the web service
novahelm logs jobs -n 500       # Last 500 lines
novahelm logs --since 1h        # Logs from the last hour
novahelm logs web --no-follow   # Print and exit (don't stream)
novahelm logs --dev             # Development stack logs

When Coolify is configured, fetches deployment logs from the Coolify API. Otherwise uses docker compose logs.

novahelm secrets <subcommand>

Manage production secrets. Uses the Coolify API when configured, otherwise edits .env.production directly.

novahelm secrets set DATABASE_PASSWORD=newpass
novahelm secrets list
novahelm secrets list --show-values
novahelm secrets get STRIPE_SECRET_KEY
novahelm secrets delete OLD_VAR

novahelm rollback [version]

Rollback to a previous deployment (requires Coolify).

novahelm rollback --list        # Show recent deployments
novahelm rollback               # Interactive selection
novahelm rollback abc123        # Rollback to specific commit/ID
novahelm rollback -n 20         # Show last 20 deployments

novahelm preview

Spin up an isolated preview environment for the current branch.

novahelm preview                # Start preview for current branch
novahelm preview --branch feat  # Start preview for a specific branch
novahelm preview --down         # Tear down the preview environment

Domain Management

novahelm domain add <hostname>

Create a DNS record pointing to your server. On first run, prompts for DNS provider and API token.

novahelm domain add app.example.com                   # A record -> server IP (auto-detected)
novahelm domain add app.example.com --proxy           # Enable Cloudflare CDN proxy
novahelm domain add app.example.com --content 1.2.3.4 # Explicit IP
novahelm domain add mail.example.com --type CNAME --content mailserver.example.com
novahelm domain add app.example.com --provider cloudflare --token cf_xxx  # Non-interactive

What it does:

1. Creates the DNS record via Cloudflare or Vercel API
2. Updates APP_URL in .env.production
3. Updates Coolify FQDN if configured

novahelm domain remove <hostname>

Remove a DNS record.

novahelm domain remove old.example.com
novahelm domain remove old.example.com --force    # Skip confirmation

novahelm domain list

List all DNS records for your domain.

novahelm domain list
novahelm domain list --json

novahelm domain check [hostname]

Verify DNS propagation. Defaults to the APP_URL hostname. Compares resolved IP against your server IP.

novahelm domain check
novahelm domain check app.example.com

novahelm domain proxy <hostname>

Toggle Cloudflare CDN proxy (orange cloud) on a DNS record. Cloudflare only.

novahelm domain proxy app.example.com --on     # Enable CDN + DDoS protection
novahelm domain proxy app.example.com --off    # DNS only

Infrastructure

novahelm infra create

Provision a Hetzner Cloud server and automatically set it up for NovaHelm (Docker, Coolify, firewall, novahelm user).

novahelm infra create                                      # Interactive wizard
novahelm infra create --token hc_xxx --server-type cx32    # Non-interactive
novahelm infra create --skip-coolify                       # Docker only, no Coolify
novahelm infra create --skip-init                          # Provision server only, skip setup

Options:

| Flag | Description | |------|-------------| | --token <token> | Hetzner API token (or HETZNER_TOKEN env var) | | --server-type <type> | Server type (e.g. cx22, cx32, cx42) | | --location <loc> | Datacenter location (e.g. fsn1, nbg1, hel1, ash) | | --name <name> | Server name (default: novahelm-production) | | --key <path> | SSH private key path | | --skip-init | Skip Docker/Coolify install after provisioning | | --skip-coolify | Install Docker only, skip Coolify |

What it does:

1. Validates your Hetzner API token
2. Selects server type and datacenter location (interactive or via flags)
3. Detects and uploads your SSH key to Hetzner
4. Creates a firewall (ports 22, 80, 443, 3000, 3001, 8000)
5. Provisions the server (Ubuntu 24.04)
6. Saves server metadata to .novahelm/infra.json (persists across terminal sessions)
7. Waits for the server to boot and SSH to become available
8. Installs Docker, Coolify (waits for readiness), configures ufw, creates novahelm user (unless --skip-init)

Getting a Hetzner API token:

1. Go to Hetzner Cloud Console
2. Select your project (or create one)
3. Go to Security > API Tokens > Generate API Token
4. Select Read & Write permissions

novahelm infra scaffold

Generate Docker infrastructure files for your project (Dockerfiles, Compose, env template, init SQL, Coolify deploy script).

novahelm infra scaffold

Creates:

infrastructure/
  docker/
    Dockerfile.web
    Dockerfile.jobs
    Dockerfile.realtime
    docker-compose.prod.yml
    .env.production.example
    .dockerignore
    postgres/
      init.sql
  coolify/
    deploy.sh

novahelm infra init

Bootstrap a fresh VPS with Docker and Coolify (interactive wizard).

novahelm infra init
novahelm infra init --ip 203.0.113.10 --key ~/.ssh/deploy_key
novahelm infra init --skip-coolify

What it does:

1. Tests SSH connectivity
2. Checks server requirements (OS, RAM, disk, Docker)
3. Installs Docker (if needed)
4. Installs Coolify (unless --skip-coolify)
5. Configures firewall (ports 22, 80, 443, 3000, 3001, 8000)
6. Creates a novahelm system user

novahelm infra setup

Configure Coolify for your NovaHelm app. Automatically creates the Coolify application if no UUID is set.

novahelm infra setup
novahelm infra setup --domain app.example.com
novahelm infra setup --skip-app-create

Options:

| Flag | Description | |------|-------------| | --domain <domain> | Domain name for your app | | --skip-app-create | Skip automatic app creation even if no UUID is set |

What it does:

1. Prompts for Coolify URL and API token (auto-suggests URL from .novahelm/infra.json if available)
2. Tests Coolify API connectivity
3. If no COOLIFY_APP_UUID is found, creates a new Coolify application:
   • Selects a server (auto-selects if only one)
   • Selects or creates a Coolify project
   • Detects your Git remote and branch
   • Chooses build pack (defaults to "dockerfile" if Dockerfile.web exists)
   • Creates the app and receives the UUID
4. Saves COOLIFY_URL, COOLIFY_TOKEN, and COOLIFY_APP_UUID to .env.production
5. Prompts for domain name, sets APP_URL and configures FQDN on Coolify (SSL via Let's Encrypt)
6. Pushes env vars from .env.production to Coolify

novahelm promote

Deploy the version running on one environment to another.

novahelm promote <source> <target>
novahelm promote staging production
novahelm promote staging production --dry-run
novahelm promote staging production --skip-build
novahelm promote staging production -y  # skip confirmation

novahelm instance delete

Destroy an environment's server and remove its config.

novahelm instance delete <id>
novahelm instance delete staging
novahelm instance delete staging -y  # skip confirmation

novahelm update

Update NovaHelm packages to the latest version.

novahelm update

Autopilot

novahelm autopilot

Autonomous AI development pipeline — dispatches AI-ready tickets, reviews open PRs, and merges approved work via a director-worker loop. Subcommands: dispatch, review, merge, full, hotfix, release, fix-ci, status.

The CLI auto-detects whether it's running inside an active Claude Code session (CLAUDECODE=1) and dispatches accordingly:

• In-session (default for interactive use): prints a /novahelm-autopilot-director ... slash invocation for the operator to paste into the active chat. The director runs in the active session under the Max plan auth — no subprocess, no auto-loaded-context rate-limit pressure.
• Headless (CLAUDECODE unset): spawns claude -p via the legacy subprocess path. Used in cron, CI, and the cloud agent host.
• Explicit opt-in via --in-session (AUTOPILOT-INSESSION-2): supported on dispatch, review, merge, and full. Forces the print-and-copy path even when CLAUDECODE is unset — use this from a regular Mac Terminal that isn't IDE-integrated but where you intend to paste the slash into an active Claude Code chat. Replaces the CLAUDECODE=1 novahelm autopilot ... env-var dance.

# Interactive (in-session): prints slash to paste
novahelm autopilot dispatch
novahelm autopilot full

# Headless (CI / cron): subprocess
CLAUDECODE= novahelm autopilot dispatch

# Regular terminal, opting into print-and-copy explicitly
novahelm autopilot dispatch --in-session
novahelm autopilot full --in-session

See CLAUDE.md "Autopilot pipeline (director-worker)" and the spec at docs/superpowers/specs/2026-05-09-autopilot-director-worker-design.md for the full pipeline shape.

Quick Start: Zero to Production

# 1. Create project
novahelm new my-app && cd my-app

# 2. Set up environment
novahelm env init

# 3. Generate infrastructure files
novahelm infra scaffold

# 4. Provision a server (Hetzner) — or use an existing VPS
novahelm infra create                           # Provisions + sets up a Hetzner server
# OR: novahelm infra init --ip <your-vps-ip>   # Set up an existing server
novahelm infra setup --domain my-app.com

# 5. Configure DNS
novahelm domain add app.my-app.com

# 6. Deploy
novahelm deploy

# 7. Monitor
novahelm status
novahelm logs

Configuration

All commands look for a novahelm.config.ts at the project root to identify a NovaHelm project. Deploy commands use environment files (.env.production, .env) for configuration.

Deploy Targets

| Target | How it's detected | What happens | |--------|------------------|--------------| | Compose (default) | No Coolify vars set | Builds images locally, runs docker compose up -d | | Coolify | COOLIFY_URL + COOLIFY_TOKEN + COOLIFY_APP_UUID all set | Triggers a deploy via Coolify API |

Set the three Coolify env vars in your .env.production to enable Coolify as your deploy target, or pass --target explicitly.