CLI Reference

light run

Execute a workflow or single node.

light run <file|dir|id|name> [options]
light run --node [dir] [options]

Options:

Examples:

# Run from folder
light run my-workflow

# Run with inline JSON input
light run my-workflow --input '{"key": "value"}'

# Run with input file
light run my-workflow --input data.json

# Full JSON output (for piping)
light run my-workflow --json | jq '.results'

# Run a single node
light run --node ./my-node

# Single node with input.json auto-loaded
cd my-node && light run --node .

# Search by name in a directory
light run my-workflow --dir ./custom-workflows

Resolution order:

1. If --node: loads .node.json from target directory
2. If target is a folder with workflow.json: loads from folder
3. If target is a .json file: loads directly
4. Searches --dir for matching workflow by ID or name

light serve

Start the REST API server.

light serve [dir] [--port 3000]

Options:

Environment:

Endpoints:

Examples:

# Serve all workflows in current directory
light serve

# Custom port
light serve --port 8080

# Serve a specific directory
light serve ./my-workflows

# Enable Bearer token authentication
LP_API_KEY=my-secret-key light serve

light init

Scaffold a new project or node.

light init [dir]                    # full project
light init --node [dir] [--lang]    # single node

Options:

Project init creates:

• package.json with start/check scripts
• example/ folder with a hello node
• main.js with SDK example

Node init creates:

• .node.json with image and entrypoint
• index.js or main.py (template code)
• lp.js and lp.py (helpers)
• input.json (empty test input)
• Auto-registers in parent workflow.json if present

light check

Validate a workflow without running it.

light check <file|dir> [--fix]

Checks performed (folder mode):

1. workflow.json exists and parses
2. workflow.json structure (name + nodes array)
3. Workflow loads (valid graph)
4. Nodes valid - reports count, or per-node failures (missing image, no entrypoint/files)
5. Links valid - reports count, or per-link failures
6. Entry nodes - reports count, or failure if none found

--fix auto-removes dead node references from workflow.json.

light describe

Show workflow structure and generate a visual diagram.

light describe <file|dir|id|name> [--no-html]

Outputs a text tree and generates describe.html with an interactive Mermaid diagram.

Example output:

  Order Pipeline (order-pipeline)
  3 nodes, 2 links

  Validate (node:20-alpine)
    in: name (string), age (integer)
    out: valid (boolean), score (number)
    -> Process [valid = true]
  Process (python:3.12-alpine)
    out: result (string)
    -> Notify
  Notify (node:20-alpine)

Node input/output schemas are shown when defined.

light doctor

Check the environment and light-run connectivity.

light doctor

Checks:

• Node.js version (prints process.version)
• LIGHT_RUN_URL - decides the mode:
  • unset (all-in-one): confirms the light-run binary is installed, since light serve/light run will spawn it automatically. Fails if the binary is missing.
  • set (explicit runner): pings the runner's /health and fails if it is unreachable.

Container-level concerns (Docker daemon, gVisor, GPU) live on the light-run host, not here - doctor only checks that light-process can reach a runner.

light remote

Manage remote light-process server profiles and run workflows remotely.

light remote <bind|set-key|list|use|forget|ping|ls|run|delete|rm> [...]

Subcommands:

Per-workflow remote override: create a .light-remote file inside the workflow folder containing the remote name.

Examples:

light remote bind https://my-server.com --key abc123
light remote set-key newkey --name test
light remote ls
light remote run my-workflow --input '{"key": "value"}'
light remote delete old-workflow --yes

light pull

Pull a workflow (or all workflows) from a remote server into a local folder.

light pull <id> [--path <dir>] [--force] [--remote <name>]
light pull --all [--force] [--remote <name>]

Options:

light push

Push a local workflow folder to a remote server. Omitting <name> pushes every workflow folder in the current directory. When a workflow already exists, push confirms before replacing it (use --yes to skip the prompt).

light push [<name>] [--path <dir>] [--remote <name>] [--yes]

Options:

light link

Manage links between nodes in a workflow folder.

light link <dir>                                    # Open workflow.json in $EDITOR
light link <dir> --from <id> --to <id> [options]    # Add a link
light link <dir> --edit <link-id> [options]          # Edit a link
light link <dir> --list                             # List links
light link <dir> --remove <link-id>                 # Remove a link
light link <dir> --open                             # Open in $EDITOR

Options (for --from/--to and --edit):

Without flags, opens workflow.json in $EDITOR.

Examples:

light link my-workflow --list
light link my-workflow --from a --to b
light link my-workflow --from a --to b --when '{"status": "ok"}'
light link my-workflow --from a --to b --when '{"count": {"gt": 5}}' --max-iterations 10
light link my-workflow --edit a-b-1 --when '{"status": {"ne": "error"}}'
light link my-workflow --remove a-b-1

light list

List workflows found in a directory. Discovers both folders and JSON files.

light list [--dir <path>] [--json]

Options:

light pack

Convert a workflow folder into a single portable JSON file. The source folder is removed after packing unless --keep is passed.

light pack [<folder>] [--to <file>] [--force] [--keep]

Options:

light unpack

Convert a workflow JSON file into a folder structure. The source JSON is removed after unpacking unless --keep is passed.

light unpack <file.json> [--to <dir>] [--force] [--keep]

Options:

light node

Manage node metadata - inspect node info or edit schemas interactively.

light node info

Show node metadata, input/output schema, and what it receives from upstream nodes.

light node info <dir> [--json]

Reads .node.json from the target directory. If a parent workflow.json exists, also shows incoming links with source node output schemas, conditions, and injected data.

Example output:

Node: transform (transform-1)
Image: node:20-alpine
Entrypoint: node index.js

Inputs:
  1. name (string, required) - The user name
  2. age (integer)

Outputs:
  1. result (string, required)

Receives from:
  validate -> status (string, required), message (string)
    when: {"status":"ok"}
    data: {"role":"admin"}

light node schema

Opens an interactive editor that reads .node.json in <dir> and lets you add, edit, or remove input/output schema fields. Changes are written back to .node.json on save.

light node schema <dir>

light node register

Register an existing node folder in the parent workflow.json. Reads the .node.json to get the node's id and name, then adds it to the nodes array. Skips if already registered.

light node register <dir>

Use this when you initialized a node outside a workflow folder and moved it in afterwards.

light node dev

Generate a .devcontainer/devcontainer.json for the node and open it in VS Code.

light node dev <dir> [--force] [--env-file <path>]

light node helpers

Regenerate lp.d.ts from the node's input/output schema. Provides TypeScript type definitions for lp.js so editors show autocomplete for input fields and send() arguments.

light node helpers <dir>

This is also run automatically by light node schema after saving.

Examples:

light node info ./my-node
light node info ./my-node --json
light node schema ./my-node
light node schema ./example/hello
light node register ./my-workflow/my-node
light node helpers ./my-node

Global options