All writing
7 min#nextdeploy#cli#devops#reference#go

NextDeploy CLI Complete Commands Reference: Workflow, Flags & Wire Protocols

The authoritative reference for every NextDeploy CLI command: init, prepare, build, ship, rollback, status, secrets, logs, creds, inspect, plan, and destroy.

The NextDeploy CLI (nextdeploy) is a compiled, single-binary deployment toolkit written in Go using the Cobra framework. It provides a deterministic, infrastructure-agnostic interface for deploying Next.js 15+ App Router applications across two target primitives: Linux VPS (systemd + Caddy + in-process Go sidecar) and Serverless Edges (Cloudflare Workers or AWS Lambda).

One declarative CLI. Zero Dockerfiles. Zero vendor lock-in. Reversible, release-pinned operations from init to destroy.

Global Architecture & Command Taxonomy

Commands in NextDeploy adhere to strict invariants: they are idempotent, report granular diagnostic phases, enforce cryptographic authentication over Unix sockets, and fail-closed prior to state mutations.

Diagram · System Flow
Rendering diagram...

1. Lifecycle & Release Pipeline

nextdeploy init

Scaffolds the minimal nextdeploy.yml manifest at your repository root. Inspects package.json to verify the next dependency and seed app name and version:

bash
nextdeploy init
  • Safe Guard: Re-running init on an existing nextdeploy.yml is a safe no-op that prevents accidental overwrites.
  • Interactive Prompts: Prompts for deployment target (vps or serverless) and provider (Cloudflare or AWS).
  • Slug Normalization: Automatically sanitizes app name into a strict regex slug (^[a-z0-9-]+$, 3–63 characters).

    • nextdeploy prepare

    Provisions fresh Linux VPS target(s) with runtime dependencies, security hardening, and the nextdeployd control plane. Default mode is agent mode: downloads the latest static nextdeployd binary directly to the server, eliminating Python and Ansible prerequisites on the local machine:

    bash· 14 lines
    1# Provision default server in agent mode
2nextdeploy prepare
3
4# Provision all configured servers in parallel
5nextdeploy prepare --all
6
7# Provision a specific server by name
8nextdeploy prepare --server production-01
9
10# Advanced flags
11nextdeploy prepare --skip-runtimes    # Skip Node.js 22 / Corepack installation
12nextdeploy prepare --skip-hardening   # Skip Fail2Ban jails and logrotate
13nextdeploy prepare --allow-root       # Allow provisioning over root SSH session
14nextdeploy prepare --timeout 15m      # Custom SSH provisioning timeout (default: 10m)
  • Node.js 22 & Corepack: Configures Node.js 22 via NodeSource signed repository and symlinks to /usr/local/bin.
  • Edge Ingress: Compiles Caddy with Coraza WAF (coraza-caddy/v2) and seeds fail2ban jails (caddy-auth, caddy-waf).
  • Filesystem Bounds: Creates /opt/nextdeploy/{apps,uploads,tmp} with 0750 permissions owned by nextdeploy:nextdeploy.
  • HMAC Security: Generates random 32-byte HMAC-SHA256 secret at /etc/nextdeployd/config.json (0600 root).

    • nextdeploy build

    Executes the buildflow.Run pipeline. Inspects your Next.js application, generates deployment metadata, and packages the deployable release tarball:

    bash· 5 lines
    1# Incremental build (skips next build if git commit and config hash match)
2nextdeploy build
3
4# Force full rebuild ignoring cache locks
5nextdeploy build --force
  • Incremental Gate: Compares .nextdeploy/build.lock against the current git commit SHA and nextdeploy.yml hash. If unchanged, next build is bypassed while release metadata and tarball are fresh-minted.
  • Metadata Extraction: Parses next.config and .next manifests into .nextdeploy/metadata.json (NextCorePayload) consumed by the daemon.
  • VPS Tarball: For VPS standalone mode, consolidates standalone server.js, public/, .next/static/, and metadata into app.tar.gz.

    • nextdeploy ship (alias: deploy)

    Uploads the packaged build and triggers release activation on the target environment:

    bash· 11 lines
    1# Ship to default production target
2nextdeploy ship
3
4# Ship with forced rebuild
5nextdeploy ship --force
6
7# Ship to isolated named environment
8nextdeploy ship -e staging
9
10# Verbose execution trace
11nextdeploy ship -v
  • Git Cleanliness: Checks git working tree and logs a warning if uncommitted changes exist.
  • DNS Guidance: Generates dns.md guide with exact A-records or CNAME mappings needed for edge routing.
  • SCP Transport: Uploads tarball over SSH to /opt/nextdeploy/uploads/nextdeploy_<app>_<timestamp>.tar.gz.
  • Daemon Activation: Executes sudo nextdeployd ship over Unix socket with HMAC-SHA256 signature and replay defense.

    • 2. Day-2 Operations & Observability

    nextdeploy status

    Queries the live state of the application across configured target servers or cloud providers:

    bash
    nextdeploy status
  • VPS Runtime: On VPS: Queries nextdeployd via socket to read systemctl show (ActiveState, MainPID, MemoryCurrent).
  • Edge Runtime: On Serverless: Queries Cloudflare/AWS APIs to return active worker deployment timestamp, script size, and health probe status.

    • nextdeploy logs

    Streams live production logs directly to your local terminal over SSH using journalctl without requiring third-party log forwarders:

    bash· 14 lines
    1# Stream application logs (journalctl -u nextdeploy-<app>-<release> -f -n 50)
2nextdeploy logs
3
4# Filter logs by specific route regex pattern
5nextdeploy logs --route /api/checkout
6
7# Inspect daemon audit log (who ran what command and HMAC status)
8nextdeploy logs --audit
9
10# Inspect daemon system log
11nextdeploy logs --daemon
12
13# Stream app, daemon, and audit streams concurrently
14nextdeploy logs --all

    nextdeploy rollback

    Instantly points live traffic to a previously deployed release without rebuilding or re-uploading:

    bash· 8 lines
    1# Revert one release step backwards
2nextdeploy rollback
3
4# Revert N releases backwards (up to 5 retained releases)
5nextdeploy rollback --steps 2
6
7# Roll back to a specific git commit SHA (full or short SHA)
8nextdeploy rollback --to 7c8350a0
  • Full Gate Parity: Reuses the full activateRelease sequence: starts candidate service, verifies two-stage health checks (<500 HTTP status), validates Caddy fragment in sandbox, and atomically flips the symlink.
  • Zero Risk: The previous service is retired only after candidate health is verified. Server never serves a broken rollback.

    • 3. Secrets & Credentials Management

    nextdeploy secrets

    Manages production environment variables stored securely on the VPS at /opt/nextdeploy/secrets/<app>.json (0600 root only):

    bash· 15 lines
    1# Set one or more secrets
2nextdeploy secrets set DATABASE_URL=postgres://user:pass@host:5432/db
3nextdeploy secrets set STRIPE_KEY=sk_live_... REDIS_URL=redis://...
4
5# Retrieve a single secret in plaintext
6nextdeploy secrets get DATABASE_URL
7
8# List all secret keys (values masked)
9nextdeploy secrets list
10
11# Delete a secret
12nextdeploy secrets unset STRIPE_KEY
13
14# Bulk load environment variables from a local file
15nextdeploy secrets load .env.production
    🔒
    Setting or unsetting secrets automatically re-renders .env.nextdeploy and performs a zero-downtime service restart — no git commit or redeployment required.

    nextdeploy creds

    Manages encrypted cloud provider credentials stored locally at ~/.nextdeploy/credstore (mode 0600):

    bash· 9 lines
    1# Interactively save provider credentials
2nextdeploy creds set --provider cloudflare
3nextdeploy creds set --provider aws
4
5# Inspect configured providers without revealing keys
6nextdeploy creds list
7
8# Clear provider credentials from local disk
9nextdeploy creds clear --provider aws

    4. Inspection, Infrastructure Diffing & Teardown

    nextdeploy inspect

    Performs a deep size audit of the .next/standalone bundle without side effects, identifying package offenders against the 250MB threshold:

    bash
    nextdeploy inspect

    nextdeploy plan & apply (Cloudflare)

    Terraform-style dry-run for declarative Cloudflare resources declared under serverless.cloudflare.resources (R2 buckets, D1 databases, KV namespaces):

    bash· 5 lines
    1# Preview planned resource creations, updates, and drift
2nextdeploy plan
3
4# Apply infrastructure changes
5nextdeploy apply

    nextdeploy generate-ci

    Emits an opinionated, production-ready GitHub Actions workflow file to .github/workflows/nextdeploy.yml that automates build and ship on push to main:

    bash· 5 lines
    1# Generate GitHub Actions CI/CD workflow
2nextdeploy generate-ci
3
4# Generate workflow for a specific named environment
5nextdeploy generate-ci --environment production
  • Automated CI: Configures Node.js setup, pnpm caching, and SSH agent configuration.
  • Secret Binding: Injects deployment secrets via GitHub Actions repository secrets (NEXTDEPLOY_SSH_KEY).

    • nextdeploy upgrade-daemon (alias: update-daemon)

    Pushes the latest nextdeployd binary to all configured VPS servers and restarts the systemd service non-destructively:

    bash
    nextdeploy upgrade-daemon

    nextdeploy destroy

    Permanently removes the application and all associated cloud/server resources:

    bash· 8 lines
    1# Interactive teardown (prompts for app slug confirmation)
2nextdeploy destroy
3
4# Force destroy overriding deletion_protection
5nextdeploy destroy --force
6
7# Non-interactive confirmation for CI/CD pipelines
8nextdeploy destroy --yes
  • Process Cleanup: Stops Go sidecar listener and retires all nextdeploy-<app>-*.service units.
  • Ingress Removal: Removes /etc/caddy/nextdeploy.d/<app>.caddy and executes systemctl reload caddy.
  • Filesystem Wipe: Removes /opt/nextdeploy/apps/<app>/ (all releases, current symlink, and shared static).
    • Disciplined CLI primitives enable autonomous infrastructure. Every command provides full visibility, deterministic outputs, and zero vendor lock-in.