CLI reference

@boardwalk-labs/cli is the front door: scaffold, run locally, validate, deploy, trigger, cancel. Open source (MIT, source). The listing and inspection commands (runs, workflows, secrets, inference, usage) accept --json for piping into your own tooling.

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 login

boardwalk login                  # browser OAuth (PKCE); least-privilege session
boardwalk login --scopes admin   # elevated: manage secrets/providers, delete workflows
boardwalk login --token bwk_...   # store an API key instead of the browser flow

Authenticates and stores the session locally (auto-refreshing when it expires). The browser flow is standard OAuth 2.0 authorization-code with PKCE; --token stores a bwk_ API key for non-interactive use. The default session is least-privilege; --scopes admin opts into the elevated tier the write commands below require, and you must be an org admin to get it.

boardwalk whoami

boardwalk whoami

A quick, local check of the stored session: the auth method (API key or OAuth), its scope, and its expiry. No network call. For a live check against the platform, use status below.

boardwalk logout

boardwalk logout

Removes the stored credentials. The next network command will prompt you to log in again.

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 starter workflow (an index.ts, package.json, .env.example, and .gitignore) into dir (default: the current directory). --template selects the starting point and defaults to the built-in hello. Never overwrites existing files.

boardwalk dev

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

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).

An agent() call that names no provider uses Boardwalk's managed models, which the local engine reaches with a short-lived key minted from your boardwalk login session (billed to --org, or the project link's org). So a managed agent run needs a one-time login; an agent-free workflow, or one that names its own provider key, runs with no account.

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>] [--environment <name>] [--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. --environmentpicks which environment's secrets and variables the run uses (default: the org base).

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, since 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 inputs

boardwalk inputs                 # the org-wide inbox of inputs awaiting a response
boardwalk inputs <runId>         # just one run's pending inputs
boardwalk inputs --json

Lists the human-in-the-loop gates waiting on a person: a run that called humanInput()pauses and appears here until someone answers. With no argument it's the org-wide inbox; pass a runId to scope it to one run.

boardwalk respond

boardwalk respond <runId> <key> --value "ship it"         # a text or single-choice gate
boardwalk respond <runId> <key> --values approve,notify   # a multi-select gate
boardwalk respond <runId> <key> --other "something else"  # the open "Other..." entry

Answers a pending input by its key (from boardwalk inputs) and resumes the run once every input in its batch is answered. Use --value for a text or single-choice gate, --values for a multi-select, and --other for the open-text entry a choice gate allows.

boardwalk webhook

boardwalk webhook <id|slug>            # show the inbound webhook URL for a webhook-triggered workflow
boardwalk webhook <id|slug> --rotate   # regenerate the secret and reveal the working URL once

For a workflow with a webhook trigger, prints its inbound URL so you can wire up the sender. --rotate regenerates the secret and reveals the full working URL a single time (it is never shown again); rotating needs an elevated login. --json emits the raw response.

boardwalk workflows

boardwalk workflows                    # the org's workflows (slug, title, triggers, last run)
boardwalk workflows show <id|slug>     # manifest projection + version history
boardwalk workflows disable <id|slug>  # pause every trigger (reversible)
boardwalk workflows enable <id|slug>   # resume a disabled workflow's triggers
boardwalk workflows delete <id|slug> --yes

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

boardwalk secrets

boardwalk secrets                                  # names/scope/kind only, never VALUES
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). set also takes --scope (org or user), --kind (api_key, oauth_token, aws_role, mcp_credential), and --description. Writing and deleting need an elevated login.

boardwalk environments

boardwalk environments                  # the org's named environments
boardwalk environments create Production
boardwalk environments delete Production --yes

Manage the org's named environments — config sets a run targets by name (the org base always applies underneath). A run picks one with boardwalk run --environment <name>; it is not a manifest field. Creating and deleting need an elevated login.

boardwalk variables

boardwalk variables                                    # non-secret config (VALUES are shown)
boardwalk variables set POSTHOG_PROJECT_ID 394895 --environment Production
boardwalk variables list --environment Production
boardwalk variables delete REGION --yes

Manage non-secret variables — injected into a run as process.env values (read them with process.env.NAME). --environment scopes a variable to one environment (omit for the org base). Use secrets for credentials — never store a secret as a variable. 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. Depending on the source, add takes --base-url (OpenAI-compatible and Azure), --region (Bedrock), --api-version (Azure), and --api-key (prefer piping it via stdin). API keys are staged server-side and never returned. Adding and deleting need an elevated login.

boardwalk models

boardwalk models                          # the most-capable head of the managed catalog
boardwalk models list --all               # every model an agent() call can route to
boardwalk models list --search claude     # filter by id or display name
boardwalk models show anthropic/claude-opus-4.8

Browse the managed-lane model catalog an agent({ model }) call can run on, with prices. list (the default) shows the most-capable head unless you pass --all, and takes --search; show <id>prints one model's price, context window, and feature support. Add --json for the raw records.

Environment

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