joblet

RNX CLI Reference

Complete reference for the RNX command-line interface, including all commands, options, and examples.

Table of Contents

• Global Options
• Job Commands
  • run
  • list
  • status
  • log
  • stop
• Volume Commands
  • volume create
  • volume list
  • volume remove
• Network Commands
  • network create
  • network list
  • network remove
• Runtime Commands
  • runtime list
  • runtime info
  • runtime test
• System Commands
  • monitor
  • nodes
  • help

Global Options

Options available for all commands:

--config <path>    # Path to configuration file (default: searches standard locations)
--node <name>      # Node name from configuration (default: "default")
--help, -h         # Show help for command
--version, -v      # Show version information

Configuration File Locations

RNX searches for configuration in this order:

1. ./rnx-config.yml
2. ./config/rnx-config.yml
3. ~/.rnx/rnx-config.yml
4. /etc/joblet/rnx-config.yml
5. /opt/joblet/config/rnx-config.yml

Job Commands

rnx run

Execute a command on the Joblet server.

rnx run [flags] <command> [args...]

Flags

Flag	Description	Default
--max-cpu	Maximum CPU usage percentage (0-10000)	0 (unlimited)
--max-memory	Maximum memory in MB	0 (unlimited)
--max-iobps	Maximum I/O bytes per second	0 (unlimited)
--cpu-cores	CPU cores to use (e.g., “0-3” or “1,3,5”)	”” (all cores)
--network	Network mode: bridge, isolated, none, or custom	“bridge”
--volume	Volume to mount (can be specified multiple times)	none
--upload	Upload file to workspace (can be specified multiple times)	none
--upload-dir	Upload directory to workspace	none
--env, -e	Environment variable (KEY=VALUE, visible in logs)	none
--secret-env, -s	Secret environment variable (KEY=VALUE, hidden from logs)	none
--schedule	Schedule job execution (duration or RFC3339 time)	immediate
--workflow	YAML workflow file for workflow execution	none

Examples

# Simple command
rnx run echo "Hello, World!"

# With resource limits
rnx run --max-cpu=50 --max-memory=512 --max-iobps=10485760 \
  python3 intensive_script.py

# CPU core binding
rnx run --cpu-cores="0-3" stress-ng --cpu 4 --timeout 60s

# Multiple volumes
rnx run --volume=data --volume=config \
  python3 process.py

# Environment variables (regular - visible in logs)
rnx run --env="NODE_ENV=production" --env="PORT=8080" \
  node app.js

# Secret environment variables (hidden from logs)
rnx run --secret-env="API_KEY=dummy_api_key_123" --secret-env="DB_PASSWORD=secret" \
  python app.py

# Mixed environment variables
rnx run --env="DEBUG=true" --secret-env="SECRET_KEY=mysecret" \
  python app.py


# File upload
rnx run --upload=script.py --upload=data.csv \
  python3 script.py data.csv

# Directory upload
rnx run --upload-dir=./project \
  npm start

# Scheduled execution
rnx run --schedule="30min" backup.sh
rnx run --schedule="2025-08-03T15:00:00" maintenance.sh

# Custom network
rnx run --network=isolated ping google.com

# Workflow execution
rnx run --workflow=ml-pipeline.yaml           # Execute full workflow
rnx run --workflow=jobs.yaml:ml-analysis      # Execute specific job from workflow

# Complex example
rnx run \
  --max-cpu=200 \
  --max-memory=2048 \
  --cpu-cores="0,2,4,6" \
  --network=mynet \
  --volume=persistent-data \
  --env=PYTHONPATH=/app \
  --upload-dir=./src \
  --workdir=/work/src \
  python3 main.py --process-data

Workflow Validation

When using --workflow, Joblet performs comprehensive pre-execution validation:

$ rnx run --workflow=my-workflow.yaml
🔍 Validating workflow prerequisites...
✅ No circular dependencies found
✅ All required volumes exist
✅ All required networks exist
✅ All required runtimes exist
✅ All job dependencies are valid
🎉 Workflow validation completed successfully!

Validation Checks:

• Circular Dependencies: Prevents infinite dependency loops
• Network Validation: Confirms all specified networks exist (built-in: none, isolated, bridge + custom networks)
• Volume Validation: Verifies all referenced volumes are available
• Runtime Validation: Checks runtime availability with name normalization
• Job Dependencies: Ensures all dependencies reference existing jobs

Error Example:

Error: workflow validation failed: network validation failed: missing networks: [non-existent-network]. Available networks: [bridge isolated none custom-net]

rnx list

List all jobs on the server.

rnx list [flags]

Flags

Flag	Description	Default
--json	Output in JSON format	false

Output Format

Table Format (default):

• ID: Job identifier
• NAME: Job name (from workflows, “-“ for individual jobs)
• STATUS: Current job status (RUNNING, COMPLETED, FAILED, STOPPED, SCHEDULED)
• START TIME: When the job started (format: YYYY-MM-DD HH:MM:SS)
• COMMAND: The command being executed (truncated to 80 chars if too long)

JSON Format: Outputs a JSON array with detailed job information including all resource limits, volumes, network, and scheduling information.

Examples

# List all jobs (table format)
rnx list

# Example output:
# ID   NAME         STATUS      START TIME           COMMAND
# ---- ------------ ----------  -------------------  -------
# 1    setup-data   COMPLETED   2025-08-03 10:15:32  echo "Hello World"
# 2    process-data RUNNING     2025-08-03 10:16:45  python3 script.py
# 3    -            FAILED      2025-08-03 10:17:20  invalid_command
# 4    -            SCHEDULED   N/A                  backup.sh

# JSON output for scripting
rnx list --json

# Example JSON output:
# [
#   {
#     "id": "1",
#     "name": "setup-data",
#     "status": "COMPLETED",
#     "start_time": "2025-08-03T10:15:32Z",
#     "end_time": "2025-08-03T10:15:33Z",
#     "command": "echo",
#     "args": ["Hello World"],
#     "exit_code": 0
#   },
#   {
#     "id": "2",
#     "name": "process-data",
#     "status": "RUNNING",
#     "start_time": "2025-08-03T10:16:45Z",
#     "command": "python3",
#     "args": ["script.py"],
#     "max_cpu": 100,
#     "max_memory": 512,
#     "cpu_cores": "0-3",
#     "scheduled_time": "2025-08-03T15:00:00Z"
#   }
# ]

# Filter with jq
rnx list --json | jq '.[] | select(.status == "FAILED")'
rnx list --json | jq '.[] | select(.max_memory > 1024)'

rnx status

Get detailed status of a specific job or workflow (unified command).

rnx status [flags] <id>

The status command automatically detects whether the ID refers to a job or workflow:

• Job IDs: String identifiers (e.g., “42”, “abc-123”)
• Workflow IDs: Numeric identifiers (e.g., 1, 2, 3)

Workflow Status Features:

• Displays job names, dependencies, status, and exit codes in a tabular format
• Shows dependency relationships between workflow jobs
• Real-time progress tracking with job-level details
• Color-coded status indicators (RUNNING, COMPLETED, FAILED, etc.)
• Job ID Display: Started jobs show actual job IDs (e.g., “42”, “43”), non-started jobs show “0”

Flags

Flag	Description	Default
--workflow	Explicitly get workflow status	false
--json	Output in JSON format	false

Examples

# Get job status (human-readable format)
rnx status 42

# Get workflow status (automatic detection)
rnx status 1

# Explicitly get workflow status  
rnx status --workflow 5

# Get status in JSON format (works for both jobs and workflows)
rnx status --json 42    # Job JSON output
rnx status --json 1     # Workflow JSON output

# Check multiple jobs/workflows
for id in 1 2 3; do rnx status $id; done

# JSON output for scripting
rnx status --json 42 | jq .status      # Job status
rnx status --json 1 | jq .total_jobs   # Workflow progress

# Example workflow status output:
# Workflow ID: 1
# Workflow: data-pipeline.yaml
# Status: RUNNING
# Progress: 2/4 jobs completed
# 
# Jobs in Workflow:
# -----------------------------------------------------------------------------------------
# JOB ID          JOB NAME             STATUS       EXIT CODE  DEPENDENCIES        
# -----------------------------------------------------------------------------------------
# 42              setup-data           COMPLETED    0          -                   
# 43              process-data         COMPLETED    0          setup-data          
# 0               validate-results     PENDING      -          process-data        
# 0               generate-report      PENDING      -          validate-results    

# Example JSON output for individual job:
# {
#   "id": "42",
#   "name": "process-data",
#   "command": "python3",
#   "args": ["process_data.py"],
#   "maxCPU": 100,
#   "cpuCores": "0-3",
#   "maxMemory": 512,
#   "maxIOBPS": 0,
#   "status": "COMPLETED",
#   "startTime": "2025-08-03T10:15:32Z",
#   "endTime": "2025-08-03T10:18:45Z",
#   "exitCode": 0,
#   "scheduledTime": ""
# }

Output includes:

• Job ID and command
• Current status
• Start/end times
• Resource limits
• Exit code (if completed)
• Scheduling information

rnx log

View or stream job logs.

rnx log [flags] <job-id>

Flags

Flag	Description	Default
--follow, -f	Stream logs in real-time	false
--tail	Number of lines to show from end	all
--timestamps	Show timestamps	false

Examples

# View complete logs
rnx log 42

# Stream logs in real-time
rnx log -f 42

# Show last 100 lines
rnx log --tail=100 42

# With timestamps
rnx log --timestamps 42

rnx stop

Stop a running or scheduled job.

rnx stop <job-id>

Examples

# Stop a running job
rnx stop 42

# Stop multiple jobs
rnx list --json | jq -r '.[] | select(.status == "RUNNING") | .id' | xargs -I {} rnx stop {}

Volume Commands

rnx volume create

Create a new volume for persistent storage.

rnx volume create <name> [flags]

Flags

Flag	Description	Default
--size	Volume size (e.g., 1GB, 500MB)	required
--type	Volume type: filesystem or memory	“filesystem”

Examples

# Create 1GB filesystem volume
rnx volume create mydata --size=1GB

# Create 512MB memory volume (tmpfs)
rnx volume create cache --size=512MB --type=memory

# Create volumes for different purposes
rnx volume create db-data --size=10GB --type=filesystem
rnx volume create temp-processing --size=2GB --type=memory

rnx volume list

List all volumes.

rnx volume list [flags]

Flags

Flag	Description	Default
--json	Output in JSON format	false

Examples

# List all volumes
rnx volume list

# JSON output
rnx volume list --json

# Check volume usage
rnx volume list --json | jq '.[] | select(.size_used > .size_total * 0.8)'

rnx volume remove

Remove a volume.

rnx volume remove <name>

Examples

# Remove single volume
rnx volume remove mydata

# Remove all volumes (careful!)
rnx volume list --json | jq -r '.[].name' | xargs -I {} rnx volume remove {}

Network Commands

rnx network create

Create a custom network.

rnx network create <name> [flags]

Flags

Flag	Description	Default
--cidr	Network CIDR (e.g., 10.10.0.0/24)	required

Examples

# Create basic network
rnx network create mynet --cidr=10.10.0.0/24

# Create multiple networks for different environments
rnx network create dev --cidr=10.10.0.0/24
rnx network create test --cidr=10.20.0.0/24
rnx network create prod --cidr=10.30.0.0/24

rnx network list

List all networks.

rnx network list [flags]

Flags

Flag	Description	Default
--json	Output in JSON format	false

Examples

# List all networks
rnx network list

# JSON output
rnx network list --json

rnx network remove

Remove a custom network. Built-in networks cannot be removed.

rnx network remove <name>

Examples

# Remove network
rnx network remove mynet

# Remove all custom networks (keep built-in networks)
rnx network list --json | jq -r '.networks[] | select(.builtin == false) | .name' | xargs -I {} rnx network remove {}

Runtime Commands

rnx runtime list

List all available runtime environments.

rnx runtime list [flags]

Flags

Flag	Description	Default
--json	Output in JSON format	false

Examples

# List all runtimes
rnx runtime list

# JSON output
rnx runtime list --json

rnx runtime info

Get detailed information about a specific runtime environment.

rnx runtime info <runtime-spec>

Examples

# Get runtime details
rnx runtime info python:3.11-ml
rnx runtime info java:17
rnx runtime info nodejs:18

rnx runtime test

Test a runtime environment to verify it’s working correctly.

rnx runtime test <runtime-spec>

Examples

# Test runtime functionality
rnx runtime test python:3.11-ml
rnx runtime test java:17

System Commands

rnx monitor

Monitor system metrics in real-time.

rnx monitor [subcommand] [flags]

Subcommands

• status - Show current system status
• (default) - Stream real-time metrics

Flags

Flag	Description	Default
--interval	Update interval in seconds	2
--json	Output in JSON format	false

Examples

# Real-time monitoring
rnx monitor

# Update every 5 seconds
rnx monitor --interval=5

# Get current status
rnx monitor status

# JSON output for metrics collection
rnx monitor status --json

# Continuous JSON stream
rnx monitor --json --interval=10

rnx nodes

List configured nodes from the client configuration file.

rnx nodes [flags]

Flags

Flag	Description	Default
--json	Output in JSON format	false

Examples

# List all nodes
rnx nodes

# JSON output
rnx nodes --json

# Use specific node for commands
rnx --node=production list
rnx --node=staging run echo "test"

rnx help

Show help information.

rnx help [command]

Examples

# General help
rnx help

# Command-specific help
rnx help run
rnx help volume create

# Show configuration help
rnx help config

Advanced Usage

Scripting with RNX

#!/bin/bash
# Batch processing script

# Process files in parallel with resource limits
for file in *.csv; do
  rnx run \
    --max-cpu=100 \
    --max-memory=1024 \
    --upload="$file" \
    python3 process.py "$file" &
done

# Wait for all jobs
wait

# Collect results
rnx list --json | jq -r '.[] | select(.status == "COMPLETED") | .id' | \
while read job_id; do
  rnx log "$job_id" > "result-$job_id.txt"
done

CI/CD Integration

# GitHub Actions example
- name: Run tests in Joblet
  run: |
    rnx run \
      --max-cpu=400 \
      --max-memory=4096 \
      --volume=test-results \
      --upload-dir=. \
      --env=CI=true \
      npm test

    # Check job status
    JOB_ID=$(rnx list --json | jq -r '.[-1].id')
    rnx status $JOB_ID

    # Get test results
    rnx run --volume=test-results cat /volumes/test-results/report.xml

Monitoring and Alerting

# Monitor job failures
while true; do
  FAILED=$(rnx list --json | jq '[.[] | select(.status == "FAILED")] | length')
  if [ $FAILED -gt 0 ]; then
    echo "Alert: $FAILED failed jobs detected"
    rnx list --json | jq '.[] | select(.status == "FAILED")'
  fi
  sleep 60
done

Configuration Examples

Multi-node Configuration

version: "3.0"
nodes:
  default:
    address: "prod-server:50051"
    cert: |
      -----BEGIN CERTIFICATE-----
      ...
    key: |
      -----BEGIN PRIVATE KEY-----
      ...
    ca: |
      -----BEGIN CERTIFICATE-----
      ...

  staging:
    address: "staging-server:50051"
    cert: |
      -----BEGIN CERTIFICATE-----
      ...
    # ... rest of credentials

  viewer:
    address: "prod-server:50051"
    cert: |
      -----BEGIN CERTIFICATE-----
      # Viewer certificate with OU=viewer
      ...
    # ... rest of credentials

Usage with Different Nodes

# Production jobs
rnx --node=default run production-task.sh

# Staging tests
rnx --node=staging run test-suite.sh

# Read-only access
rnx --node=viewer list
rnx --node=viewer monitor status

Best Practices

1. Resource Limits: Always set appropriate resource limits for production jobs
2. Volumes: Use filesystem volumes for persistent data, memory volumes for temporary data
3. Networks: Create isolated networks for security-sensitive workloads
4. Monitoring: Use rnx monitor to track resource usage
5. Scheduling: Use ISO 8601 format for precise scheduling
6. Error Handling: Check exit codes and logs for job failures
7. Cleanup: Remove unused volumes and networks regularly

Troubleshooting

See Troubleshooting Guide for common issues and solutions.

This site is open source. Improve this page.