NodeTool CLI

The nodetool CLI is the TypeScript command-line interface for the NodeTool platform. It manages servers, workflows, jobs, assets, and secrets. Install the project and run nodetool --help to see the top-level command list. Every sub-command exposes its own --help flag with detailed usage.

Installation

The CLI is part of the @nodetool/cli package in the monorepo. Build it with:

# From repo root
npm install
npm run build:packages

After building, you can run the CLI via:

node packages/cli/dist/nodetool.js --help
# Or via the npm script alias:
npm run nodetool -- --help

Getting Help

  • nodetool --help — list all top-level commands.
  • nodetool <command> --help — show command-specific options (e.g. nodetool serve --help).
  • nodetool <group> --help — list sub-commands for grouped tooling (e.g. nodetool workflows --help).

Core Commands

nodetool info

Display system and environment information including Node.js version, platform, and API key configuration.

Options:

  • --json — output as JSON.

Example:

nodetool info
nodetool info --json

nodetool serve

Starts the TypeScript WebSocket + HTTP backend server. This serves the REST API, WebSocket endpoints, and static assets.

Options:

  • --host (default 127.0.0.1) — bind address (use 0.0.0.0 for all interfaces).
  • --port (default 7777) — listen port.

Examples:

# Start the server on the default port
nodetool serve

# Bind to all interfaces on a custom port
nodetool serve --host 0.0.0.0 --port 8080

You can also start the server directly:

PORT=7777 HOST=127.0.0.1 node packages/websocket/dist/server.js

nodetool workflows run <workflow_id_or_file>

Executes a workflow by ID (from the local database), JSON file, or TypeScript DSL file.

Arguments:

  • <workflow_id_or_file> — workflow ID, path to a .json workflow file, or path to a .ts DSL file.

Options:

  • --params <json> — JSON string of workflow parameters.
  • --json — output result as JSON.

Examples:

# Run workflow by ID
nodetool workflows run workflow_abc123

# Run workflow from JSON file
nodetool workflows run ./my_workflow.json

# Run workflow from TypeScript DSL
nodetool workflows run ./my_workflow.ts

# Run with parameters as JSON
nodetool workflows run workflow_abc123 --params '{"input": "hello"}'

# JSON output for automation
nodetool workflows run ./my_workflow.json --json

nodetool workflows export-dsl <workflow_id_or_file>

Exports a workflow as a TypeScript DSL file.

Arguments:

  • <workflow_id_or_file> — workflow ID or path to a .json workflow file.

Options:

  • -o, --output <file> — write to file instead of stdout.

Examples:

# Print DSL to stdout
nodetool workflows export-dsl workflow_abc123

# Write to file
nodetool workflows export-dsl workflow_abc123 -o workflow.ts

# Export from JSON file
nodetool workflows export-dsl ./my_workflow.json

nodetool run <dsl-file>

Shorthand for running a TypeScript DSL workflow file directly.

Options:

  • --json — output results as JSON.

Examples:

nodetool run workflow.ts
nodetool run workflow.ts --json

Chat

nodetool chat

Starts an interactive TUI chat session.

Options:

  • -p, --provider <provider> — LLM provider (e.g., anthropic, openai, ollama).
  • -m, --model <model> — model ID.
  • -a, --agent — enable agent mode with tool use.
  • -u, --url <url> — WebSocket server URL (default: connects to local server).
  • -w, --workspace <path> — workspace directory for file operations.
  • --tools <tools> — comma-separated list of enabled tools.

Examples:

# Start interactive chat
nodetool chat

# Chat with a specific provider and model
nodetool chat --provider anthropic --model claude-3-5-sonnet-20241022

# Agent mode with tool use
nodetool chat --agent --provider openai

# Connect to a custom server
nodetool chat --url ws://localhost:7777

Workflow Management

nodetool workflows

Manage workflows via the API.

Subcommands: list, get, run

# List all workflows
nodetool workflows list
nodetool workflows list --api-url http://localhost:7777 --json

# Get a workflow by ID
nodetool workflows get <workflow_id>

# Run a workflow (see above for full options)
nodetool workflows run <workflow_id_or_file>

Job Management

nodetool jobs

Query job status and results.

Subcommands: list, get

Options:

  • --api-url <url> — API base URL (default: http://localhost:7777).
  • --workflow-id <id> — filter by workflow ID (for list).
  • --limit <n> — max results (default: 100).
  • --json — output as JSON.

Examples:

# List all jobs
nodetool jobs list

# Filter by workflow
nodetool jobs list --workflow-id workflow_abc123

# Get a specific job
nodetool jobs get <job_id>

Asset Management

nodetool assets

Manage uploaded files and workflow assets.

Subcommands: list, get

Options:

  • --api-url <url> — API base URL (default: http://localhost:7777).
  • --query <q> — search query (for list).
  • --content-type <type> — filter by content type (for list).
  • --limit <n> — max results (default: 100).
  • --json — output as JSON.

Examples:

# List assets
nodetool assets list

# Search assets
nodetool assets list --query "landscape"

# Get a specific asset
nodetool assets get <asset_id>

Secrets Management

nodetool secrets

Manage encrypted secrets stored in the local database with per-user encryption.

Subcommands: list, store, get

Examples:

# List stored secret keys
nodetool secrets list

# Store a secret (prompts for value)
nodetool secrets store OPENAI_API_KEY

# Retrieve a secret value
nodetool secrets get OPENAI_API_KEY

Settings

nodetool settings show

Display current settings from environment variables.

Options:

  • --json — output as JSON.

Example:

nodetool settings show
nodetool settings show --json

Tips

  • Use --json flags for machine-readable output suitable for scripting.
  • Set NODETOOL_API_URL environment variable to avoid specifying --api-url on every command.
  • Use nodetool serve to start the local backend server before running API commands.
  • See Environment Variables for a complete list of configurable variables.
Edit this page on GitHub