@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.

When to Use the CLI

The CLI is for Bundled mode — when you want config-as-code and separate deployment:

Use CLI When	Use Integrated Mode When
Static sites, landing pages	React/Next.js apps
Docker/server deployments	TypeScript projects
CI/CD versioned configs	Programmatic control
Marketing/GTM workflows	Build-time type safety

For Integrated mode (importing directly into your app), see the Collector package.

Installation

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

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

Quick Start

# Bundle a flow configuration
walkeros bundle flow.json

# Test with simulated events (no real API calls)
walkeros simulate flow.json --event '{"name":"product view"}'

# Push real events to destinations
walkeros push flow.json --event '{"name":"product view"}'

# Run a collection server locally
walkeros run dist/bundle.mjs --port 3000

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:

• --flow <name> - Flow name for multi-flow configs
• --all - Build all flows for multi-flow configs
• --stats - Show bundle statistics
• --json - Output as JSON (implies --stats)
• --no-cache - Disable package caching
• --dockerfile [file] - Generate Dockerfile (or copy custom file) to dist/
• -v, --verbose - Verbose output
• -s, --silent - Suppress output

Examples:

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

# Bundle with auto-generated Dockerfile
walkeros bundle flow.json --dockerfile

# Bundle with custom Dockerfile
walkeros bundle flow.json --dockerfile Dockerfile.custom

The output path uses convention-based defaults: ./dist/bundle.mjs for server, ./dist/walker.js for web.

simulate

Test event processing with simulated events. The config JSON gets bundled and executed with destination mocking.

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

Options:

• -e, --event <json> - Event to simulate (JSON string, file path, or URL)
• --flow <name> - Flow name for multi-flow configs
• -p, --platform <platform> - Platform override (web or server)
• --json - Output as JSON
• -v, --verbose - Verbose output
• -s, --silent - Suppress output

Examples:

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

# Simulate specific flow from multi-flow config
walkeros simulate flow.json --flow server --event '{"name":"test"}'

push

Execute your flow with real API calls to configured destinations. Unlike simulate which mocks API calls, push performs actual HTTP requests. Accepts either a config JSON (which gets bundled) or a pre-built bundle.

walkeros push <input> --event '<json>' [options]

Input types:

• Config JSON - Bundled and executed
• Pre-built bundle (.js/.mjs) - Executed directly

The CLI auto-detects the input type by attempting to parse as JSON.

Options:

• -e, --event <source> - Event to push (JSON string, file path, or URL) Required
• --flow <name> - Flow name (for multi-flow configs)
• -p, --platform <platform> - Platform override (web or server)
• --json - Output results as JSON
• -v, --verbose - Verbose output
• -s, --silent - Suppress output (for CI/CD)

Event input formats:

# Inline JSON
walkeros push flow.json --event '{"name":"page view","data":{"title":"Home"}}'

# File path
walkeros push flow.json --event ./events/order.json

# URL
walkeros push flow.json --event https://example.com/sample-event.json

Bundle input:

# Push with pre-built bundle
walkeros push dist/bundle.mjs --event '{"name":"order complete"}'

# Override platform detection
walkeros push dist/bundle.js --platform server --event '{"name":"order complete"}'

Push vs Simulate:

Feature	push	simulate
API Calls	Real HTTP requests	Mocked (captured)
Use Case	Integration testing	Safe local testing
Side Effects	Full (writes to DBs, sends to APIs)	None

Use simulate first to validate configuration safely, then push to verify real integrations.

run

Run flows locally (no Docker daemon required).

walkeros run <config-file> [options]

Options:

• -p, --port <number> - Server port
• -h, --host <host> - Server host
• --json - Output as JSON
• -v, --verbose - Verbose output
• -s, --silent - Suppress output

Examples:

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

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

How it works:

• JSON configs are auto-bundled to temp .mjs
• .mjs bundles are used directly
• Runs in current Node.js process
• Press Ctrl+C for graceful shutdown

validate

Validate flow configurations, events, mappings, or contracts.

walkeros validate <config-file> [options]

By default, validates a Flow.Config file — checking schema, references, and cross-step example compatibility.

Options:

• --type <type> - Validation type (default: flow). Also accepts: event, mapping, contract
• --path <path> - Validate a specific entry against its package schema (e.g., destinations.snowplow, sources.browser)
• --flow <name> - Flow name for multi-flow configs
• --strict - Treat warnings as errors
• --json - Output as JSON
• -v, --verbose - Verbose output
• -s, --silent - Suppress output

Exit codes: 0 = valid, 1 = errors, 2 = warnings (with --strict), 3 = input error

Examples:

# Validate flow config (schema + examples)
walkeros validate flow.json

# Validate specific flow
walkeros validate flow.json --flow analytics

# Validate a single event
walkeros validate event.json --type event

# Validate in CI
walkeros validate flow.json --json --strict || exit 1

# Validate entry against package schema
walkeros validate flow.json --path destinations.snowplow

deploy

Deploy flows to walkerOS cloud.

walkeros deploy start <flowId> [options]
walkeros deploy status <flowId> [options]

Options:

• --project <id> - Project ID (defaults to WALKEROS_PROJECT_ID)
• --flow <name> - Flow name for multi-config flows
• --no-wait - Do not wait for deployment to complete (start only)
• --json - Output as JSON
• -v, --verbose - Verbose output
• -s, --silent - Suppress output

Examples:

# Deploy a single-config flow
walkeros deploy start cfg_abc123

# Deploy a specific config from a multi-config flow
walkeros deploy start cfg_abc123 --flow web

# Check deployment status
walkeros deploy status cfg_abc123 --flow server

When a flow has multiple configs, the CLI requires --flow <name> to specify which one to deploy. If omitted, the error message lists available names.

Caching

The CLI implements intelligent caching for faster builds:

Package Cache

• NPM packages are cached in .tmp/cache/packages/
• Mutable versions (latest, ^, ~) are re-checked daily
• Exact versions (0.4.1) are cached indefinitely

Build Cache

• Compiled bundles are cached in .tmp/cache/builds/
• Cache key based on flow.json content + current date
• Identical configs reuse cached build within the same day

Cache Management

# View cache info
walkeros cache info

# Clear all caches
walkeros cache clear

# Clear only package cache
walkeros cache clear --packages

# Clear only build cache
walkeros cache clear --builds

# Disable caching for a single build
walkeros bundle flow.json --no-cache

Flow Configuration

Flow configs use the Flow.Config format with version and flows:

{
  "version": 3,
  "flows": {
    "default": {
      "server": {},
      "packages": {
        "@walkeros/collector": { "imports": ["startFlow"] },
        "@walkeros/server-source-express": {},
        "@walkeros/destination-demo": {}
      },
      "sources": {
        "http": {
          "package": "@walkeros/server-source-express",
          "config": {
            "settings": { "path": "/collect", "port": 8080 }
          }
        }
      },
      "destinations": {
        "demo": {
          "package": "@walkeros/destination-demo",
          "config": {
            "settings": { "name": "Demo" }
          }
        }
      },
      "collector": { "run": true }
    }
  }
}

Platform is determined by the web: {} or server: {} key presence.

Package Configuration Patterns

The CLI automatically resolves imports based on how you configure packages:

1. Default exports (recommended for single-export packages):

{
  "packages": {
    "@walkeros/server-destination-api": {}
  },
  "destinations": {
    "api": {
      "package": "@walkeros/server-destination-api"
    }
  }
}

The CLI generates: import _walkerosServerDestinationApi from '@walkeros/server-destination-api';

2. Named exports (for multi-export packages):

{
  "packages": {
    "@walkeros/server-destination-gcp": {}
  },
  "destinations": {
    "bigquery": {
      "package": "@walkeros/server-destination-gcp",
      "code": "destinationBigQuery"
    },
    "analytics": {
      "package": "@walkeros/server-destination-gcp",
      "code": "destinationAnalytics"
    }
  }
}

The CLI generates: import { destinationBigQuery, destinationAnalytics } from '@walkeros/server-destination-gcp';

3. Utility imports (for helper functions):

{
  "packages": {
    "lodash": { "imports": ["get", "set"] }
  },
  "mappings": {
    "custom": {
      "data": "({ data }) => get(data, 'user.email')"
    }
  }
}

The CLI generates: import { get, set } from 'lodash';

Key points:

• Omit packages.imports for destinations/sources - the default export is used automatically
• Only specify code when using a specific named export from a multi-export package
• Use packages.imports only for utilities needed in mappings or custom code

Local Packages

Use local packages instead of npm for development or testing unpublished packages:

{
  "packages": {
    "@walkeros/collector": {
      "path": "../packages/collector",
      "imports": ["startFlow"]
    },
    "@my/custom-destination": {
      "path": "./my-destination",
      "imports": ["myDestination"]
    }
  }
}

Resolution rules:

• path takes precedence over version
• Relative paths are resolved from the config file's directory
• If dist/ folder exists, it's used; otherwise package root is used

Dependency resolution:

When a local package has dependencies on other packages that are also specified with local paths, the CLI will use the local versions for those dependencies too. This prevents npm versions from overwriting your local packages.

{
  "packages": {
    "@walkeros/core": {
      "path": "../packages/core",
      "imports": []
    },
    "@walkeros/collector": {
      "path": "../packages/collector",
      "imports": ["startFlow"]
    }
  }
}

In this example, even though @walkeros/collector depends on @walkeros/core, the local version of core will be used (not downloaded from npm).

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({
  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 examples/server-collect.json --port 3000

Development Workflow

Typical development cycle:

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

# 2. Test with simulation (no real API calls)
walkeros simulate \
  my-flow.json \
  --event '{"name":"product view"}' \
  --verbose

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

# 4. Run locally
walkeros run dist/bundle.mjs --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 → execute bundle with built-in runtime

Key principle: CLI handles both build-time and runtime operations.

Runner (Docker)

The walkeros/flow Docker image is a self-bundling runner for production deployment. It supports four deployment modes — from fully local to fully managed — all using the same image and config format.

# Mode A: Local only — no signup, no API
docker run -v ./flow.json:/app/flow.json -e BUNDLE=/app/flow.json walkeros/flow

# Mode B: Local config + dashboard visibility
docker run -v ./flow.json:/app/flow.json \
  -e BUNDLE=/app/flow.json \
  -e WALKEROS_TOKEN=sk-walkeros-xxx \
  -e PROJECT_ID=proj_xxx \
  walkeros/flow

# Mode C: Remote config with hot-swap
docker run \
  -e WALKEROS_TOKEN=sk-walkeros-xxx \
  -e PROJECT_ID=proj_xxx \
  -e FLOW_ID=flow_xxx \
  walkeros/flow

Each step adds one env var. Same runner, same config, same bundle pipeline.

See the Runner documentation for the full reference (env vars, pipeline, caching, hot-swap, health checks, troubleshooting).

Using Node.js

Run the bundle directly with the CLI:

# Build your flow
walkeros bundle flow.json

# Run in production
walkeros run dist/bundle.mjs --port 8080

This runs the flow in the current Node.js process, suitable for deployment on platforms like AWS Lambda, Google Cloud Run, or any Node.js hosting.

Requirements

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

Type Definitions

See src/types.ts for TypeScript interfaces.

Related

• Website Documentation
• Runner Documentation - Self-hosted runner with config polling and hot-swap
• Docker Runtime - Pre-built bundle deployment
• Flow Configuration
• Collector Package - For Integrated mode (direct imports)
• Operating Modes - Choosing between Integrated and Bundled

License

MIT © elbwalker