| name | walkeros-using-cli |
| description | Use when working with the walkerOS CLI (`walkeros`) bundles, tests, and runs event collection flows. |
| metadata | {"author":"elbwalker"} |
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
npm install -g @walkeros/cli
walkeros bundle flow.json
walkeros push flow.json -e '{"entity":"page","action":"view"}' --simulate destination.demo
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
walkeros bundle flow.json --flow myFlow
walkeros bundle flow.json --all
walkeros push flow.json --flow myFlow -e event.json --simulate destination.demo
Local Development 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": {},
"packages": {},
"sources": {},
"destinations": {},
"transformers": {},
"mappings": {},
"collector": {}
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? }):
walkeros push flow.json --simulate source.browser --event '{"content":"<html>...","trigger":{"type":"click"}}'
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
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 is dist/bundle.mjs). The CLI detects this
and errors.
- Runtime paths: The runner sets CWD to the bundle directory. File paths in
settings resolve 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-wrapper cause
syntax errors โ use gtagWrapper instead.
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
Detailed References:
Converted and distributed by TomeVault โ claim your Tome and manage your conversions.
