kx — Kree4JS CLI

kx is the command-line tool for managing Kree4JS Node.js nodes — start, stop, list, and snapshot instances.

Installation

npm install -g @kree4js/kx-cli

Or install locally alongside your project:

npm install @kree4js/kx-cli
npx kx start ...

This package depends on @kree4js/kree4n (peer dependency installed automatically when using npm 7+).

Data Directory

All instance metadata and snapshots live under ~/.kx/:

~/.kx/
├── instances/       # <nodeId>.json — one file per started instance
├── snapshots/       # <name>.json   — saved instance snapshots
└── configs/         # *.config.js   — auto-generated configs (from kx save)

Override the base directory with the KX_HOME environment variable (useful for testing).

Commands

kx start

Start a Kree4N node.

kx start -n <name> [-c <config>] [-l <url>] [-a <url>] [-f]

| Option | Alias | Type | Default | Description | |--------|-------|------|---------|-------------| | --name | -n | string | required | Node name (unique among running instances) | | --config | -c | string | — | Path to config file (ESM .js) | | --listen | -l | array | — | Listen URL, repeatable (-l tcp://0.0.0.0:9000) | | --attach | -a | array | — | Attach URL, repeatable | | --fork | -f | boolean | false | Fork to child process |

Two start modes:

| Mode | Behavior | Use case | |------|----------|----------| | In-process (default) | Runs in current process, blocks until SIGINT/SIGTERM. On shutdown, stops kree4n gracefully and cleans up the instance record. | PM2 / systemd / direct shell | | Fork (--fork) | Spawns a child process and exits immediately. Instance record is saved before exit. | Standalone CLI usage |

When the process exits (either mode), the instance record is automatically removed from ~/.kx/instances/.

Config-free start:

You can start a node without a config file by providing --listen and --attach directly:

kx start -n my-node -l tcp://0.0.0.0:9000 -l tcp://0.0.0.0:9001

Name collision detection:

If an instance with the same name is already running, start refuses with an error message. Use kx stop <name> first.

Config file format

A config file is an ES module exporting a default object:

// kree4n.config.js
export default {
  name: 'my-node',
  description: 'A Kree4N node',

  // URLs this node listens on
  listen: ['tcp://0.0.0.0:9000'],

  // URLs this node connects to
  attach: [],

  // Registered service implementations
  services: {},

  // KreeX runtime options
  options: {}
}

Generate one with kx init.

kx stop

Stop a running node.

kx stop [target]

target can be a node ID, node name, or omitted. When omitted, stops the instance whose cwd matches the current directory.

The command sends SIGTERM, waits up to 5 seconds for graceful shutdown, then sends SIGKILL if the process is still alive.

kx list

List all known instances with their status.

kx list

Output columns: NODE ID, NAME, PID, STATUS (running/dead), and first LISTEN URL. Dead instances (process no longer alive) are shown with - PID.

kx clean

Stop all running instances and remove all instance records.

kx clean [-f]

| Option | Alias | Type | Description | |--------|-------|------|-------------| | --force | -f | boolean | Skip the 5-second graceful-shutdown wait |

kx save

Save a snapshot of all currently running instances. For instances started without a config file, a config is auto-generated under ~/.kx/configs/.

kx save [-n <name>]

| Option | Alias | Type | Description | |--------|-------|------|-------------| | --name | -n | string | Snapshot name (default: snap-<timestamp>) |

kx restore

Restore instances from a snapshot.

kx restore [-n <name>] [-f]

| Option | Alias | Type | Default | Description | |--------|-------|------|---------|-------------| | --name | -n | string | latest | Snapshot name (omit for most recent) | | --fork | -f | boolean | false | Start each restored instance with --fork |

Each instance is launched as a separate kx start subprocess. If a working directory no longer exists, it is skipped with a warning.

In-process mode (default): restore blocks until each instance exits — suitable when PM2 manages the restored processes.

Fork mode (--fork): Each instance starts in the background and restore returns immediately.

kx init

Generate a default kree4n.config.js in the current directory.

kx init [-o <path>] [-f]

| Option | Alias | Type | Default | Description | |--------|-------|------|---------|-------------| | --output | -o | string | kree4n.config.js | Output file path | | --force | -f | boolean | — | Overwrite existing file |

kx ping

Verify connectivity to a Kree4N node by attaching a temporary client.

kx ping <url> [-t <ms>]

| Argument | Type | Default | Description | |----------|------|---------|-------------| | url | string | required | Target URL (e.g. tcp://127.0.0.1:9000) |

| Option | Alias | Type | Default | Description | |--------|-------|------|---------|-------------| | --timeout | -t | number | 5000 | Connection timeout in milliseconds |

kx info

Display framework and runtime information.

kx info

Shows kx-cli version, kree4n version, Node.js version, and current PID.

kx version

kx version

Prints kx v<version>.

PM2 Integration

kx is designed to work well with PM2. Since the default start mode runs in-process, PM2 manages the lifecycle directly.

Basic Usage

The -- separator passes arguments to kx rather than PM2:

pm2 start kx -- start -n my-node -c kree4n.config.js
pm2 start kx -- start -n another -l tcp://0.0.0.0:9001
pm2 save
pm2 startup

Production-Grade Configuration (Recommended)

Create an ecosystem.config.js for better manageability:

module.exports = {
  apps: [{
    name: 'kree4n-primary',
    script: 'kx',
    args: 'start -n primary -c /path/to/kree4n.config.js',
    instances: 1,
    autorestart: true,
    watch: false,
    max_memory_restart: '1G',
    env: {
      NODE_ENV: 'production'
    }
  }, {
    name: 'kree4n-secondary',
    script: 'kx',
    args: 'start -n secondary -l tcp://0.0.0.0:9001',
    instances: 1,
    autorestart: true,
    watch: false
  }]
}

Start with:

pm2 start ecosystem.config.js

Important Notes

• Arguments after -- are passed to kx, not PM2
• If using kx --fork, place it after the -- separator:

  pm2 start kx -- start -n my-node -c config.js --fork

• pm2 stop/restart/reload sends SIGTERM, which triggers graceful shutdown
• kx list shows all registered instances regardless of PM2 status

PM2 handles daemonization, log management, and auto-restart — kx handles instance metadata and graceful shutdown.

Use kx list to see registered instances and kx save to persist snapshots for later restoration.

Example Workflow

# Generate a config
kx init

# Start a node (blocking, in current terminal)
kx start -n my-node -c kree4n.config.js

# Or start in background with --fork
kx start -n my-node -c kree4n.config.js --fork

# List all instances
kx list

# Verify connectivity
kx ping tcp://127.0.0.1:9000

# Save a snapshot for later restoration
kx save -n production-setup

# Stop a node
kx stop my-node

# Restore from snapshot
kx restore -n production-setup

# Clean everything up
kx clean

# Check versions
kx info