CLI Commands
Reference for the canonical Breyta CLI lifecycle and docs navigation.
Quick Answer
Use this page when you need the command catalog.
- Default authoring path: Author Flows
- Broader docs map: Reference Index
- New user path: Start Here
Navigate By Goal
| If you need | Start here |
|---|---|
| Default authoring loop | Author Flows |
| Default draft/live lifecycle | Release And Install |
| Sell paid public flows | Paid Public Flows and Flow Metadata And Discover |
| Full docs map | Reference Index |
| Docs search query syntax | Docs Search |
| Flow file and step contracts | Flow Definition and Step Reference |
| Flow metadata, grouping, and public discover | Flow Metadata And Discover |
| Jobs workers and machine auth | Jobs Control Plane and Service Accounts |
| Flow-health incidents and digests | Flow Health |
| Table resources and limits | Table Resources |
| Connections/bindings | Connections First, Flow Configuration, Installations |
| Runs/outputs/resources | Runs And Outputs, Persisted Resources, Step Table |
| Limits/recovery/reporting | Limits And Recovery, Troubleshooting, Feedback |
Core Surface
| Command | What it does |
|---|---|
breyta docs | Show docs command surface (find, show, fields, sync). |
breyta docs find "flows" | Search docs pages. Supports terms, quoted phrases, field filters, and boolean operators. See Docs Search. |
breyta docs show <slug> [--section <heading>] [--full] | Show compact page preview, one section, or full page. |
breyta docs fields <step-or-doc> [field ...] | Show compact config field rows. Add fields such as response-as persist retry for targeted lookup. |
breyta docs sync --out ./.breyta-docs --clean | Download docs corpus for offline grep/search. |
breyta flows search <query> | Search workspace flow metadata and summaries. Refine with --step-type, --provider, --connection, or --flow. |
breyta flows grep <pattern> | Search workspace flow source by literal pattern. Use --or, --surface, or --scope to narrow. |
breyta flows templates search <query> [--limit 5] | Search approved templates. Use --full for bounded source preview. |
breyta flows templates grep <pattern> | Search approved template source. Use --surface and --full to narrow or expand. |
breyta flows discover list | Browse public installable end-user flows for the current workspace. Add --include-own only when debugging whether this workspace's own public flows are indexed. |
breyta flows discover search <query> | Search public installable end-user flows for the current workspace. Add --include-own only for owner-side indexing checks. This is separate from workspace flow search and approved template search. |
breyta connections list [--type ...] | List reusable workspace connections. |
breyta connections usages [--connection-id <id>] [--flow <slug>] [--only-connected] | Show which flow targets (draft/live/installation) currently use each connection. |
breyta connections items <connection-id> [--item-type <type>] [--raw] | Inspect cached non-secret provider items used by dropdowns. |
breyta connections create ... | Create a new connection when no reusable one exists. |
breyta connections test <connection-id> | Test one connection health directly. This confirms health/config state, not end-to-end step execution. |
breyta connections test --all [--only-failing] | Run workspace-wide connection health checks before wiring. This is a preflight check, not runtime proof. |
breyta connections delete <connection-id> | Delete an unbound connection. If still bound, CLI returns a hint to move/unset bindings first. |
breyta secrets list [--secret-id <id>] | List workspace secret IDs. |
breyta secrets usages [--secret-id <id>] [--flow <slug>] [--only-connected] | Show which flow targets (draft/live/installation) currently reference each secret. |
breyta secrets delete <secret-id> | Delete an unbound secret. If still bound, CLI returns a hint to move/unset bindings first. |
breyta flows list [--limit 10] [--pretty] | List workspace flows with a compact default limit. See Flow Metadata And Discover for grouped-flow fields and metadata. |
breyta flows show <slug> [--pretty] | Show one flow with compact metadata, counts, step/trigger summaries, and a non-editable flowLiteralPreview when source is available. Use --full or --include definition for full source fields. |
breyta flows delete <slug> --yes [--force] | Permanently delete a flow. Use --force when runs/installations must be cleaned up. |
breyta flows marketplace update <slug> --visible=true | Enable marketplace visibility metadata after explicit author approval and installable-ready proof. Use --visible=false to disable. |
breyta flows discover update <slug> --public=true | Enable public discover visibility metadata after explicit author approval and installable-ready proof. Use --public=false to disable. |
breyta flows update <slug> ... | Update mutable flow metadata such as grouping, discover card media, display-icon selection, and publish description. |
breyta flows pull <slug> --out ./tmp/flows/<slug>.clj | Pull definition to local file. |
breyta flows lint --file ./tmp/flows/<slug>.clj [--local-only\|--server] | Lint candidate source before push. Local lint is offline and fast; server lint is canonical and non-mutating. |
breyta flows push --file ./tmp/flows/<slug>.clj | Push working copy. |
breyta flows diff <slug> | Show draft-vs-live source diff. Draft-only flows with push history fall back to previous pushed draft vs current draft. |
breyta flows readiness <slug> [--target draft\|live] [--public] [--marketplace] | Compact readiness report with blockers and next commands. Defaults to draft; use live or release-check for release proof. |
breyta flows release-check <slug> [--public] [--marketplace] | Check live release readiness. Use public/marketplace flags for end-user release gates before publication or paid marketplace changes. |
breyta flows configure suggest <slug> [--target live] | Suggest --set bindings from existing connections and show unresolved slots. |
breyta flows configure <slug> --set ... | Configure draft runtime target (bindings/inputs) when required. For live, use --target live and optional --version <n|latest>. |
breyta flows configure check <slug> | Check required bindings/inputs for draft target. For live, use --target live and optional --version <n|latest>. |
breyta flows validate <slug> | Optional read-only validation (useful for CI/troubleshooting/explicit target checks). |
breyta flows run <slug> --wait | Start a run using draft-target bindings/config by default. Code version comes from the active release unless --version overrides it. |
breyta flows run <slug> --invocation <id> --input '{...}' --wait | Start a specific invocation contract directly. |
breyta flows interfaces list <slug> --target live | List manual/HTTP/webhook/MCP interface surfaces declared over invocations. |
breyta flows interfaces show <slug> <interface-id-or-tool-name> --target live | Inspect one interface, including invocation input metadata and endpoint details when available. |
breyta flows metrics <slug> --source draft\|live | Inspect redacted aggregate metrics for author-owned draft/live interface calls. Use --installation-id <id> for one installation. |
breyta flows interfaces call <slug> <http-interface-id> --input '{...}' --wait | Smoke-test the draft author HTTP interface route. Add --target live for the author live route or --installation-id <id> for a specific installation. |
breyta flows interfaces curl <slug> <http-interface-id> --target live --input '{...}' | Generate a copyable curl command for an HTTP interface without printing the real token. Omit --target for draft. |
breyta steps run --flow <slug> --source draft --type <type> --id <step-id> --params '<json>' | Run one step with draft context. Output is compact and includes a binding preview. |
breyta steps run ... --params-file ./params.json --result-path rows.0 | Run one step with larger params and focused preview. Use preview flags, --result-file, or --full to expand. |
breyta steps record --flow <slug> --source draft --type <type> --id <step-id> --params '<json>' | Run one step and save observed input/output as a step example and snapshot test once behavior is stable. |
breyta steps tests verify <slug> <step-id> --source draft | Re-run stored step tests. Use preview flags or --full for expansion. |
breyta runs list --query 'status:failed flow:my-flow installation:inst-1 version:7' | List runs with the canonical structured filter syntax. |
breyta runs list --installation-id <installation-id> --version <n> | List runs with legacy discrete filter flags. |
breyta runs show <workflow-id> | Inspect one run in detail. |
breyta runs events <workflow-id> [--step <step-id>] [--installation-id <id>] [--limit <n>] | Inspect a bounded run and step event timeline for live debugging. |
breyta runs inspect <workflow-id> [--step <step-id>] | Inspect a run with compact step data, or inspect one step's input/output/error/cost without expanding the whole run payload. |
breyta runs step <workflow-id> <step-id> [--full] [--installation-id <id>] | Short alias for compact step I/O inspection, including the step event timeline when available. |
breyta runs continue <workflow-id> --approve-latest-wait | Approve the latest active approval wait for a waiting workflow, then inspect the run again with runs show or runs inspect. |
breyta waits list [--flow <slug>] [--workflow-id <id>] | List live human-in-the-loop waits and approval requests. |
breyta jobs create --type <job-type> [--payload '{...}'] [--metadata '{...}'] | Create one queued external job. |
breyta jobs list [--type <job-type>] [--batch-id <batch-id>] [--status <status>] [--limit <n>] | List jobs with optional type, batch, status, and limit filters. |
breyta jobs show <job-id> | Show durable job state and persisted outputs/artifacts. |
breyta service-accounts list [--status active\|disabled] | List workspace service accounts. |
breyta service-accounts create --name <name> --scope <scope>[,<scope>] [--scope <scope>] [--job-type <job-type>] | Create a workspace service account with explicit scopes. --scope accepts repeated flags or comma-separated values. --capability remains a compatibility alias. |
breyta service-accounts keys create <service-account-id> --name <key-name> | Mint a service-account API key. |
breyta service-accounts keys revoke <service-account-id> <key-id> | Revoke one service-account API key without deleting the service account. |
breyta jobs batches create --type <job-type> --job '{...}' [--job '{...}'] | Create a batch of queued jobs of one type. |
breyta jobs batches show <batch-id> | Show one batch, including aggregate counts and any included jobs. |
breyta jobs claim --type <job-type> --worker-id <worker-id> [--lease-duration 2m] | Claim one job lease for a worker capable of that job type. |
breyta jobs progress <job-id> --lease-token <lease-token> | Report active job progress while a lease is held. |
breyta jobs complete <job-id> --lease-token <lease-token> | Mark a leased job terminal with structured outputs, metrics, and artifacts. |
breyta jobs fail <job-id> --lease-token <lease-token> | Mark a leased job failed with structured error details and artifacts. |
breyta jobs worker run --type <job-type> --handler ./handler | Run a polling worker loop for one job type. |
breyta jobs worker state [--job-dir /tmp/breyta-job-...] | Show local worker state for the active job or a kept job directory. |
breyta jobs worker progress --status running --message "..." | Report progress for the active worker job. |
breyta jobs worker attach-file --file ./report.md --label review-report | Attach a file resource to the active worker job. |
breyta jobs worker attach-kv --label review-summary --field finding-count=1 | Attach structured key-value data to the active worker job. |
breyta jobs worker attach-table --label findings --rows-file ./findings.json | Attach row-shaped output as a table resource for the active worker job. |
breyta jobs worker finish --summary "..." --output key=value | Write local success or no-op worker result state. |
breyta jobs worker fail --message "..." --code my_error | Write local failed worker result state. |
breyta incidents list [--status open\|acknowledged\|recovered\|suppressed-until-recovered] [--mine] | List workspace flow-health incidents, or limit to flows you created with --mine. |
breyta incidents show <incident-id> [--failure-limit <n>] | Show one incident with first-class failure rows. |
breyta incidents lanes <incident-id> [--limit <n>] | Show affected lanes or keys for one incident. |
breyta incidents acknowledge <incident-id> | Mark an incident as seen without claiming it recovered. |
breyta incidents snooze <incident-id> --for 30m\|2h\|1d | Temporarily suppress incident surfacing for a bounded window. |
breyta incidents suppress <incident-id> | Suppress an incident until the runtime proves it recovered. |
breyta digests list [--kind immediate\|scheduled] [--status materialized] [--cadence daily\|weekly\|monthly] | List digest/update artifacts and optionally filter scheduled digests by cadence. |
breyta digests show <digest-id> | Show one digest summary and its incident rollup. |
breyta digests deliveries <digest-id> [--channel in-app\|email] | Show per-recipient in-app/email delivery state for a digest. |
breyta digests mark-read <digest-id> | Mark an in-app digest update as read for the current user. |
breyta digests cadence | Show the current scheduled digest cadence and settings deep link for the workspace/user. |
breyta digests cadence set daily\|weekly\|monthly | Update the scheduled digest cadence for the current workspace/user. |
breyta resources list [--query "<text>"] [--types file,result] | List persisted resources with picker-style filters. |
breyta resources search "<query>" [--limit 10] [--type result|file] | Search workspace files and persisted blobs. Defaults are compact. |
breyta resources read <res://...> [--limit 100] [--full] | Read content or preview a table. Use --full for full payloads. |
breyta resources table query <uri> [--page-mode offset|cursor] [--limit 100] | Query one table. Add select/where/sort/partition flags as needed. |
breyta resources table get-row <uri> (--row-id <id> \| --key order-id=ord-1) [--partition-key <key>] | Fetch one row by row id or keyed lookup. |
breyta resources table aggregate <uri> --metrics-json '[...]' | Run a bounded aggregate on one table resource. Add where/group/order/partition flags as needed. |
breyta resources table schema <uri> [--partition-key <key> \| --partition-keys <k1,k2>] | Show schema, indexes, family stats, and partition summaries. |
breyta resources table export <uri> [--out orders.csv] [--partition-key <key> \| --partition-keys <k1,k2>] | Export a table resource as CSV. |
breyta resources table import <uri-or-table-name> --file orders.csv | Import CSV rows. Use --write-mode upsert --key-fields ... for keyed upserts. |
breyta resources table update-cell <uri> (--row-id <id> \| --key order-id=ord-1) --column status (--value closed \| --value-json 'true') [--partition-key <key>] | Update one table cell value. |
breyta resources table update-cell-format <uri> ... | Add or clear one sparse formatting override for a cell. |
breyta resources table set-column <uri> --column customer-name ... | Create or update one logical column definition. |
breyta resources table recompute <uri> [--where-json '[[\"status\",\"=\",\"open\"]]'] [--limit 1000] [--offset 0] [--partition-key <key> \| --partition-keys <k1,k2>] | Recompute materialized values for existing rows. |
breyta resources table materialize-join --left-json '{...}' --right-json '{...}' --on-json '[...]' --into-json '{...}' | Materialize a bounded key-based join into a destination table. |
breyta feedback send --title "..." --description "..." | Send issue/feature feedback to the Breyta team. |
Resource Share API
Public artifact preview shares are API-only today. Use them when an external
recipient should view a generated artifact without logging in.
| API route | Purpose |
|---|---|
POST /api/resources/shares | Create an unlisted no-login preview link for a workspace-owned resource. Body accepts uri or resourceUri, optional title, optional ttlSeconds, optional same-origin relative claimUrl, and optional allowDownload. Requires X-Breyta-Workspace. |
GET /public/artifact-previews/:token | Open the sanitized read-only public preview page. |
GET /public/artifact-previews/:token/download | Download a text-like shared artifact when the share was created with allowDownload: true, such as EDN, Markdown, CSV, JSON, XML, JavaScript, form data, or plain text. Uses the same unlisted, revocable, expiring token. |
DELETE /api/resources/shares/:token | Revoke a preview link. Requires X-Breyta-Workspace. |
Use breyta resources url <res://...> only for temporary signed direct
resource access. It is not the outreach preview URL.
Command Notes
- Jobs workers, helper commands, and worker output contracts:
Jobs Control Plane - Service-account creation, API keys, and service-account scopes:
Service Accounts - Grouping metadata, display-icon selection, publish description, and public
discover:
Flow Metadata And Discover - Paid public flow publishing and Stripe seller onboarding:
Paid Public Flows - Incident, digest, and cadence behavior:
Flow Health - Storage filters, table-resource behavior, partitioning, and table-family
limits:
Table Resources - Delete guards for connections and secrets are binding-based
(draft/live/installation). Delete stays blocked until old bindings
are moved or unset.
Advanced Rollout Commands
| Command | Use |
|---|---|
breyta flows release <slug> | Create immutable release. Use --release-note-file; configure live bindings first for required slots. |
breyta flows promote <slug> | Promote a release to live installation scope. |
breyta flows versions update <slug> --version <n> | Update mutable version metadata such as the markdown releaseNote. |
Advanced Install Commands
| Command | Use |
|---|---|
breyta flows installations list <flow-slug> | List installations for a flow. |
breyta flows installations create <flow-slug> --name "..." | Create an installation. |
breyta flows installations create <flow-slug> --source-workspace-id <ws> --local-private-test | Local dev only: test a private cross-workspace install without public visibility. |
breyta flows installations get <installation-id> | Inspect installation state (installedVersion, latestAvailable, updateAvailable, policy). |
breyta flows configure <flow-slug> --schedules '{...}' | Set author-owned schedule defaults for setup schedules. |
breyta flows configure <flow-slug> --schedule-enable <schedule-id> / --schedule-disable <schedule-id> | Toggle one author-owned schedule override. |
breyta flows configure <flow-slug> --schedule-reset <schedule-id> | Remove one author-owned schedule override and inherit the flow default. |
breyta flows installations configure <installation-id> --input '{...}' | Set installation inputs/config. |
breyta flows installations configure <installation-id> --schedules '{...}' | Set installer-owned schedule settings for setup schedules. |
breyta flows installations configure <installation-id> --schedule-enable <schedule-id> / --schedule-disable <schedule-id> | Toggle one installer-owned schedule. |
breyta flows installations configure <installation-id> --schedule-reset <schedule-id> | Remove one installer-owned schedule override and inherit the flow/default setup schedule. |
breyta flows installations enable <installation-id> / disable | Enable or pause the installation. Disabled installations reject manual runs, interface calls, and schedules while preserving per-schedule and per-interface settings. |
breyta flows installations interfaces <installation-id> | Show manual/HTTP/webhook/MCP interface surfaces available on the installed flow version. |
breyta flows installations upload <installation-id> --file ./a.pdf | Upload files to an installation webhook interface. |
breyta flows installations delete <installation-id> | Delete installation. |
New end-user installations default to track-latest.
breyta flows release <slug> always promotes the live target and also promotes track-latest installations by default. Use --skip-promote-installations when you only want the live promotion step.
Recommended release-note flow:
- inspect changes first:
breyta flows diff <slug> - release with markdown note:
breyta flows release <slug> --release-note-file ./release-note.md - edit later if needed:
breyta flows versions update <slug> --version <n> --release-note-file ./release-note.md
Functional Split: Draft Vs Live
| Aspect | draft | live |
|---|---|---|
| Definition source | Latest pushed working copy | Installed released version |
| What updates it | breyta flows push --file ... | breyta flows release <slug> / breyta flows promote <slug> |
| Default run target | Yes (breyta flows run <slug>) | No (must use --target live or --installation-id) |
| Primary intent | Fast authoring iteration | Stable installed runtime behavior |
Run Flag Matrix
breyta flows run <slug> defaults to draft-target bindings/config resolution. If the flow has never been released and you hit no_active_version, run the mutable draft explicitly with --target draft during authoring, or release the flow first.
| Need | Flags |
|---|---|
| Default draft target bindings/config | none |
| Brand-new unreleased draft | --target draft |
| Installed live target (advanced) | --target live |
| Exact installation (advanced) | --installation-id <id> |
| Explicit release version | --version <n> |
| Runtime input payload | --input '{...}' |
| Wait for completion | --wait (plus optional --timeout, --poll) |
--target selects which bindings/config target to use. It does not switch execution to the mutable draft definition.
For new flows, declare per-run fields under :invocations and expose human launch
with :interfaces :manual; pass values with --input.
Older manual field shapes remain executable for compatibility, but new source
and new docs should use :invocations plus :interfaces :manual.
breyta flows release <slug> updates live installation for the selected workspace by default, but does not change the default run target. Use --target live or --installation-id when you need installation runtime behavior.
breyta runs list supports the same structured filter tokens as the web runs list:
status:<running|completed|failed|waiting>flow:<slug>installation:<installation-id>version:<n>
Docs Search
Use Docs Search for the full query model.
Quick examples:
| Query pattern | Command |
|---|---|
| Step config overview | breyta docs fields http |
| Selected step fields | breyta docs fields http response-as persist retry --format json |
| Operation-specific step fields | breyta docs fields files source paths --section read |
| Plain terms | breyta docs find "flows push" |
| Source filter | breyta docs find "source:cli release" |
| Phrase + boolean | breyta docs find "\"end-user\" AND source:flows-api" |
| Pagination | breyta docs find "install" --limit 20 --offset 20 |
| Snippets/explain | breyta docs find "release" --explain --format json |
Compatibility Surface
Legacy command aliases remain executable for compatibility but are not part of
the canonical command surface. New callable ingress should use :interfaces and
breyta flows installations interfaces <installation-id>.
Related
- Start Here
- Author Flows
- Debug And Verify
- Release And Install
- CLI Workflow
- CLI Essentials
- Reference Index
- Docs Search
- Flow Metadata And Discover
- Flow Health
- Flow Definition
- Jobs Control Plane
- Service Accounts
- Table Resources
- Flow Configuration
- Connections First
- Installations
- Paid Public Flows
- Profiles
- Runs And Outputs
- Persisted Results And Resource Refs
- Step Table
- Flow Grouping
- Troubleshooting
- Feedback And Reporting
- CLI Skills