Using the walkerOS CLI

Overview

The walkerOS CLI (walkeros) bundles, tests, and runs event collection flows.

Core workflow:

1. Configure - Write Flow.Setup JSON config
2. Bundle - Generate optimized JS bundle
3. Test - Simulate events (mocked) or push (real)
4. Deploy - Run locally or deploy to production

Quick Start

# Install
npm install -g @walkeros/cli

# Bundle a flow
walkeros bundle flow.json

# Test with simulated event
walkeros simulate flow.json -e '{"entity":"page","action":"view"}'

# Push real event
walkeros push flow.json -e '{"entity":"page","action":"view"}'

Commands Overview

For detailed command reference, see commands-reference.md.

Common Workflows

Development Workflow

1. Write flow.json config
2. Bundle: walkeros bundle flow.json
3. Simulate: walkeros simulate flow.json -e event.json
4. Fix issues, repeat 2-3
5. Push test: walkeros push flow.json -e event.json
6. Deploy bundle

Multi-Flow Development

# Bundle specific flow
walkeros bundle flow.json --flow myFlow

# Bundle all flows
walkeros bundle flow.json --all

# Test specific flow
walkeros simulate flow.json --flow myFlow -e event.json

Local Development Servers

# Server-side: HTTP event collection
walkeros run collect flow.json --port 3000

# Browser-side: Static file server
walkeros run serve flow.json --port 8080

Flow.Setup Configuration

Minimal Config

{
  "version": 1,
  "flows": {
    "default": {
      "web": {},
      "packages": {
        "@walkeros/web-destination-gtag": {}
      },
      "destinations": {
        "gtag": {
          "package": "@walkeros/web-destination-gtag",
          "config": { "measurementId": "G-XXXXXX" }
        }
      }
    }
  }
}

Config Structure

{
  "version": 1,
  "flows": {
    "<flowName>": {
      "web": {} | "server": {},     // Platform (required)
      "packages": {},               // NPM packages to bundle
      "sources": {},                // Event sources
      "destinations": {},           // Event destinations
      "transformers": {},           // Transformer chain (optional)
      "mappings": {},               // Event transformation rules
      "collector": {}               // Collector configuration
    }
  }
}

For detailed configuration options, see flow-configuration.md.

$code: Prefix (Inline JavaScript)

Embed JavaScript functions in JSON configs:

{
  "fn": "$code:(event) => event.data.price * 100",
  "condition": "$code:(event) => event.data?.value > 100"
}

Important: The CLI bundler converts $code: strings to actual JavaScript functions during build. This is essential for mappings in JSON configs.

For mapping patterns, see understanding-mapping.

Quick Reference

Bundle Command

walkeros bundle <config> [options]

Options:
  --flow <name>     Bundle specific flow (default: "default")
  --all             Bundle all flows
  --stats           Show bundle statistics
  --json            JSON output
  --no-cache        Skip build cache
  --dockerfile      Generate Dockerfile
  -v, --verbose     Verbose output
  -s, --silent      Silent mode

Output: ./dist/walker.js (web) or ./dist/bundle.mjs (server)

Simulate Command

walkeros simulate <config|bundle> [options]

Options:
  -e, --event <json|file|url>   Event to process (required for bundles)
  --flow <name>                  Flow to simulate
  -p, --platform <web|server>   Platform override
  --json                         JSON output

Push Command

walkeros push <config|bundle> [options]

Options:
  -e, --event <json|file|url>   Event to process (required)
  --flow <name>                  Flow to use
  -p, --platform <web|server>   Platform override

Validate Command

walkeros validate <input> [options]

Options:
  --flow            Validate as flow config
  --config          Validate as destination/source config
  --strict          Treat warnings as errors
  --json            JSON output

Exit codes:
  0 = Valid
  1 = Errors found
  2 = Warnings (with --strict)
  3 = Input error

Run Command

# HTTP event collection server
walkeros run collect <config|bundle> [options]

# Static file server for browser bundles
walkeros run serve <config|bundle> [options]

Options:
  -p, --port <number>   Port (default: 3000/8080)
  -h, --host <string>   Host (default: localhost)

Troubleshooting

Bundle Fails

1. Check JSON syntax: walkeros validate flow.json --flow
2. Check package names: Ensure packages exist on npm
3. Clear cache: walkeros cache clear

Events Not Processing

1. Validate event: walkeros validate event.json
2. Check mapping: Event must match entity/action in mapping
3. Use simulate first: walkeros simulate flow.json -e event.json -v

Local Packages Not Found

Use absolute or relative paths:

{
  "packages": {
    "my-destination": {
      "path": "./local/my-destination"
    }
  }
}

Where CLI Lives

Related Skills

• understanding-mapping - Mapping configuration
• understanding-flow - Data flow architecture
• create-destination - Creating destinations
• create-source - Creating sources
• debugging - Troubleshooting event flow

Detailed References:

• commands-reference.md - All commands with full options
• flow-configuration.md - Complete Flow.Setup reference