Node CLI

CLI tool for managing operator registry nodes. This tool helps you create, validate, and push operators to the registry.

Installation

cd tools/node-cli
npm install
npm run build   # compile the TypeScript sources to dist/

Tip: rerun npm run build whenever you change the CLI source before invoking node-cli.

Usage

Init - Create Operator Structure

Creates a folder structure template for a new operator:

node-cli init <operator-name> [options]

Options:

• -d, --dir <directory> - Target directory (default: current directory)

Example:

node-cli init myoperator
# Creates: ./myoperator/
#   - lib/
#   - meta.json

During initialization the CLI will prompt you for key metadata (name, version, description, authors, tags, OS, architecture, entrypoint). Defaults are provided so you can hit enter to accept them.

Validate - Validate Operator

Validates the meta.json and folder structure:

node-cli validate <operator-path>

Example:

node-cli validate operator_registry_nodes/myoperator
# or
node-cli validate ./myoperator

Checks:

• Folder structure (lib/ directory exists)
• meta.json exists and is valid JSON
• All required fields in meta.json
• Data type specifications
• Parameter definitions
• Signal definitions
• Entrypoint library exists

Push - Push to Registry

Validates, packages, and pushes operator to registry:

node-cli push <operator-path> [options]

Options:

• -r, --registry <url> - Registry URL (or set OPERATOR_REGISTRY_URL env var)
• -t, --token <token> - Authentication token (or set OPERATOR_REGISTRY_TOKEN env var)

Example:

node-cli push operator_registry_nodes/myoperator --registry https://registry.example.com/api/operators --token your-token

Process:

1. Validates the operator (same as validate command)
2. Creates a tar.gz archive: {operator-name}-{version}.tar.gz
3. Uploads to registry via POST request
4. Cleans up temporary archive

Environment Variables

• OPERATOR_REGISTRY_URL - Default registry URL
• OPERATOR_REGISTRY_TOKEN - Default authentication token

Operator Structure

operator_registry_nodes/
└── myoperator/
    ├── lib/
    │   └── libmyoperator.dylib  # Your shared library
    └── meta.json                 # Operator metadata

Meta.json Validation

The validator checks:

Required Fields

• name - Must be lowercase, start with letter, alphanumeric + underscores
• version - Semantic versioning (e.g., "1.0.0")
• description - Human-readable description
• authors - Non-empty array
• created_at - YYYY-MM-DD format
• tags - Array of strings
• os - One of: darwin, linux, windows
• arch - One of: arm64, x64, x86
• entrypoint - Library filename (must match OS)
• input_types - Array of data type definitions
• output_types - Array of data type definitions
• parameters - Array of parameter definitions
• signals - Array of signal definitions

Data Types

• "any" - Accepts any data type
• number - Requires subtype: integer, double, or float
• string - Text values
• boolean - True/false
• array - Requires items field
• object - Requires properties array
• enum - Requires subtype, options, and optionally number_subtype

Parameters

• Must have name and type
• required - Boolean (default: false)
• depends_on - Conditional requirement
  • parameter - Name of parameter to depend on
  • equals - Value must equal
  • in - Value must be in array

Signals

• Must have name and description
• parameters - Array of signal parameters
• standard - Boolean indicating standard signal

Examples

Create a new operator

# 1. Create structure
node-cli init myfilter

# 2. Copy your shared library
cp build/libmyfilter.dylib myfilter/lib/

# 3. Edit meta.json with your operator details

# 4. Validate
node-cli validate myfilter

# 5. Push to registry
node-cli push myfilter \
  --registry https://registry.example.com/api/operators \
  --token your-auth-token

Error Handling

The CLI will:

• Exit with code 1 on validation errors
• Show detailed error messages
• Warn about missing files but allow validation to pass
• Clean up temporary files on push errors

See Also

• META_JSON_DOCUMENTATION.md - Complete meta.json schema documentation