@nodevisor/cli

The CLI provides four commands that drive your infrastructure workflow: setup, deploy, connect, and run. Each command takes a TypeScript cluster definition file and executes the corresponding operation.

Available as three binary names: nv, nodevisor, or nodevisor-cli.

Cluster Definition File

Every CLI command requires a cluster definition file — a TypeScript file that exports a cluster as its default export:

// .nodevisor/production.ts
import { DockerCluster, DockerNode, ClusterUser, NodeWeb, Traefik, Postgres } from 'nodevisor';

const cluster = new DockerCluster({
  name: 'production',
  nodes: [
    new DockerNode({ host: '10.0.0.1' }),
    new DockerNode({ host: '10.0.0.2' }),
  ],
  users: [
    new ClusterUser({
      username: 'root',
      privateKeyPath: '~/.ssh/nodevisor_id_ed25519',
    }),
  ],
});

cluster.addDependency(new Traefik({ ssl: { email: '[email protected]' } }));
cluster.addDependency(new Postgres({ database: 'app', username: 'app', password: process.env.DB_PASSWORD! }));
cluster.addDependency(new NodeWeb({ name: 'api', appDir: './apps/api', domains: ['api.example.com'], port: 3000 }));

export default cluster;

The CLI automatically loads .env files from the same directory as your cluster file, so environment variables like DB_PASSWORD are available without extra configuration.

If you pass a filename without a directory separator, the CLI first looks in the .nodevisor/ directory. So nv deploy production.ts resolves to .nodevisor/production.ts if it exists.

Commands

setup

Provision and secure your servers. Installs system packages, configures the firewall, sets up SSH keys, creates deploy users, and initializes Docker Swarm.

nv setup production.ts

Options

Generate keys and set up servers in one step:

nv setup production.ts --generate-keys

With a custom key path:

nv setup production.ts --generate-keys --identity ~/.ssh/my_deploy_key

deploy

Build images, push to your registry, and deploy all services to the cluster.

nv deploy production.ts

Options

Deploy only specific services:

nv deploy production.ts --service api --service worker

Skip building and deploy existing images:

nv deploy production.ts --no-build

Local development with Docker Compose:

nv deploy production.ts --local

connect

Open an SSH connection to the master node. Optionally forward all service ports to your local machine for debugging.

nv connect production.ts

Options

Connect and forward ports for local access to remote services:

nv connect production.ts --forward

run

Run a one-off service (like database migrations) on the cluster.

nv run production.ts --service migration

Options

Run a migration service:

nv run production.ts --service migration

Typical Workflow

# 1. First time: generate keys and provision servers
nv setup production.ts --generate-keys

# 2. Deploy your application
nv deploy production.ts

# 3. Run database migrations
nv run production.ts --service migration

# 4. Debug: connect and forward ports
nv connect production.ts --forward

# 5. Subsequent deploys
nv deploy production.ts

Related Packages

• nodevisor — Umbrella package with all modules
• @nodevisor/docker — DockerCluster used by CLI commands
• @nodevisor/cluster — Abstract cluster primitives