CLI Reference

Complete reference documentation for Noid CLI commands and options.

Core Commands

noid create

Create a new microVM.

noid create <name> [OPTIONS]

Arguments:

• <name> - Name of the VM to create (required)

Options:

--vcpus <N>      Number of virtual CPUs (default: 1)
--memory <MB>    Memory in MB (default: 2048)

Examples:

# Basic VM creation
noid create my-vm

# VM with custom resources
noid create powerful-vm --vcpus 4 --memory 4096

# Minimal resources
noid create tiny-vm --vcpus 1 --memory 512

Notes:

• The server copies the base rootfs for each new VM
• Every VM gets its own independent filesystem
• VM is started automatically after creation
• With golden snapshot: creation takes 5-10 seconds
• Without golden snapshot (cold boot): 30-60 seconds

noid destroy

Destroy one or more VMs.

noid destroy <name>

Arguments:

• <name> - Name of VM to destroy (required)

Examples:

# Destroy single VM
noid destroy my-vm

# If you have multiple VMs, destroy each separately
noid destroy vm1
noid destroy vm2

Notes:

• Stops the VM if running
• Releases all resources
• Deletes VM and its data
• Checkpoints are typically preserved

noid list

List all VMs.

noid list

Output:

Displays information about all VMs including:

• VM name
• Status (running, stopped, etc.)
• Resource allocation (vCPUs, memory)
• IP address (if available)

Examples:

# List all VMs
noid list

noid exec

Execute a command inside a VM.

noid exec <name> [OPTIONS] -- <command> [args...]

Arguments:

• <name> - VM name (required, or omit if using noid use)
• <command> - Command to execute (required)
• [args...] - Command arguments

Options:

-e <KEY=VALUE>    Set environment variable (can be used multiple times)

Examples:

# Simple command
noid exec my-vm -- ls -la

# With environment variables
noid exec my-vm -e NODE_ENV=production -- node app.js
noid exec my-vm -e PATH=/custom/path -e HOME=/root -- env

# Pipe input
echo "test data" | noid exec my-vm -- cat

# Complex commands with shell
noid exec my-vm -- sh -c "ls | grep txt"

Notes:

• Automatic shell-escaping for special characters
• Environment variables exist only for that command's duration
• Returns the exit code of the executed command
• Safer than persistent shell exports for temporary variables

noid console

Attach to VM serial console.

noid console <name>

Arguments:

• <name> - VM name (required, or omit if using noid use)

Examples:

# Attach to console
noid console my-vm

Usage:

• Provides direct, interactive shell inside the VM
• Uses WebSocket bidirectional communication
• Press Ctrl+] to exit
• Only one console session per VM is supported

noid checkpoint

Create a VM checkpoint (snapshot).

noid checkpoint <vm-name> <checkpoint-name> [OPTIONS]

Arguments:

• <vm-name> - VM to checkpoint (required)
• <checkpoint-name> - Name for the checkpoint (required)

Options:

--label <TEXT>    Optional description label

Examples:

# Create checkpoint
noid checkpoint my-vm stable-v1

# With description
noid checkpoint my-vm configured --label "Development environment ready"

What's Captured:

• Complete VM memory state
• Disk state
• CPU registers
• All process states

Performance:

• Typically < 100ms for checkpoint creation
• On btrfs: zero-copy (instant) for disk
• On ext4: regular file copy for disk

Notes:

• Checkpoints capture the complete VM state (like hibernating a laptop)
• Use descriptive names rather than timestamps
• Label describes the state, not the time

noid restore

Restore VM from checkpoint.

noid restore <vm-name> <checkpoint-id> [OPTIONS]

Arguments:

• <vm-name> - VM to restore (required)
• <checkpoint-id> - Checkpoint ID to restore from (required)

Options:

--as <newname>    Clone into new VM instead of restoring in-place

Examples:

# Restore in-place (rewind the VM)
noid restore my-vm stable-v1

# Clone to new VM
noid restore my-vm stable-v1 --as test-instance-2

Performance:

• Typically < 50ms for restoration
• Nearly instant on btrfs

Notes:

• In-place restore "rewinds" the VM to checkpoint state
• Clone with --as creates a new VM from the checkpoint
• The VM gets a new IP address on restore
• Use DNS rather than hardcoded IP addresses

noid use

Set active VM context for current directory.

noid use <name>

Arguments:

• <name> - VM name to set as active

Examples:

# Set active VM
noid use my-dev-vm

# Now commands work without specifying VM name
noid exec -- ls
noid console

How it Works:

• Creates a .noid file in current directory
• Stores the active VM name
• Subsequent commands use this VM by default
• Allows omitting the VM parameter

noid auth setup

Configure authentication with Noid server.

noid auth setup --url <SERVER_URL> --token <TOKEN>

Options:

--url <URL>      Server URL (required)
--token <TOKEN>  API token (required)

Examples:

# Setup authentication
noid auth setup --url http://my-server:7654 --token abc123def456...

# Local development server
noid auth setup --url http://localhost:7654 --token your-token

Notes:

• Saves credentials to ~/.noid/config.toml
• Verifies connectivity to server
• Token should be 64-character hexadecimal
• Default port is 7654

Configuration

Environment Variables

NOID_SERVER    Default server URL
NOID_TOKEN     Authentication token

Example:

export NOID_SERVER=http://my-server:7654
export NOID_TOKEN=your-token-here

noid list  # Uses environment variables

Configuration File

Noid reads configuration from ~/.noid/config.toml:

server = "http://my-server:7654"
token = "your-token-here"

Active VM Context

The .noid file in your current directory stores the active VM:

my-dev-vm

This allows commands to omit the VM name parameter.

Common Patterns

Golden Snapshot Workflow

# 1. Create and configure VM
noid create base-vm
noid exec base-vm -- apt-get update
noid exec base-vm -- apt-get install -y python3 nodejs

# 2. Create golden checkpoint
noid checkpoint base-vm golden

# 3. Create clones from checkpoint
noid restore base-vm golden --as worker-1
noid restore base-vm golden --as worker-2
noid restore base-vm golden --as worker-3

# 4. Use and reset
noid exec worker-1 -- ./run-task.sh
noid restore worker-1 golden  # Reset to clean state

Development with Active Context

# Set active VM for project
cd ~/my-project
noid use dev-vm

# Now work without specifying VM
noid exec -- npm install
noid exec -- npm test
noid checkpoint dev-vm working-state

# Reset when needed
noid restore dev-vm working-state

CI/CD Pattern

#!/bin/bash
# Create isolated test VM
noid create ci-vm-$BUILD_ID

# Run tests
noid exec ci-vm-$BUILD_ID -- git clone $REPO_URL /workspace
noid exec ci-vm-$BUILD_ID -- /workspace/run-tests.sh

# Cleanup
noid destroy ci-vm-$BUILD_ID

Exit Codes

All commands follow standard exit code conventions:

• 0 - Success
• Non-zero - Error

For noid exec, returns the exit code of the executed command.

Next Steps

• Server Setup - Configure the Noid server
• Checkpoints Guide - Advanced checkpoint features
• Authentication - Token management

Getting Help

# Command help
noid <command> --help

# Version info
noid --version

# Report issues
# https://github.com/noid-one/noid-cli/issues