CLI reference

@boardwalk-labs/cli is the front door: scaffold, run locally, validate, deploy, trigger, cancel. Open source (MIT, source).

Install & auth

npm install -g @boardwalk-labs/cli

boardwalk login                 # browser OAuth; stores a scoped, least-privilege token
boardwalk login --scopes admin  # opt-in elevated session (manage secrets/providers, delete workflows)
boardwalk status                # host + login (verified live) + project link
boardwalk whoami                # quick local check of the stored session
boardwalk logout                # remove local credentials

Commands that talk to Boardwalk resolve credentials in this order: --token flag, the BOARDWALK_API_KEY environment variable (CI), then the stored login session. The API host follows the same source: an explicit BOARDWALK_API_URL/BOARDWALK_API_DOMAIN wins, otherwise the stored session's own origin (so logging into a dev or self-hosted stack just works), then the default.

The default login is least-privilege — deploy, trigger and read runs, and list secrets/providers (names and endpoints only, never values). Writing secrets, wiring inference providers, and deleting workflows need an elevated session (boardwalk login --scopes admin); you must be an org admin. Even elevated, a CLI token can never mint a full-power API key or manage members.

boardwalk status

boardwalk status [--token <token>]

A one-stop check of how the CLI is wired up: which API host you're pointed at (and the environment variable that set it, so dev, prod, and self-host are never ambiguous), your login state verified liveagainst the platform (it confirms the credential actually works and names your account and orgs), and the workflow this directory is linked to. It degrades gracefully when you're offline or logged out, and exits non-zero when there's no usable credential or the server rejects it, so it's safe to gate a script on. whoami stays the quick, local check of the stored session.

boardwalk init

boardwalk init [dir] --template <name>

Scaffolds a workflow project into dir (default: the current directory). --template is the built-in hello or any template from the examples registry, like morning-digest or claude-code-cron. Never overwrites existing files.

boardwalk dev

boardwalk dev <file|dir> [--input <json>] [--env <path>] [--verbose] [--stream <channels>]

Executes the workflow right now, locally, streaming the run log to your terminal. Secrets resolve from .env (or --env); --input supplies a trigger payload; --verbose streams every event channel including raw agent turns and tool calls. --stream picks channels precisely: a comma-separated list of lifecycle,phase,output,log,agent (e.g. --stream output for just the result, pipe-friendly).

boardwalk build

boardwalk build <file|dir> [--out <path>]

Bundles the workflow to a single deployable .mjs (the SDK left external, meta intact). This is what a self-hosted server loads from its BOARDWALK_WORKFLOWS_DIR. Defaults to <slug>.mjs in the current directory. See Self-hosting.

boardwalk check

boardwalk check <file|dir>

Validates locally with no network: the program compiles and meta derives a valid manifest. Wire it into CI so a broken workflow can't merge.

boardwalk deploy

boardwalk deploy <file|dir> --org <slug>

Creates the workflow (or a new version of it) on Boardwalk. The project directory keeps a .boardwalk/ link file so later deploys update the same workflow even if you rename it. Add --dry-run to see the plan without deploying.

boardwalk run

boardwalk run <file|dir> --org <slug> [--input <json>] [--no-wait]

Deploy plus trigger: ships the current file, starts a run, and polls the status to your terminal until it finishes (exit code 0 on success, 1 on failure). --no-wait returns immediately after triggering.

boardwalk cancel

boardwalk cancel <runId>

Cancels a queued or in-flight run. Cancellation is cooperative first (the program can clean up), then forceful after a grace period.

boardwalk usage

boardwalk usage --org <slug> [--days <n>] [--json]

Prints your org's usage: runs, compute, tokens, credit, autonomy, and cache-hit rate. --days sets the window (server default ~14, capped at 90); --json emits the raw summary for piping into your own tooling.

boardwalk runs

boardwalk runs [--org <slug>] [--workflow <id|slug>] [--status <status>] [--limit <n>]
boardwalk runs <runId>            # one run's summary (status, duration, tokens, error)
boardwalk runs <runId> --logs     # its event log (--verbose / --stream for tools + raw turns)
boardwalk runs <runId> --follow   # live-tail over SSE until it finishes (Ctrl-C aborts)

Lists your org's recent runs, or acts on one run by id (no --org needed — the run resolves its own org). --workflow scopes the list to a single workflow; --status filters it. --logsprints the run's event log and --follow live-tails it, both rendering the same channels as dev (--verbose or --stream to see agent turns and every tool call).

boardwalk workflows

boardwalk workflows                    # the org's workflows (slug, title, triggers, last run)
boardwalk workflows show <id|slug>     # manifest projection + version history
boardwalk workflows delete <id|slug> --yes

Inspect the org's workflows from the terminal. show accepts a workflow id (a ULID, as in a dashboard URL) or a slug; delete is irreversible and guarded behind --yes. Deleting needs an elevated login.

boardwalk secrets

boardwalk secrets                                  # names/scope/kind only — VALUES are never shown
echo "$TOKEN" | boardwalk secrets set GITHUB_TOKEN # stage a value (piped → out of shell history)
boardwalk secrets set DEPLOY_KEY --from-file ./key # …or from a file (--value also accepted)
boardwalk secrets delete GITHUB_TOKEN --yes

Manage the org's secrets. Values never touch argv by default — pipe them or pass --from-file so they stay out of shell history, and no surface ever returns a value (the list shows a last-4 hint). Writing and deleting need an elevated login.

boardwalk inference

boardwalk inference                                       # BYO providers (endpoints only, never keys)
echo "$KEY" | boardwalk inference add my-openai --source openai
boardwalk inference add vllm --source openai_compatible --base-url https://vllm.internal
boardwalk inference delete my-openai --yes

Manage the org's BYO inference providers (the endpoints an agent({ provider }) call routes to). Sources: bedrock, anthropic, google, openai, openai_compatible, azure_openai. API keys are staged server-side and never returned. Adding and deleting need an elevated login.

Environment

A few environment variables override defaults, mostly for CI and self-hosting: