Agent skill

walkeros-using-cli

Use when bundling walkerOS flows, testing events with simulate/push, running local servers, validating configs, or configuring Flow.Setup JSON files.

View SKILL.md on GitHub Repository
Stars 163
Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/other/other/walkeros-using-cli

SKILL.md

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

bash
# 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

Command Purpose Safe?
bundle Generate JS bundle from config ✅
simulate Test with mocked API calls ✅
push Execute with real API calls ⚠️
run collect Local HTTP event collection ✅
run serve Local static file server ✅
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 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

bash
# 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

bash
# 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

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

Config Structure

json
{
  "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:

json
{
  "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

bash
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

bash
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

bash
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

bash
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

bash
# 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:

json
{
  "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.Setup reference

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

majiayu000/claude-skill-registry

agent-ops-spec

Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-state

Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-spec

Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-testing

Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-testing

Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-state

Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.

163 31
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results