tomevault-io Using the walkerOS CLI
Overview
The walkerOS CLI (walkeros) bundles, tests, and runs event collection flows.
Core workflow:
- Configure - Write Flow.Config JSON config
- Bundle - Generate optimized JS bundle
- Test - Simulate events (mocked) or push (real)
- 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 push flow.json -e '{"entity":"page","action":"view"}' --simulate destination.demo
# Push real event
walkeros push flow.json -e '{"entity":"page","action":"view"}'
Commands Overview
| Command | Purpose | Safe? |
|---|---|---|
bundle |
Generate JS bundle from config | ✅ |
push |
Execute with real API calls (or --simulate for mocked) |
⚠️ |
run |
Local HTTP event collection | ✅ |
deploy |
Deploy flows to cloud | ⚠️ |
validate |
Validate configs/events | ✅ |
cache |
Manage caching | ✅ |
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 push flow.json -e event.json --simulate destination.demo
4. Fix issues, repeat 2-3
5. Push test: walkeros push flow.json -e event.json
6. Deploy: walkeros deploy start <flowId>
Multi-Flow Development
# Bundle specific flow
walkeros bundle flow.json --flow myFlow
# Bundle all flows
walkeros bundle flow.json --all
# Test specific flow
walkeros push flow.json --flow myFlow -e event.json --simulate destination.demo
Local Development Server
# HTTP event collection server
walkeros run flow.json --port 3000
Server port note: The --port flag (or PORT env var) is forwarded at
runtime to all source configs that have a port setting. You don't need to
hardcode ports in the flow config — set port: 8080 as a default and let the
runtime override it.
Flow.Config Configuration
Minimal Config
{
"version": 3,
"flows": {
"default": {
"web": {},
"packages": {
"@walkeros/web-destination-gtag": {}
},
"destinations": {
"gtag": {
"package": "@walkeros/web-destination-gtag",
"config": { "measurementId": "G-XXXXXX" }
}
}
}
}
}
Config Structure
{
"version": 3,
"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.
Testing with Step Examples
Simulate with --step
Target a specific step and provide input as SourceInput
({ content, trigger? }):
# Simulate a source step with trigger metadata
walkeros push flow.json --simulate source.browser --event '{"content":"<html>...","trigger":{"type":"click"}}'
# Simulate a destination step with an event
walkeros push flow.json --simulate destination.gtag -e '{"entity":"order","action":"complete","data":{"total":149.97}}'
Example output:
Step: destinations.gtag
in: { name: "order complete", data: { id: "ORD-123", total: 149.97 } }
out: ["event", "purchase", { transaction_id: "ORD-123", value: 149.97 }]
Status: PASS
Validate flow config
Validate schema, references, and cross-step example compatibility:
walkeros validate flow.json
All checks run automatically — schema validation, reference checking, and cross-step example compatibility. No flags needed for full validation.
For full details on writing and testing with step examples, see using-step-examples.
$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)
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
--simulate <step> Simulate a step (repeatable). destination.NAME or source.NAME
--mock <step=value> Mock a step with a specific return value (repeatable)
--snapshot <source> JS file to eval before execution (sets global state)
Validate Command
walkeros validate <input> [options]
Options:
--type <type> Validation type (default: flow). Also: event, mapping, contract
--path <path> Validate entry against package schema (e.g. destinations.snowplow)
--flow <name> Flow name for multi-flow configs
--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 <config|bundle> [options]
Options:
-p, --port <number> Port (default: 8080)
-h, --host <string> Host (default: 0.0.0.0)
Bundler Gotchas
- Circular copies: Never include the output directory itself (e.g.,
include: ["./dist"]when output isdist/bundle.mjs). The CLI detects this and errors. - Runtime paths: The runner sets CWD to the bundle directory. File paths in
settingsresolve relative to the bundle, not the project root. - Component names: Source, transformer, destination, and store names must be
valid JavaScript identifiers (camelCase). Hyphens like
gtag-wrappercause syntax errors — usegtagWrapperinstead.
Troubleshooting
Bundle Fails
- Check JSON syntax:
walkeros validate flow.json --flow - Check package names: Ensure packages exist on npm
- Clear cache:
walkeros cache clear
Events Not Processing
- Validate event:
walkeros validate event.json - Check mapping: Event must match entity/action in mapping
- Use simulate first:
walkeros push flow.json -e event.json --simulate destination.demo -v
Destination Not Found in Simulation
If --simulate destination.NAME errors with "not found in collector", the
destination likely has require: ["consent"] in its config. This delays
initialization until a walker consent event fires — which doesn't happen
during simulation.
Fix: Remove or comment out the require field for simulation testing:
{
"destinations": {
"gtag": {
"package": "@walkeros/web-destination-gtag",
"config": {
"settings": { "measurementId": "G-XXXXXX" }
}
}
}
}
Destination Silent (0 Events Received)
If the destination is found but receives 0 events:
- Check consent: If destination has
consent: { marketing: true }, the event must include matching consent. Add to event JSON:{ "name": "page view", "data": {...}, "consent": { "marketing": true } } - Check mapping: The event name must match a mapping rule (entity/action keys). Unmapped events pass through unmodified.
- Check policy: Policy runs BEFORE mapping — verify policy isn't redacting fields needed by mapping rules.
Web Simulation Transport
Web simulations run in JSDOM. fetch and navigator.sendBeacon are
polyfilled as tracked no-ops -- no real HTTP requests are made. Captured
network calls are included in PushResult.networkCalls when present.
Local Packages Not Found
Use absolute or relative paths:
{
"packages": {
"my-destination": {
"path": "./local/my-destination"
}
}
}
Where CLI Lives
| Location | Purpose |
|---|---|
packages/cli/ |
CLI source code |
packages/cli/src/commands/ |
Command implementations |
packages/cli/examples/ |
Example flow configs |
packages/cli/README.md |
Full CLI documentation |
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.Config reference
- server-deployment.md - Server flow deployment guide
Converted and distributed by TomeVault — claim your Tome and manage your conversions.