Nex CLI Guide

NEX CLI Guide

Installation

# From source
go install github.com/synadia-io/nex/cmd/nex@latest

# Or download binary from releases
# https://github.com/synadia-io/nex/releases

Global Flags

Configuration Precedence

Configuration is loaded in this order (later overrides earlier):

1. /etc/nex/config.json (system)
2. ~/.config/nex/config.json (user)
3. ./config.json (local)
4. Command-line flags (highest priority)

Configuration File Format

{
  "servers": "nats://localhost:4222",
  "namespace": "default",
  "timeout": "5s",
  "credentials": "/path/to/creds.creds"
}

Node Commands

nex node up

Start a NEX node (host that runs agents/workloads).

# Basic startup
nex -s nats://127.0.0.1:4222 node up

# With custom name and tags
nex node up \
  --node-name my-node \
  --tags "env=production;region=us-west" \
  --agents "native" \
  --show-workload-logs

# Production setup with persistence
nex node up \
  --node-name prod-node-01 \
  --tags "env=prod;region=us-east-1" \
  --state kv \
  --events nats,logs \
  --issuer-signing-key "SAABC..."

Flags:

nex node list

List all running NEX nodes.

# List all nodes
nex node list

# Filter by tags
nex node list --filter "nex.nexus=mynexus"
nex node list --filter "env=production"

# JSON output for scripting
nex node list --json

Flags:

nex node info

Get detailed information about a specific node.

# Basic info
nex node info <NODE_ID>

# Full info with agent details and workloads
nex node info <NODE_ID> --full

# JSON output
nex node info <NODE_ID> --json

Flags:

nex node lameduck

Graceful shutdown - stop accepting new workloads, allow existing to drain.

# Lame duck specific node
nex node lameduck --node-id <NODE_ID> --delay 2m

# Lame duck by tag (all matching nodes)
nex node lameduck --tag env=staging --delay 1m

Flags:

Workload Commands

nex workload start

Deploy a workload to the cluster.

# From Nexfile (recommended)
nex workload start -f Nexfile

# From Nexfile with placement tags
nex workload start -f Nexfile --tags "region=us-west"

# Inline definition (for scripting)
nex workload start \
  --type native \
  --lifecycle service \
  --name my-service \
  --start-request '{"uri":"file:///usr/local/bin/myapp","argv":["--config","/etc/app.yaml"]}'

Flags:

nex workload ls

List running workloads.

# List all workloads
nex workload ls

# With metadata
nex workload ls --show-metadata

# Filter by type
nex workload ls --type native

# JSON output
nex workload ls --json

Flags:

nex workload stop

Terminate a running workload.

nex workload stop <WORKLOAD_ID>

# With graceful timeout
nex workload stop <WORKLOAD_ID> --timeout 30s

nex workload info

Get detailed information about a workload.

nex workload info <WORKLOAD_ID>
nex workload info <WORKLOAD_ID> --json

nex workload clone

Duplicate a workload (re-auction to new capacity).

# Clone to additional capacity
nex workload clone <WORKLOAD_ID>

# Clone with different placement
nex workload clone <WORKLOAD_ID> --tags "region=canary"

# Clone and stop original (migration)
nex workload clone <WORKLOAD_ID> --stop

Flags:

Nexfile Format

The Nexfile defines a workload for deployment.

YAML Format (Recommended)

# Required fields
name: "my-workload"           # Human-readable name
type: native                  # Agent type
lifecycle: service            # service | job | function

# Start request (agent-specific)
start_request:
  uri: "file:///path/to/binary"
  argv:
    - "--config"
    - "/etc/app.yaml"
  environment:
    LOG_LEVEL: "debug"
    DATABASE_URL: "postgres://..."
  workdir: "/app"

# Optional metadata
description: "My awesome service"
tags:
  region: "us-west"
  env: "production"
  team: "platform"

JSON Format

{
  "name": "my-workload",
  "type": "native",
  "lifecycle": "service",
  "description": "My awesome service",
  "tags": {
    "region": "us-west",
    "env": "production"
  },
  "start_request": {
    "uri": "file:///path/to/binary",
    "argv": ["--config", "/etc/app.yaml"],
    "environment": {
      "LOG_LEVEL": "debug"
    },
    "workdir": "/app"
  }
}

Lifecycle Types

Service (Long-Running)

name: "api-server"
type: native
lifecycle: service
start_request:
  uri: "file:///usr/local/bin/api"
  argv: ["--port", "8080"]
  environment:
    PORT: "8080"

• Runs continuously
• Auto-restarts on failure
• Use for: API servers, stream processors, daemons

Job (Run-to-Completion)

name: "db-migration"
type: native
lifecycle: job
start_request:
  uri: "file:///usr/local/bin/migrate"
  argv: ["--dry-run=false"]

• Runs once to completion
• No auto-restart
• Use for: Batch tasks, migrations, backups

Function (Event-Triggered)

name: "webhook-handler"
type: native
lifecycle: function
start_request:
  uri: "file:///usr/local/bin/handler"
  # Trigger configured via NATS subject

• Invoked per-event
• Scales to zero when idle
• Use for: Webhooks, data transforms, event handlers

Environment Variables

Injected into Workloads

NEX automatically injects these environment variables:

Using Injected Credentials

// Go example
servers := os.Getenv("NEX_WORKLOAD_NATS_SERVERS")
jwt := os.Getenv("NEX_WORKLOAD_NATS_B64_JWT")
nkey := os.Getenv("NEX_WORKLOAD_NATS_NKEY")

nc, err := nats.Connect(servers, nats.UserJWTAndSeed(jwt, nkey))

// TypeScript example
const servers = process.env.NEX_WORKLOAD_NATS_SERVERS
const jwt = Buffer.from(process.env.NEX_WORKLOAD_NATS_B64_JWT!, 'base64').toString()
const nkey = process.env.NEX_WORKLOAD_NATS_NKEY

const nc = await connect({
  servers: servers?.split(','),
  authenticator: jwtAuthenticator(jwt, new TextEncoder().encode(nkey)),
})

Monitoring

Subscribe to Events

# All events
nats sub "$NEX.FEED.default.event.>"

# Specific event types
nats sub "$NEX.FEED.default.event.WorkloadStarted"
nats sub "$NEX.FEED.default.event.WorkloadStopped"

Subscribe to Logs

# All logs
nats sub "$NEX.FEED.default.logs.>"

# Specific workload
nats sub "$NEX.FEED.default.logs.<WORKLOAD_ID>.>"

# Only stdout
nats sub "$NEX.FEED.default.logs.<WORKLOAD_ID>.out"

# Only stderr
nats sub "$NEX.FEED.default.logs.<WORKLOAD_ID>.err"

Event Types

Examples

Deploy a Simple Service

# Create Nexfile
cat > Nexfile.yaml << 'EOF'
name: hello-service
type: native
lifecycle: service
start_request:
  uri: "file:///usr/local/bin/hello"
  environment:
    GREETING: "Hello from NEX!"
EOF

# Deploy
nex workload start -f Nexfile.yaml

# Check status
nex workload ls

# View logs
nats sub "$NEX.FEED.default.logs.>"

Deploy with Placement Constraints

# Deploy only to production nodes
nex workload start -f Nexfile.yaml --tags "env=production"

# Deploy to specific region
nex workload start -f Nexfile.yaml --tags "region=us-west-2"

Rolling Update

# Clone with new image/config (clone goes to different node)
nex workload clone <OLD_ID> --tags "version=v2"

# Verify new workload is healthy
nex workload info <NEW_ID>

# Stop old workload
nex workload stop <OLD_ID>

Batch Job

cat > migration.yaml << 'EOF'
name: db-migration-v42
type: native
lifecycle: job
start_request:
  uri: "file:///usr/local/bin/migrate"
  argv: ["--version", "42", "--apply"]
  environment:
    DATABASE_URL: "postgres://localhost/mydb"
EOF

nex workload start -f migration.yaml

# Watch for completion
nats sub "$NEX.FEED.default.event.WorkloadStopped"

Troubleshooting

Node Won't Start

# Check NATS connectivity
nats server check

# Run with verbose logging
nex -v node up

# Check for port conflicts
netstat -tlnp | grep 4222

Workload Won't Deploy

# Check available nodes
nex node list

# Verify node has matching tags
nex node info <NODE_ID> --full

# Check auction (verbose)
nex -v workload start -f Nexfile.yaml

Workload Keeps Restarting

# Check logs
nats sub "$NEX.FEED.default.logs.<WORKLOAD_ID>.err"

# Check events for failure reason
nats sub "$NEX.FEED.default.event.WorkloadStopped"

# Get workload info
nex workload info <WORKLOAD_ID>

Related Skills

• /nex-codebase-navigation - Source code exploration
• /nex-effect-services - Effect-TS integration patterns

References

• NEX GitHub
• NEX Documentation
• NATS CLI