/walkeros-using-cli

name: walkeros-using-cli
description:
  Use when bundling walkerOS flows, testing events with simulate/push, running
  or deploying a built flow (runneros, the walkeros/flow image), validating
  configs, or configuring Flow JSON files.

Using the walkerOS CLI

Overview

The walkerOS CLI (`walkeros`) validates, simulates, tests and bundles event collection flows. It does not run them: a built server flow runs with `runneros start` from `@walkeros/runner` (the `walkeros/flow` image).

**Core workflow:**

1. **Configure** - Write Flow.Json JSON config 2. **Validate** - `walkeros validate flow.json` 3. **Test** - Simulate events (mocked) or push (real) 4. **Bundle** - `walkeros bundle flow.json -o dist/` 5. **Run** - `runneros start dist/flow.mjs`, or deploy through the app

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) | ⚠️ | | `setup` | Run a component's `setup()` to provision external resources | ⚠️ | | `validate` | Validate configs/events | ✅ | | `cache` | Manage caching | ✅ | | `auth` | Log in, log out, check identity, print the access token | ✅ | | `api` | Call the walkerOS app API, or list its operations | ⚠️ |

For detailed command reference, see [commands-reference.md](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: in the walkerOS app, or
   walkeros api POST /api/projects/{projectId}/flows/<flowId>/deploy
   (see the CI recipe in the CLI docs)

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

# Build, then start the artifact with the runtime (a separate package)
walkeros bundle flow.json -o dist/
npx --package=@walkeros/runner runneros start dist/flow.mjs --port 3000

**Server port note:** Under `runneros` the runtime owns the port: it listens on `--port` (or `PORT`, default 8080), serves `/health` and `/ready`, and hands every other request to the flow's HTTP handler. A source's own `port` setting is not used there.

---

Flow.Json Configuration

Minimal Config

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

Config Structure

{
  "version": 4,
  "flows": {
    "<flowName>": {
      "config": {
        "platform": "web" | "server",  // Platform (required)
        "settings": {},                 // Platform-specific settings (optional)
        "bundle": {
          "packages": {},               // NPM packages pacote will install
          "overrides": {},              // Transitive dep version pins (npm-style)
          "traceInclude": []            // Optional: nft escape hatch (paths/globs)
        },
        "observe": {}                   // Optional: public observe connect pair (url + binding)
      },
      "sources": {},                    // Event sources
      "destinations": {},               // Event destinations
      "transformers": {},               // Transformer chain (optional)
      "mappings": {},                   // Event transformation rules
      "collector": {}                   // Collector configuration
    }
  }
}

**You do NOT need `npm install` for step packages.** flow.json's `config.bundle.packages` is the single source of truth. Pacote installs them transparently when you run `walkeros bundle`. Only `@walkeros/cli` belongs in your project's `package.json` (as a devDependency).

**`config.bundle.overrides`** pins transitive dependency versions. Use it when a vendor SDK's declared peer/dep range conflicts with another required version in the same tree. Example: `{"@amplitude/analytics-types": "2.11.1"}` forces that exact version everywhere in the install graph. Direct `packages` specs always win over overrides; overrides only substitute transitive resolution.

**Schema version stays at 4.** Build-time fields live under `flow.<name>.config.bundle.{packages, overrides, traceInclude}`. The `flow.<name>.config.bundle.external` sub-field is no longer supported in @walkeros/cli@4.x.

**`config.observe` bakes only public values.** For web flows, `walkeros bundle` emits the `url` + `binding` connect pair statically into the bundle; the per-session credential arrives out-of-band at runtime (`?elbObserve=` URL param), so no secret ever enters the artifact. A partial pair (only one of the two set) warns at build time and wires nothing.

For detailed configuration options, see [flow-configuration.md](flow-configuration.md).

---

Testing with Step Examples

Simulate with `--step`

Target a specific step and provide input as `