@walkeros/cli

@walkeros/cli

Command-line tools for building, testing, and running walkerOS event collection flows.

What is this?

The walkerOS CLI is a developer tool that:

• Bundles flow configurations into optimized JavaScript
• Simulates event processing for testing
• Runs flows locally without Docker daemon

Think of it as your development toolchain for walkerOS - from config to running production bundles.

Installation

# Global (recommended for CLI usage)
npm install -g @walkeros/cli

# Local (for programmatic usage)
npm install @walkeros/cli

Commands

bundle

Generate optimized JavaScript bundles from flow configurations.

walkeros bundle <config-file> [options]

Config files can be local paths or HTTP(S) URLs:

walkeros bundle ./config.json                                    # Local file
walkeros bundle https://example.com/config.json                  # Remote URL

Options:

• -e, --env <name> - Build specific environment (multi-env configs)
• --all - Build all environments
• -s, --stats - Show bundle statistics
• --json - Output stats as JSON
• --no-cache - Disable package caching
• --local - Run locally without Docker
• -v, --verbose - Verbose output

Example:

# Bundle with stats
walkeros bundle examples/server-collect.json --stats

The output path is specified in the config's build.output field.

simulate

Test event processing with simulated events.

walkeros simulate <config-file> --event '{"name":"page view"}' [options]

Options:

• -e, --event <json> - Event JSON string (required)
• --json - Output results as JSON
• --local - Run locally without Docker
• -v, --verbose - Verbose output

Example:

# Simulate page view
walkeros simulate \
  examples/web-serve.json \
  --event '{"name":"page view","data":{"title":"Home"}}' \
  --json

run

Run flows locally using @walkeros/docker as a library (no Docker daemon required).

walkeros run <mode> <config-file> [options]

Modes:

• collect - HTTP event collection server
• serve - Static file server

Options:

• -p, --port <number> - Server port
• -h, --host <host> - Server host
• --static-dir <dir> - Static directory (serve mode)
• --local - Run locally without Docker
• --json - JSON output
• -v, --verbose - Verbose output

Examples:

# Run collection server (auto-bundles JSON)
walkeros run collect examples/server-collect.json --port 3000

# Run with pre-built bundle
walkeros run collect examples/server-collect.mjs --port 3000

# Serve static files
walkeros run serve flow.json --port 8080 --static-dir ./dist

How it works:

• JSON configs are bundled to temp .mjs automatically
• .mjs bundles are used directly
• Runs in current Node.js process (no containers)
• Press Ctrl+C for graceful shutdown

Flow Configuration

Minimal example:

{
  "flow": {
    "platform": "server",
    "sources": {
      "http": {
        "code": "sourceExpress",
        "config": {
          "settings": {
            "path": "/collect",
            "port": 8080
          }
        }
      }
    },
    "destinations": {
      "demo": {
        "code": "destinationDemo",
        "config": {
          "settings": {
            "name": "Demo"
          }
        }
      }
    },
    "collector": {
      "run": true
    }
  },
  "build": {
    "packages": {
      "@walkeros/collector": {
        "version": "latest",
        "imports": ["startFlow"]
      },
      "@walkeros/server-source-express": {
        "version": "latest",
        "imports": ["sourceExpress"]
      },
      "@walkeros/destination-demo": {
        "version": "latest",
        "imports": ["destinationDemo"]
      }
    },
    "code": "// Custom code here\n",
    "output": "bundle.mjs",
    "template": "./templates/base.hbs"
  }
}

See examples/ for complete working configurations.

Programmatic API

Use commands programmatically:

import { bundle, simulate, runCommand } from '@walkeros/cli';

// Bundle
await bundle({
  config: './flow.json',
  stats: true,
});

// Simulate
const result = await simulate(
  './flow.json',
  { name: 'page view', data: { title: 'Test' } },
  { json: true },
);

// Run
await runCommand('collect', {
  config: './flow.json',
  port: 3000,
  verbose: true,
});

Examples

Working example configs in examples/:

• server-collect.json - Basic server-side collection
• server-collection.json - Advanced server setup
• web-serve.json - Web demo with API destination
• web-tracking.json - General web tracking

Try them:

# Bundle example
walkeros bundle examples/server-collect.json --stats

# Simulate
walkeros simulate \
  examples/web-serve.json \
  --event '{"name":"product view","data":{"id":"P123"}}'

# Run server
walkeros run collect examples/server-collect.json --port 3000

Development Workflow

Typical development cycle:

# 1. Create/edit config
vim my-flow.json

# 2. Bundle and check stats
walkeros bundle my-flow.json --stats

# 3. Test with simulation
walkeros simulate \
  my-flow.json \
  --event '{"name":"test event"}' \
  --verbose

# 4. Run locally
walkeros run collect my-flow.json --port 3000

# 5. In another terminal, test it
curl -X POST http://localhost:3000/collect \
  -H "Content-Type: application/json" \
  -d '{"name":"page view","data":{"title":"Home"}}'

Architecture

CLI (downloads packages + bundles with esbuild)
 ├─ Bundle → optimized .mjs file
 ├─ Simulate → test bundle with events
 └─ Run → import @walkeros/docker + execute bundle

Key principle: CLI handles build-time, Docker handles runtime.

Docker Images

By default, CLI uses explicit version tags (not :latest):

• walkeros/cli:0.3.5 - Build tools (bundle, simulate)
• walkeros/docker:0.1.4 - Production runtime

Override with environment variables:

export WALKEROS_CLI_DOCKER_IMAGE=walkeros/cli:0.3.4
export WALKEROS_RUNTIME_DOCKER_IMAGE=walkeros/docker:latest
walkeros bundle config.json

Requirements

• Node.js: 18+ or 22+
• Docker: Not required for CLI (only for production deployment)

Documentation

Detailed guides in docs/:

• RUN_COMMAND.md - Run command details
• PUBLISHING.md - Publishing guide
• MANUAL_TESTING_GUIDE.md - Testing guide

License

MIT © elbwalker