CLI reference

@boardwalk-labs/cli is the front door: scaffold, 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

New here? One command installs the CLI and wires up your coding agent: it logs you in, detects your agent (Claude Code, Codex, Cursor, OpenCode, OpenClaw), and installs its Boardwalk plugin and the control-plane MCP server. It never touches files in your project.

npx @boardwalk-labs/setup

Or install and authenticate by hand:

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 and inference providers)
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:

1. The --token flag.
2. The BOARDWALK_API_KEY environment variable (CI).
3. The stored login session.

The API host follows the same source: an explicit BOARDWALK_API_URL/BOARDWALK_API_DOMAINwins, 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 and wiring inference providers 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. Admin-only actions such as deleting a workflow work from any login, gated on your org role like everywhere else.

Command index

Every command, with the writes that need an elevated login (boardwalk login --scopes admin) called out:

boardwalk login

boardwalk login                  # browser OAuth (PKCE); least-privilege session
boardwalk login --scopes admin   # elevated: manage secrets and inference providers
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 live against 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>] [--python]

Scaffolds a workflow package (a workflow.jsonc descriptor, src/index.ts, README.md, package.json, tsconfig.json, and .gitignore) into dir (default: the current directory). --python scaffolds the Python shape instead (main.py + pyproject.toml). --template selects the starting point and defaults to the built-in hello, which works offline; other names come from the public examples registry. It also drops the Boardwalk agent skills into .claude/skills/ so a coding agent working in the project can drive the CLI. Never overwrites existing files.

boardwalk build

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

Builds the package into the exact content-addressed .tgz artifact a deploy uploads: the bundled entry (the SDK left external), the descriptor, the source tree, the skills/ + README.md + files assets, and the types harvest the backend derives the I/O schemas from. Defaults to <slug>.tgz in the current directory. You rarely need it directly; deploy and run build the same artifact themselves.

boardwalk check

boardwalk check <dir>

Validates the package locally with no network and no account: the descriptor validates against the schema (including the concurrency.key template syntax), the entry compiles and every import resolves, and the artifact packs. The I/O schemas themselves derive server-side at deploy, which returns any derivation warnings. Wire checkinto CI so a broken workflow can't merge.

boardwalk deploy

boardwalk deploy <dir> [--org <slug>] [--dry-run] [--yes]
                       [--run] [--input <json>] [--environment <name>] [--no-wait]

Creates the workflow (or a new version of it) on Boardwalk. The org resolves deterministically: --org, else a single-org credential's scope, else the project's .boardwalk/ link, else a hard error listing your orgs. A deploy that would create a new workflow asks first; --yes skips the prompt for CI. Add --dry-run to see the plan without deploying. Derivation warnings from the server (a field that degraded to raw JSON in the input form) are printed with the result.

--run is the authoring loop: it triggers the version you just shipped and waits for it, so one command covers ship-and-verify. --input supplies that run's payload, --environment picks its environment, and --no-wait returns as soon as it is triggered. Without --run, deploying never starts anything; it publishes the version and the next trigger picks it up.

A run pins its version when it is created, not when it starts, so a deploy applies to everything triggered after it lands and never to a run already queued or in flight. That is what you want for a run mid-flight, but it makes “deploy, then immediately fire a webhook” a race with your own deploy: a delivery that arrived seconds earlier executes the previous version, however long it waits in the queue. --run has no such race, since it triggers after the deploy returns.

boardwalk run

boardwalk run <workflow> [--org <slug>] [--input <json>] [--environment <name>] [--no-wait] [--json]

Runs a deployed workflow, named by its slug or its id. It reads nothing from your disk (no package, no build, no deploy), so it works from any directory on any machine that has a login. Reach for boardwalk deploy to ship code, and boardwalk deploy <dir> --run to do both in one step while you iterate.

It starts the run, polls the status to your terminal until it finishes (exit code 0 on success, 1 on failure), and prints the run's output. --input supplies the JSON payload passed to run(input); --no-wait returns immediately after triggering; --environmentpicks which environment's secrets and variables the run uses (default: the org base); --json emits { runId, status, ... } for scripting. --org is only needed when your login covers more than one org.

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 the run streamed (--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 webhooks

boardwalk webhooks                     # the org's inbound endpoints (no secrets)
boardwalk webhooks create <name>       # create one; the signing secret is shown ONCE
boardwalk webhooks rotate <name>       # new secret, shown ONCE; the old one stops working
boardwalk webhooks delete <name> --yes

A webhook is an org-level endpoint, not a property of one workflow: create it once, point a sender at its URL, then attach any number of workflows with a webhook trigger naming it. Every attached workflow runs on every delivery.

The secret is revealed a single time by create and rotate (elevated login) and is never shown again. For a sender that owns its own signing key (Stripe, Slack, Sentry…), pass it with --secret, or --secret - to read it from stdin so it stays out of your shell history. --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. disable pauses a workflow's triggers (and enable resumes them) without deleting it; delete is irreversible and guarded behind --yes (elevated login).

boardwalk workspace

boardwalk workspace show <workflow>     # what it stores across runs, per scope: size + last written
boardwalk workspace reset <workflow> --environment production --yes
boardwalk workspace reset <workflow> --key acme/app --yes

Inspect or clear a workflow's persistent workspace. reset clears one scope: --environment and --key pick which, and without --yes it prints what it would clear and exits. Every other scope, and the workflow, its triggers, and its run history, are untouched. It does not interrupt a run already in flight, and that run saves at the end, overwriting the reset.

boardwalk notifications

boardwalk notifications                 # newest first (--unread to filter, --limit <n>)
boardwalk notifications unread          # just the count, a bare number
boardwalk notifications read <id...>    # mark read by id, or --all

Your in-app notifications for the org: watched runs finishing, input requests waiting on you, billing notices. unread prints a bare count, which makes it easy to drop into a prompt or a status line.

boardwalk runner

boardwalk runner start --org your-org         # serve runs from THIS machine (default: containerized)
boardwalk runner start --pool gpu-fleet --labels cuda,a100
boardwalk runner register --url <origin> --token <bwkreg...>   # fleet install
boardwalk runner list                        # the org's runners: status, pool, labels, last seen
boardwalk runner remove <runnerId> --yes
boardwalk runner pools token --pool gpu-fleet  # one-time registration token (shown once, 1h TTL)

Attach your own machines to the hosted control plane as self-hosted runners. start is the whole setup on one machine: it registers the runner if needed and begins serving. --host drops container isolation and gives runs full machine access, so keep it for workflows you trust; --mount exposes specific host paths instead. register plus pools token is the fleet path, where the token is minted centrally and redeemed on each machine.

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.

set on a name that already exists replaces the value in place: same secret, same reference, so every workflow that reads it keeps working and nothing needs redeploying. That is how a mangled or expired credential gets repaired. A name that exists only inside an environment is edited there instead, since which environment was meant is ambiguous.

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: