Multi-environment management: switch, list, diff, copy.

nself env <subcommand> [flags] [args]

nself env manages multiple environments (dev, staging, prod) on a single project. Each environment gets its own Docker project name, network, volume namespace, and port range, so they can coexist on one host without conflicts.

env use <name> switches the active environment. After switching, run nself build so the generated docker-compose.yml and nginx config reflect the new environment's .env.<name> cascade. env list shows all environments with the active one marked. env show prints the resolved config for the current environment with secrets redacted. env diff a b compares two environments side-by-side. env copy from to scaffolds a new environment from an existing one as the starting template.

The active environment is stored in a project-local marker (.env.active or equivalent) so subsequent commands like nself start, nself logs, and nself db all target the right stack.

The env subcommands take no flags beyond positional arguments. Use --help on any subcommand to confirm.

# See which environments exist
nself env list

# Switch to staging and rebuild
nself env use staging
nself build

# Show the resolved config for the current environment
nself env show

# Compare dev and prod env configs
nself env diff dev prod

# Scaffold a new "qa" environment from staging
nself env copy staging qa
nself env use qa

Manage the multi-server inventory stored in .nself/control-plane.yaml.

nself env target <subcommand> [flags] [args]

nself env target manages a fleet of servers across environments. The inventory is persisted in .nself/control-plane.yaml (mode 0600). Each server entry records its role, SSH target, SSH key reference (env-var name only — never an inline key), remote installation path, and whether it is the primary app server.

The probe subcommand runs SSH + Docker checks against live servers and classifies each as manage (full control), read-only (SSH reachable but Docker unavailable), or hidden (SSH unreachable). A 60-second on-disk cache avoids repeated probe latency; use --refresh to bypass it.

The migrate subcommand is a one-time helper for teams that previously configured deployments via NSELF_DEPLOY_HOST_* environment variables. It synthesizes a control-plane.yaml from those variables without overwriting any existing manual entries.

• --key-ref accepts an env-var name only (e.g. NSELF_SSH_KEY_STAGING). Supplying a file path or inline key material is rejected on input.
• SSH probes use BatchMode=yes StrictHostKeyChecking=accept-new ForwardAgent=no. No interactive prompts, no agent forwarding.
• Secret values are never written to or read from the inventory file. list and probe output shows SSHKeyRef names, not values.
• All writes to control-plane.yaml use mode 0600.

# List all servers (table)
nself env target list

# List only staging servers, JSON output
nself env target list staging --json

# Add a primary app server to staging
nself env target add staging web1 \
  --host [email protected] \
  --role app \
  --key-ref NSELF_SSH_KEY_STAGING \
  --remote-path /opt/nself \
  --primary

# Add an LB server that routes to web1 and web2
nself env target add staging lb1 \
  --host [email protected] \
  --role lb \
  --key-ref NSELF_SSH_KEY_STAGING \
  --upstreams web1,web2

# Remove a server from staging
nself env target remove staging web1

# Probe all servers (capability matrix)
nself env target probe

# Probe only staging, JSON, bypassing cache
nself env target probe staging --json --refresh

# Probe one specific server
nself env target probe staging:web1

# Migrate legacy NSELF_DEPLOY_HOST_* env vars
nself env target migrate

ENV      SERVER  CAPABILITY  SSH  DOCKER  LATENCY  REASON
staging  web1    manage      ok   ok      42ms
staging  lb1     read-only   ok   -       38ms     docker socket permission denied
prod     db1     manage      ok   ok      91ms

[
  {
    "env": "staging",
    "server": "web1",
    "capability": "manage",
    "ssh_reachable": true,
    "docker_ok": true,
    "latency_ms": 42
  }
]

.nself/control-plane.yaml (mode 0600):

version: 1
environments:
  staging:
    name: staging
    kind: remote
    servers:
      - name: web1
        role: app
        host: [email protected]
        ssh_key_ref: NSELF_SSH_KEY_STAGING
        remote_path: /opt/nself
        primary: true
  prod:
    name: prod
    kind: remote
    servers:
      - name: web1
        role: app
        host: [email protected]
        ssh_key_ref: NSELF_SSH_KEY_PROD
        remote_path: /opt/nself
        primary: true

• cmd-build, regenerate compose for the active environment
• cmd-promote, promote one environment to another
• cmd-secrets, environment-scoped secrets
• Commands, full command index

← Commands | Home →