@walkeros/cli
Advanced tools
Command-line tools for building, testing, and running walkerOS event collection flows.
The walkerOS CLI is a developer tool that:
Think of it as your development toolchain for walkerOS - from config to running production bundles.
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.
# Global (recommended for CLI usage)
npm install -g @walkeros/cli
# Local (for programmatic usage)
npm install @walkeros/cli
# Bundle a flow configuration
walkeros bundle flow.json
# Test with simulated events (no real API calls)
walkeros simulate flow.json --event '{"name":"product view"}'
# Or test a pre-built bundle directly
walkeros simulate dist/bundle.mjs --event '{"name":"product view"}'
# Push real events to destinations
walkeros push flow.json --event '{"name":"product view"}'
# Run a collection server locally
walkeros run collect dist/bundle.mjs --port 3000
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 outputExamples:
# 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. The --dockerfile flag generates a Dockerfile with
the correct MODE (collect/serve) based on flow type.
Test event processing with simulated events. Accepts either a config JSON (which gets bundled) or a pre-built bundle (executed directly).
walkeros simulate <input> --event '{"name":"page view"}' [options]
Input types:
.js/.mjs) - Executed directly, no mockingThe CLI auto-detects the input type by attempting to parse as JSON.
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 outputExamples:
# 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"}'
# Simulate with pre-built bundle
walkeros simulate dist/bundle.mjs --event '{"name":"page view"}'
# Override platform detection
walkeros simulate dist/bundle.js --platform server --event '{"name":"page view"}'
Platform detection:
When using pre-built bundles, platform is detected from file extension:
.mjs → server (ESM, Node.js).js → web (IIFE, JSDOM)Use --platform to override if extension doesn't match intended runtime.
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:
.js/.mjs) - Executed directlyThe 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 flows locally (no Docker daemon required).
walkeros run <mode> <config-file> [options]
Modes:
collect - HTTP event collection serverserve - Static file serverOptions:
-p, --port <number> - Server port-h, --host <host> - Server host--json - Output as JSON-v, --verbose - Verbose output-s, --silent - Suppress outputExamples:
# 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:
.mjs.mjs bundles are used directlyThe CLI implements intelligent caching for faster builds:
.tmp/cache/packages/latest, ^, ~) are re-checked daily0.4.1) are cached indefinitely.tmp/cache/builds/# 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 configs use the Flow.Setup format with version and flows:
{
"version": 1,
"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.
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:
packages.imports for destinations/sources - the default export is used
automaticallycode when using a specific named export from a multi-export
packagepackages.imports only for utilities needed in mappings or custom codeUse 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 versiondist/ folder exists, it's used; otherwise package root is usedDependency 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.
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,
});
Working example configs in examples/:
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
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 collect 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"}}'
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.
Deploy your flows using Docker or Node.js.
The walkeros/flow image runs pre-built bundles in production:
# Build your flow with Dockerfile
walkeros bundle flow.json --dockerfile
# Deploy (e.g., to Cloud Run)
gcloud run deploy my-service --source ./dist
Or run locally:
docker run -v ./dist:/flow -p 8080:8080 walkeros/flow
Custom Dockerfile:
# Use a custom Dockerfile with extra packages or configuration
walkeros bundle flow.json --dockerfile Dockerfile.custom
Environment variables:
MODE - collect or serve (default: collect)PORT - Server port (default: 8080)BUNDLE - Bundle path (default: /app/flow/bundle.mjs)Run the bundle directly with the CLI:
# Build your flow
walkeros bundle flow.json
# Run in production
walkeros run collect 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.
See src/types.ts for TypeScript interfaces.
MIT © elbwalker
FAQs
walkerOS CLI - Bundle and deploy walkerOS components
The npm package @walkeros/cli receives a total of 882 weekly downloads. As such, @walkeros/cli popularity was classified as not popular.
We found that @walkeros/cli demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Security News
GPT-6 Astra tried to plant malicious code in simulated open source projects using fake GitHub accounts and deceptive PRs during an assigned CTF challenge.
Security News
upm uses Node.js to deliver fast npm installs in about 250 KB, with a JavaScript API and security defaults.
Company News
Socket is joining the OpenJS Security Stewardship Program to fund Node.js vulnerability research, maintainer remediation, and security releases.