> ## Documentation Index
> Fetch the complete documentation index at: https://docs.asteroid.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI reference

> Every asteroid command, its arguments and its flags

Sign in with `asteroid login`, or set `ASTEROID_API_KEY` for CI and agents.
Commands that return data print compact text. Add `--json` to get the response as JSON.
The text output may change between releases. Scripts should read `--json`.
At a terminal, tables show up to 6 columns and cut long cells to fit; when output is piped, they show every column in full. Use `--json` for every field.
Downloads write raw bytes. `login`, `logout`, `use` and `skill sync` only report status on stderr.
Exit codes: 0 ok, 1 API error, 2 usage error.

## Global flags

* `--json`: Print the response as JSON.
* `--org <id|name>`: Act in this organization for one command. Also ASTEROID\_ORG.
* `--body <json|@file|->`: Request body as JSON, a file, or stdin. Flags override its fields.
* `--output <file>`: Write a downloaded file here, not to stdout.
* `-h, --help`: Show help.

## Account

### `asteroid login`

Sign in with your browser. Stores a refresh token in the OS keychain, or in a private file in the config directory when no keychain is available. Then offers to install the Asteroid skills into every skills directory it finds: `~/.claude/skills` (Claude Code), `~/.cursor/skills` (Cursor) and `~/.agents/skills`.

* `--no-skills`: Do not offer to install the Asteroid skills.

### `asteroid logout`

Forget the stored sign-in and cached tokens.

### `asteroid orgs`

List the organizations you can act in. The active one is marked.

### `asteroid use [org]`

Make an organization, by id or name, the default for later commands. Without one, pick from a list.

### `asteroid complete <zsh|bash|fish|powershell>`

Print a shell completion script. For zsh: `asteroid complete zsh > ~/.zfunc/_asteroid`.

### `asteroid whoami`

Show who you act as, in which organization, and how long the token lasts.

### `asteroid auth token`

Print the access token the CLI sends for the active organization, refreshed from your sign-in when needed. Like `gh auth token`, it lets a script call the API as you: `curl -H "Authorization: Bearer $(asteroid auth token)" ...`. A sign-in token lasts a few minutes, so fetch it right before each call. With staff access from `asteroid use --reason`, it prints the staff token, which lasts up to 8 hours. With `--json`, also prints when it expires, which organization it acts in and whether it is a staff token. Unset `ASTEROID_API_KEY` first: an API key has no access token, so the command refuses it.

## Skills

### `asteroid skill sync`

Install the Asteroid skills, or bring them up to date, in every skills directory found: `~/.claude/skills`, `~/.cursor/skills` and `~/.agents/skills`. Writes the files that changed, removes the skills the API no longer serves, and leaves a skill directory it did not create alone. Do not edit an installed skill, because the next sync overwrites it. If a skill is missing something about how a portal works, save it with `asteroid memory create`.

* `--no-remove`: Keep the skills and files the API no longer serves.

## Commands

### `asteroid api-key list [flags]`

List the organization's API keys, newest first: name, obfuscated value, creator, created, last used and expiry. Values never appear. Use it to check that a key exists before deploying. Keys are created in the platform; `organizationId` defaults to the caller's one organization.

### `asteroid batch cancel <batch-id> [flags]`

Cancel a batch and every item it has not yet triggered. Runs already started continue. A cancelled batch cannot be resumed.

* `<batch-id>`

### `asteroid batch create [flags]`

Queue one execution per row of `items` for `workflowId`, starting at `startAt` (ISO 8601; now or earlier starts at once). `config` paces the runs: `{type: "maxConcurrent", maxConcurrent}` or `{type: "timeBatching", batchSize, batchInterval}` (seconds). Each item takes `inputs` (see `workflow_version_inputs_get`), optional `profileId` or `profileGroupId`, `metadata`, and `workflowVersionId` to pin a version. Check the same body first with `execution_batch_validate`. Returns the batch; follow it with `execution_batch_get`, and its runs with `executions_list` filtered by `batchId`.

* `--workflow-id <string>`: Workflow ID for this batch. Set this or agentId.
* `--name <string>`: (required)
* `--start-at <string>`: When to start triggering executions (required)
* `--config <json>`: Discriminated union of batch configuration types (discriminated by type) (required)
* `--items <json>`: (required)

### `asteroid batch get <batch-id> [flags]`

Get one batch with its status and counts: pending, triggered, awaiting capacity, cancelled, failed and total. List its items with `scheduled_executions_list` filtered by `batchId`.

* `<batch-id>`

### `asteroid batch list [flags]`

List the execution batches for a workflow (`workflowId` is required), optionally by `status`. A batch is a set of queued executions with shared timing and concurrency settings.

* `--workflow-id <string>`: Filter by workflow ID. Set this or agentId.
* `--status <pending|running|paused|completed|cancelled>`: Execution batch status
* `--page-size <integer>`
* `--page <integer>`

### `asteroid batch pause <batch-id> [flags]`

Pause a running batch. Items not yet triggered wait; runs already started continue. Resume with `execution_batch_resume`.

* `<batch-id>`

### `asteroid batch resume <batch-id> [flags]`

Resume a paused batch. Trigger times for the remaining items are recalculated from now.

* `<batch-id>`

### `asteroid batch validate [flags]`

Check an `execution_batch_create` body without creating anything. Returns `valid`, `itemCount`, and `issues`: each row (by its 0-based `index` in `items`) whose inputs would fail the input schema of the version it runs. A problem with the whole batch, such as an empty `items` or a bad `config`, returns the same error create would.

* `--workflow-id <string>`: Workflow ID for this batch. Set this or agentId.
* `--name <string>`: (required)
* `--start-at <string>`: When to start triggering executions (required)
* `--config <json>`: Discriminated union of batch configuration types (discriminated by type) (required)
* `--items <json>`: (required)

### `asteroid billing balance [flags]`

Get the organization's credit balance broken down by pool (plan credits, top-ups, free credits), its contracts, the current period and the active contract's rates.

### `asteroid billing capabilities [flags]`

Get what the organization's plan and granted exceptions allow, such as Windows environments or concurrency limits, and for each missing one the cheapest tier that adds it. Use it to explain why a feature is locked.

### `asteroid billing credit [flags]`

Get how urgently the organization needs credit. `band` is ok, low, critical or depleted. Also returns the balance, daily spend, when credit runs out (`runsOutAt`), when it renews, why runs are blocked (`blockedReason`), auto top-up state, and `suggestedTier` when recent spend suits a bigger plan. Use it to warn before runs stop or to explain why they stopped. Cached for up to 60 seconds. Top-ups and plan changes happen in the platform app's billing page.

### `asteroid billing executions [flags]`

List raw usage per execution in the organization, newest first: LLM tokens, environment seconds and proxy bytes. Pass `executionId` for one execution. Page with `page` and `pageSize`. Costs are not returned: price usage with the rates from billing\_info\_get.

* `--execution-id <string>`: Only the row for this execution.
* `--page-size <integer>`
* `--page <integer>`

### `asteroid billing invoices [flags]`

List the organization's finalized invoices, newest first, with amount, status, period and links to the hosted invoice page and PDF where the payment provider has them.

### `asteroid billing subscription [flags]`

Get the organization's active subscription: plan name, monthly fee, start date, and any pending downgrade or cancellation (`pendingPlanName`, `finishedAt`). Plan changes and card updates happen in the platform app's billing page.

### `asteroid billing usage [flags]`

Get the organization's usage between `startingOn` (inclusive) and `endingBefore` (exclusive), in `hour` or `day` buckets: LLM tokens, environment time and proxy bytes. For usage per execution, use billing\_execution\_usage\_list. Costs are not returned: price usage with the rates from billing\_info\_get.

* `--starting-on <string>`: Inclusive start of the time range (RFC3339). (required)
* `--ending-before <string>`: Exclusive end of the time range (RFC3339). (required)
* `--window-size <hour|day>`: Window size for Metronome usage time series. (required)

### `asteroid bug report [flags]`

File a bug report with Asteroid's engineering team. Use it for defects in the Asteroid platform itself. Do not use it when the problem is in a downstream portal or site the agent drives, or in the user's own workflow. Write plain text: what happened, what was expected, and the ids of any executions or workflows involved. Never include patient data, credentials or other secrets; reference ids instead. Returns a reference for the user to quote.

* `--title <string>`: One line naming the bug, 1 to 200 characters, no line breaks (required)
* `--description <string>`: Plain text, 1 to 10000 characters: what happened, what you expected, and the ids of the executions or workflows involved (required)

### `asteroid catalog get [flags]`

The organization's agent catalog: categories, portals and every runnable template, with its category and portal by name. `accessLevel` is `granted` (can instantiate) or `viewable` (locked). A template the organization has not added is `viewable`; `catalog_template_add` grants it. Templates on a portal whose `portalType` is `mock` run against stand-in sites with sample data that Asteroid hosts: they are `granted` to every organization and touch nothing real. Their node instructions carry a demo login. That login is public sample data: sign in with it as written. They need no profile. Offer them for a demo or when the user has no access to the real portal yet, and prefer a real portal's template otherwise. `organizationId` defaults to the caller's one organization. Template definitions are omitted; read one with `catalog_template_get`.

### `asteroid catalog template add <template-id> [flags]`

Add a catalog template to an organization at `accessLevel` `granted`, so `catalog_template_instantiate` can clone it. Also adds the skills of the template's portal. A template that is not `runnable` (see `catalog_template_get`) returns 400. Needs a Startup plan or above. Adding one the organization already has is a no-op. `organizationId` defaults to the caller's one organization.

* `<template-id>`

### `asteroid catalog template get <template-id> [flags]`

One catalog template with a source workflow, with its current `runnable` state, its `inputs`, the portal's credential fields and the organization's `accessLevel`. A template the organization has not added is `viewable`. Set `includeWorkflowDefinition` to also get the template's rules, nodes and transitions as a read-only reference when building or editing a workflow; on an organization-scoped read it needs `accessLevel` `granted`. To get an editable copy, use `catalog_template_instantiate`. A template with no source workflow returns 404. `organizationId` defaults to the caller's one organization.

* `<template-id>`
* `--[no-]include-workflow-definition`: Also return `workflowDefinition`: the rules, nodes and transitions of the source agent's latest published workflow. On an organization-scoped read it needs `granted` access; a `viewable` template returns 403.

### `asteroid catalog template instantiate <template-id> [flags]`

Create a new workflow in the organization from a catalog template. Needs `accessLevel` `granted`: add the template with `catalog_template_add` first; a template on a `mock` portal is already granted. Pass `credentials` (keyed by the portal's credential field keys) to create a profile, or `agentProfileId` to reuse one, or neither for a bare clone. Returns the new workflow's `id` (pass it as `workflowId` to other tools), its `versionId` and any `agentProfileId`. `organizationId` defaults to the caller's one organization.

* `<template-id>`
* `--name <string>`: Optional name for the created agent. Letters, digits, spaces, and punctuation excluding \_ \< > : " / \ | ? and \*. Defaults to the template name.
* `--agent-profile-id <string>`: Reuse an existing agent profile from the target organization for this clone. The profile must belong to `organizationId`. Mutually exclusive with `credentials`; supplying both is a 400.
* `--credentials <json>`: Plaintext values for the portal's declared credential fields, keyed by CredentialField.key. The server creates a fresh agent profile holding them (portal profile defaults applied) before cloning the agent. Required fields (required omitted or true) must be non-blank; blank optional fields are dropped. On a portal with no credential fields, a present (even empty) object still mints a defaults-only profile when the portal declares profile defaults. Mutually exclusive with `agentProfileId`. Omit both fields for a bare clone.
* `--credentials.<key> <string>`: One entry. The key is sent as written.

### `asteroid context [flags]`

Get who you are: your user ID and email, and the organizations this request can act in, with IDs and names. With an organization API key there is no user, so the ID and email are empty. When you belong to several organizations, use this to find the `organizationId` to pass. The Asteroid platform is at [https://platform.asteroid.ai](https://platform.asteroid.ai); use it as the base for dashboard links. When you act in an organization, load the matching skill before you build or edit a workflow: list the skills, then get the one that fits.

### `asteroid custom-environment address list <custom-environment-id> [flags]`

List the logins on a custom environment: the ones its profile rows name, and the ones that ran on it in the last 30 days. Each comes with its own address, when it got it, and its last run, when present. A login has no address until its first run here. Empty unless the environment has `settings.addresses: one_per_login`.

* `<custom-environment-id>`

### `asteroid custom-environment create [flags]`

Create a custom environment: a saved machine a workflow boots on. Set a unique `name` and a `base`: a browser, or a Linux or Windows OS environment. Optionally whitelist `profiles`, override boot `settings`, and keep copies ready with `warmPool` or fresh logins with `warmCache` (not both). Bind it to a workflow with the version's `settings.custom_environment_id`.

* `--name <string>`: Name, unique within the organisation (required)
* `--base <json>`: The base machine: a browser, or a Linux / Windows OS environment. For non-admins, an OS base's `snapshotName` must be one of the organisation's snapshots or a public one; admins may name any snapshot. Omit it for the default image. (required)
* `--base.type <browser|os>`: Type of execution environment
* `--base.config <json>`
* `--profiles <json>`: Ordered whitelist of the profile sources an execution bound to this environment may run as. Each row gets its own warm copies. With one row, a trigger that names neither a profile nor a pool defaults to that row; with several rows, the trigger must name an allowed profile, a member of an allowed pool, or an allowed pool. Empty means any profile or pool may be named, or none. (required)
* `--settings <json>`: Settings the environment boots with. Must match the base type. Absent boots with the platform defaults for the base, plus the agent profile's cookies on a browser. A change applies to environments booted afterwards; warm members already booted keep the settings they booted with.
* `--warm-pool <json>`: Warm pool configuration. Absent means the environment is not kept warm. Exclusive with warmCache.
* `--warm-pool.target-size <integer>`: Baseline number of warm environments to keep ready per profile row outside any scheduled window. An environment with no rows keeps this many in total. 0 drains the pool while no window is open; with no schedule, 0 drains it fully so keep-warm can be turned off or the environment deleted
* `--warm-pool.schedule <json>`: Hour windows that override the baseline target size. Absent means the baseline applies around the clock.
* `--warm-pool.schedule.timezone <string>`: IANA time zone the windows are evaluated in, such as Europe/London
* `--warm-pool.schedule.windows <json>`
* `--warm-pool.max-age-mins <integer>`: Member max age in minutes, not a hard retirement time. The replacement boots ahead of it, by the pool's recent warmup time; the member stays claimable past it until the replacement is ready, for a grace of at most half the max age or 15 minutes. At most 180 on a managed browser base, which ends a session at about 4 hours.
* `--warm-pool.reuse <json>`: How long a pooled environment lives: retired on its first claim, or reused until maxAgeMins and its replacement is ready.
* `--warm-pool.initialization <json>`: Agent that initialises each member. Absent means a member is available as soon as it has booted.
* `--warm-pool.initialization.workflow-id <string>`: The initialising workflow
* `--warm-pool.initialization.inputs <json>`: Fixed inputs for the initialising run
* `--warm-pool.initialization.inputs.<key> <json>`: One entry. The key is sent as written.
* `--warm-pool.initialization.success-outcomes <string[]>`: Outcomes of the initialising run that count as a success. A run that completes with any other outcome is treated as a failed run: a warm pool tears the member down, a warm cache records a failed login. Each must be an outcome of the agent's published version. Absent or empty means any completed run counts. (repeatable)
* `--warm-pool.keep-alive <json>`: Periodic probe that keeps an idle member's session alive and retires a member whose session is dead. Needs a managed browser base or a Daytona desktop base. Absent means members are never touched between warmup and retirement.
* `--warm-pool.keep-alive.interval-mins <integer>`: Minutes between probes of the same member, whether the last one passed or failed. The sweep runs once a minute, so 1 is the shortest effective interval. Must be below the pool's maxAgeMins.
* `--warm-pool.keep-alive.script <string>`: On a browser base: a JavaScript expression evaluated in the member's open page. `await` is allowed. It must evaluate, or resolve, to true while the session is live and to false once it is not. Example: `fetch('/api/session', {credentials: 'include'}).then(r => r.ok)`. It runs with no attached execution, so it must not navigate. On a Linux base: a bash script. On a Windows base: a PowerShell script. Exit code 0 means the session is live; any other exit code means it is dead.
* `--warm-pool.workers <json>`: Runs the pool's executions on workers. Needs a browser base and a reusable reuse policy of at most 20 executions per environment. Absent means the members run executions themselves. Omitting it on update keeps the stored workers; set enabled to false to remove them.
* `--warm-pool.workers.enabled <boolean>`: False removes the workers. Absent or true keeps them on. A save that omits workers keeps the stored ones, so only false turns them off.
* `--warm-pool.workers.count <integer>`: Workers the pool keeps, 1 to 8. Each drives every member environment and takes any execution; add more for volume. Absent means one per member profile, at most 8
* `--warm-cache <json>`: Warm cache configuration. Absent means no login agent keeps the profiles' cookies fresh. Exclusive with warmPool.
* `--warm-cache.timing <json>`: When each profile logs in again. An every rule with anchor last\_run counts from the profile's last login. Prefer it over intervalMins and activeHours. When a request carries all three, a timing that differs from the stored one wins. A timing equal to the stored one lets a changed intervalMins or activeHours apply. It needs a rule that recurs. Logins of one profile stay at least 5 minutes apart.
* `--warm-cache.timing.timezone <string>`: IANA time zone every part is read in, such as America/New\_York. Required in every timing.
* `--warm-cache.timing.at <json>`
* `--warm-cache.timing.every <json>`
* `--warm-cache.timing.once <json>`
* `--warm-cache.timing.cron <json>`
* `--warm-cache.timing.start-at <string>`: No fire before this instant. Inclusive.
* `--warm-cache.timing.end-at <string>`: No fire at or after this instant.
* `--warm-cache.description <string>`: The timing in words. The server writes it and ignores it in a request.
* `--warm-cache.interval-mins <integer>`: Minutes between logins of the same profile. Prefer timing. In a response it is the interval of timing, or the mean gap between its runs.
* `--warm-cache.active-hours <json>`: Hours during which logins run. Absent means around the clock. Prefer the during windows of timing.
* `--warm-cache.active-hours.timezone <string>`: IANA time zone the windows are evaluated in, such as Europe/London
* `--warm-cache.active-hours.windows <json>`
* `--warm-cache.initialization <json>`: The login agent, run on each profile's own environment
* `--warm-cache.initialization.workflow-id <string>`: The initialising workflow
* `--warm-cache.initialization.inputs <json>`: Fixed inputs for the initialising run
* `--warm-cache.initialization.inputs.<key> <json>`: One entry. The key is sent as written.
* `--warm-cache.initialization.success-outcomes <string[]>`: Outcomes of the initialising run that count as a success. A run that completes with any other outcome is treated as a failed run: a warm pool tears the member down, a warm cache records a failed login. Each must be an outcome of the agent's published version. Absent or empty means any completed run counts. (repeatable)
* `--warm-cache.executions-write-back <boolean>`: Whether executions on the environment save the browser profile when they stop. Off by default: only the login agent saves it, so a run that ends logged out cannot overwrite the session for later runs. The first run on a login's own address saves anyway, to keep the address.

### `asteroid custom-environment delete <custom-environment-id> [flags]`

Delete a custom environment. Workflows bound to it through `settings.custom_environment_id` can no longer boot. Refused while warm members exist: set `warmPool.targetSize` to 0 first and wait for them to retire.

* `<custom-environment-id>`

### `asteroid custom-environment get <custom-environment-id> [flags]`

Read one custom environment by ID, such as the one a workflow's `settings.custom_environment_id` names, to see what machine the workflow boots on.

* `<custom-environment-id>`

### `asteroid custom-environment list [flags]`

List an organization's custom environments: the saved machines a workflow boots on, each with its environment type, snapshot, networking, allowed profiles and warm pool. Use an environment's `id` as a workflow version's `settings.custom_environment_id`.

### `asteroid custom-environment member list <custom-environment-id> [flags]`

List a custom environment's warm pool members: each pre-warmed environment's ID, state (warming, available, retiring), profile, attached executions and keep-alive health. Empty when the environment is not kept warm.

* `<custom-environment-id>`

### `asteroid custom-environment update <custom-environment-id> [flags]`

Replace a custom environment's configuration. Send the full config, as `custom_environment_get` returns it: a field left out is cleared, except proxy passwords, a managed proxy's provider, `settings.addresses` and `warmPool.workers`, which keep their stored values. Set `warmPool.workers.enabled` to false to remove workers. Changes apply to environments booted afterwards. Turning keep-warm off is refused while members exist: set `warmPool.targetSize` to 0 first and wait for them to retire.

* `<custom-environment-id>`
* `--name <string>`: Name, unique within the organisation (required)
* `--base <json>`: The base machine: a browser, or a Linux / Windows OS environment. For non-admins, an OS base's `snapshotName` must be one of the organisation's snapshots or a public one; admins may name any snapshot. Omit it for the default image. (required)
* `--base.type <browser|os>`: Type of execution environment
* `--base.config <json>`
* `--profiles <json>`: Ordered whitelist of the profile sources an execution bound to this environment may run as. Each row gets its own warm copies. With one row, a trigger that names neither a profile nor a pool defaults to that row; with several rows, the trigger must name an allowed profile, a member of an allowed pool, or an allowed pool. Empty means any profile or pool may be named, or none. (required)
* `--settings <json>`: Settings the environment boots with. Must match the base type. Absent boots with the platform defaults for the base, plus the agent profile's cookies on a browser. A change applies to environments booted afterwards; warm members already booted keep the settings they booted with.
* `--warm-pool <json>`: Warm pool configuration. Absent means the environment is not kept warm. Exclusive with warmCache.
* `--warm-pool.target-size <integer>`: Baseline number of warm environments to keep ready per profile row outside any scheduled window. An environment with no rows keeps this many in total. 0 drains the pool while no window is open; with no schedule, 0 drains it fully so keep-warm can be turned off or the environment deleted
* `--warm-pool.schedule <json>`: Hour windows that override the baseline target size. Absent means the baseline applies around the clock.
* `--warm-pool.schedule.timezone <string>`: IANA time zone the windows are evaluated in, such as Europe/London
* `--warm-pool.schedule.windows <json>`
* `--warm-pool.max-age-mins <integer>`: Member max age in minutes, not a hard retirement time. The replacement boots ahead of it, by the pool's recent warmup time; the member stays claimable past it until the replacement is ready, for a grace of at most half the max age or 15 minutes. At most 180 on a managed browser base, which ends a session at about 4 hours.
* `--warm-pool.reuse <json>`: How long a pooled environment lives: retired on its first claim, or reused until maxAgeMins and its replacement is ready.
* `--warm-pool.initialization <json>`: Agent that initialises each member. Absent means a member is available as soon as it has booted.
* `--warm-pool.initialization.workflow-id <string>`: The initialising workflow
* `--warm-pool.initialization.inputs <json>`: Fixed inputs for the initialising run
* `--warm-pool.initialization.inputs.<key> <json>`: One entry. The key is sent as written.
* `--warm-pool.initialization.success-outcomes <string[]>`: Outcomes of the initialising run that count as a success. A run that completes with any other outcome is treated as a failed run: a warm pool tears the member down, a warm cache records a failed login. Each must be an outcome of the agent's published version. Absent or empty means any completed run counts. (repeatable)
* `--warm-pool.keep-alive <json>`: Periodic probe that keeps an idle member's session alive and retires a member whose session is dead. Needs a managed browser base or a Daytona desktop base. Absent means members are never touched between warmup and retirement.
* `--warm-pool.keep-alive.interval-mins <integer>`: Minutes between probes of the same member, whether the last one passed or failed. The sweep runs once a minute, so 1 is the shortest effective interval. Must be below the pool's maxAgeMins.
* `--warm-pool.keep-alive.script <string>`: On a browser base: a JavaScript expression evaluated in the member's open page. `await` is allowed. It must evaluate, or resolve, to true while the session is live and to false once it is not. Example: `fetch('/api/session', {credentials: 'include'}).then(r => r.ok)`. It runs with no attached execution, so it must not navigate. On a Linux base: a bash script. On a Windows base: a PowerShell script. Exit code 0 means the session is live; any other exit code means it is dead.
* `--warm-pool.workers <json>`: Runs the pool's executions on workers. Needs a browser base and a reusable reuse policy of at most 20 executions per environment. Absent means the members run executions themselves. Omitting it on update keeps the stored workers; set enabled to false to remove them.
* `--warm-pool.workers.enabled <boolean>`: False removes the workers. Absent or true keeps them on. A save that omits workers keeps the stored ones, so only false turns them off.
* `--warm-pool.workers.count <integer>`: Workers the pool keeps, 1 to 8. Each drives every member environment and takes any execution; add more for volume. Absent means one per member profile, at most 8
* `--warm-cache <json>`: Warm cache configuration. Absent means no login agent keeps the profiles' cookies fresh. Exclusive with warmPool.
* `--warm-cache.timing <json>`: When each profile logs in again. An every rule with anchor last\_run counts from the profile's last login. Prefer it over intervalMins and activeHours. When a request carries all three, a timing that differs from the stored one wins. A timing equal to the stored one lets a changed intervalMins or activeHours apply. It needs a rule that recurs. Logins of one profile stay at least 5 minutes apart.
* `--warm-cache.timing.timezone <string>`: IANA time zone every part is read in, such as America/New\_York. Required in every timing.
* `--warm-cache.timing.at <json>`
* `--warm-cache.timing.every <json>`
* `--warm-cache.timing.once <json>`
* `--warm-cache.timing.cron <json>`
* `--warm-cache.timing.start-at <string>`: No fire before this instant. Inclusive.
* `--warm-cache.timing.end-at <string>`: No fire at or after this instant.
* `--warm-cache.description <string>`: The timing in words. The server writes it and ignores it in a request.
* `--warm-cache.interval-mins <integer>`: Minutes between logins of the same profile. Prefer timing. In a response it is the interval of timing, or the mean gap between its runs.
* `--warm-cache.active-hours <json>`: Hours during which logins run. Absent means around the clock. Prefer the during windows of timing.
* `--warm-cache.active-hours.timezone <string>`: IANA time zone the windows are evaluated in, such as Europe/London
* `--warm-cache.active-hours.windows <json>`
* `--warm-cache.initialization <json>`: The login agent, run on each profile's own environment
* `--warm-cache.initialization.workflow-id <string>`: The initialising workflow
* `--warm-cache.initialization.inputs <json>`: Fixed inputs for the initialising run
* `--warm-cache.initialization.inputs.<key> <json>`: One entry. The key is sent as written.
* `--warm-cache.initialization.success-outcomes <string[]>`: Outcomes of the initialising run that count as a success. A run that completes with any other outcome is treated as a failed run: a warm pool tears the member down, a warm cache records a failed login. Each must be an outcome of the agent's published version. Absent or empty means any completed run counts. (repeatable)
* `--warm-cache.executions-write-back <boolean>`: Whether executions on the environment save the browser profile when they stop. Off by default: only the login agent saves it, so a run that ends logged out cannot overwrite the session for later runs. The first run on a login's own address saves anyway, to keep the address.

### `asteroid docs search [flags]`

Search Asteroid documentation for guides on building workflows, node types, and best practices.

* `--query <string>`: (required)
* `--format <mdx|text>`: How search result content is returned

### `asteroid environment get <environment-id> [flags]`

Read a running environment by ID: its status and metadata, plus the proxied CDP URL needed to drive it (omitted when the proxy is disabled, or for environments with no browser endpoint). Returns 404 once the environment has stopped or expired.

* `<environment-id>`

### `asteroid environment list [flags]`

List an organization's currently-running standalone environments, to rediscover one to attach to. Narrow to one workflow with `workflowId`. Only environments started through this API are listed. Gives IDs and statuses; fetch connection details with `environment_get`.

* `--workflow-id <string>`: Only environments bound to this workflow. Omit for every standalone environment in the organisation, the unbound ones included.
* `--lifecycle <running|terminal|all>`: Which lifecycle states to return. Omit for running environments only.

### `asteroid environment start [flags]`

Start a live browser or OS environment. Without `source`, you get a browser, or the bound workflow's environment when an Astro chat starts it. Set `source` to `{kind: "workflow"}` to use a workflow's environment (needs `workflowId`), or to `{kind: "spec"}` to choose a browser or an OS. Optional: `workflowId` binds it to a workflow; `profileId` loads a login profile's secrets. For a browser, `connection.cdpUrl` is a proxied DevTools URL for Playwright's `connectOverCDP`, present once the browser is ready. The environment stops at `expiresAt`; stop it earlier with `environment_stop`.

* `--workflow-id <string>`: The workflow to bind the environment to. Gates access to that workflow. Omit for an organization-owned environment with no workflow binding. Do not set together with agentId.
* `--source <json>`: Where the environment spec comes from. Omit for the server default: a browser env at the computer-use resolution, or the bound workflow's environment when an Astro chat starts it. The workflow arm needs a workflow to resolve against, so it requires `workflowId`.
* `--profile-id <string>`: Optional login profile to attach. The profile id is stamped onto the env row for the session's lifetime, so later reads resolve against the stamped profile rather than the workflow's current one. Its decrypted credentials come back on the response's `connection` only for service-to-service callers — they are never returned to an API key or a browser. Do not set together with agentProfileId.

### `asteroid environment stop <environment-id> [flags]`

Stop a running standalone environment by environment ID. Idempotent: stopping an already-stopped environment is a no-op.

* `<environment-id>`

### `asteroid environment totp <environment-id> [flags]`

Compute the current 2FA code for a secret field on the profile an environment was started with (`environment_start` with `profileId`). Name the field by its placeholder, e.g. `##MY_PORTAL.TOTP##`; `secret_get` lists a secret's placeholders. Returns `code` and `expiresInSeconds`; the seed itself is never returned. Optional `digits`, `period` and `algorithm` override what the field's otpauth URI says.

* `<environment-id>`
* `--field <string>`: The secret field to read, as the placeholder `secret get` prints for it, e.g. `##MY_PORTAL.TOTP##`. Copy it rather than building it: the item key is the secret's key upper-cased with dashes as underscores, the field key is upper-cased. The `##` and the case are optional. The field holds a base32 seed or an `otpauth://totp/` URI. (required)
* `--digits <integer>`: Code length, 4 to 10. Defaults to the URI's `digits`, else 6.
* `--period <integer>`: Seconds each code lasts. Defaults to the URI's `period`, else 30.
* `--algorithm <sha1|sha256|sha512>`: Hash. Defaults to the URI's `algorithm`, else sha1.

### `asteroid event-type list [flags]`

List the events a workflow notification rule can match, with the fields each one can filter on, their operators and valid values.

### `asteroid execution activities <execution-id> [flags]`

List an execution's activity log: what the agent did, step by step. Set `order` (asc or desc by time) and `limit`.

* `<execution-id>`
* `--order <asc|desc>`: Sort order for activities by timestamp
* `--limit <integer>`

### `asteroid execution cancel <execution-id> [flags]`

Cancel an execution. The execution stops and cannot be resumed.

* `<execution-id>`

### `asteroid execution context-file download <execution-id> <file-id> [flags]`

Download one file attached to an execution by `fileId`, from the listing returned by `execution_context_files_get`. The response redirects to the file in storage.

* `<execution-id>`
* `<file-id>`

### `asteroid execution context-file list <execution-id> [flags]`

List the files attached to an execution, such as `tempFiles` staged before it started. Download one with `execution_context_file_signed_url`.

* `<execution-id>`

### `asteroid execution context-file upload <execution-id> [flags]`

Upload files into a running execution. The agent finds them in its uploads folder. To attach files before an execution starts, stage them with `temp_files_upload`.

* `<execution-id>`
* `--files <path>`: File to upload (repeatable)

### `asteroid execution context-file url <execution-id> <file-id> [flags]`

Get a short-lived URL to download one context file (a file uploaded to the execution) by `fileId`, from the listing returned by `execution_context_files_get`.

* `<execution-id>`
* `<file-id>`

### `asteroid execution counts [flags]`

Aggregate counts of executions grouped by status, plus the top outcome labels, for an organization. Accepts the same filters as `executions_list` (workflow, status, date range, metadata, inputs, labels), so it answers "how many runs failed this week" without paging rows.

* `--execution-id <string>`: Search by execution ID (partial, case-insensitive match)
* `--status <queued|starting|running|paused|awaiting_confirmation|completed|cancelled|failed|paused_by_agent>`: Filter by execution status (can specify multiple, there is an 'OR' condition applied to these) (repeatable)
* `--created-after <string>`
* `--created-before <string>`
* `--human-labels <string[]>`: Filter by human labels (can specify multiple label IDs, there is an 'OR' condition applied to these) (repeatable)
* `--outcome-label <string>`: Filter by execution result outcome (partial, case-insensitive match)
* `--metadata-key <string>`: Filter by metadata key - must be used together with metadataValue
* `--metadata-value <string>`: Filter by metadata value - must be used together with metadataKey
* `--inputs-key <string>`: Filter by input variable key - must be used together with inputsValue
* `--inputs-value <string>`: Filter by input variable value (partial, case-insensitive match) - must be used together with inputsKey
* `--workflow-version <integer>`
* `--[no-]has-script-failures`
* `--trigger-source <api|ui|schedule|warmup>`: Filter by how the execution was triggered (can specify multiple, there is an 'OR' condition applied to these) (repeatable)
* `--phase <pending|active|terminal>`: Filter by lifecycle phase, derived from status (can specify multiple, OR across values). Composes with the status filter as AND. pending = queued; active = starting, running, awaiting\_confirmation, paused, paused\_by\_agent; terminal = completed, cancelled, failed. (repeatable)
* `--workflow-id <string>`
* `--created-within <string>`: Filter executions created within this long before now: number-unit pairs with units w, d, h, m, longest first, e.g. 30m, 24h, 7d, 1d12h. Maximum 10 years. Cannot be combined with createdAfter
* `--metadata <string[]>`: Filter by metadata key=value pairs. Repeat the parameter for several pairs; every pair must match (repeatable)
* `--profile-ids <string[]>`: Filter by login profile IDs (can specify multiple, there is an 'OR' condition applied to these) (repeatable)
* `--batch-id <string>`: Only executions started by this batch, an ID from `execution_batches_list`. Rows not yet triggered have no execution yet: list them with `scheduled_executions_list` and `batchId`.
* `--[no-]include-outcomes`: Also count outcome labels. Defaults to true. Set false when only status counts are needed: with no time window, outcome counts read every result in the organization. When false, outcome\_counts.items is empty.

### `asteroid execution delete <execution-id> [flags]`

Delete a finished execution. It disappears from lists and reads, and the user cannot restore it. Only a terminal execution can be deleted: cancel a running one first with `execution_cancel`. Confirm with the user before calling it. This is a soft delete: Asteroid keeps the data under its retention policy, so it does not meet a data deletion or retention requirement. For that, the user must ask Asteroid for custom retention.

* `<execution-id>`

### `asteroid execution file download <execution-id> <file-id> [flags]`

Download one execution file by `fileId`, from the listing returned by `execution_files_get`. The response redirects to the file in storage.

* `<execution-id>`
* `<file-id>`

### `asteroid execution file list <execution-id> [flags]`

List an execution's files, grouped by directory (uploads, downloads, workspace, shared). Download one with `execution_file_signed_url`.

* `<execution-id>`

### `asteroid execution file url <execution-id> <file-id> [flags]`

Get a short-lived URL to download one execution file by `fileId`, from the listing returned by `execution_files_get`. Fetch the URL to read the file's contents.

* `<execution-id>`
* `<file-id>`

### `asteroid execution get <execution-id> [flags]`

Get one execution: status, result, timing, workflow and version, inputs, metadata, profile, and live-view and recording URLs.

* `<execution-id>`

### `asteroid execution list [flags]`

List executions with filtering and pagination. Filter by age with `createdWithin` (e.g. `24h`, `7d`) and by metadata with repeated `metadata=key=value`. Sort with `sort=created_at:desc`.

* `--page-size <integer>`
* `--page <integer>`
* `--execution-id <string>`: Search by execution ID (partial, case-insensitive match)
* `--status <queued|starting|running|paused|awaiting_confirmation|completed|cancelled|failed|paused_by_agent>`: Filter by execution status (can specify multiple, there is an 'OR' condition applied to these) (repeatable)
* `--created-after <string>`
* `--created-before <string>`
* `--human-labels <string[]>`: Filter by human labels (can specify multiple label IDs, there is an 'OR' condition applied to these) (repeatable)
* `--outcome-label <string>`: Filter by execution result outcome (partial, case-insensitive match)
* `--metadata-key <string>`: Filter by metadata key - must be used together with metadataValue
* `--metadata-value <string>`: Filter by metadata value - must be used together with metadataKey
* `--inputs-key <string>`: Filter by input variable key - must be used together with inputsValue
* `--inputs-value <string>`: Filter by input variable value (partial, case-insensitive match) - must be used together with inputsKey
* `--workflow-version <integer>`
* `--[no-]has-script-failures`
* `--trigger-source <api|ui|schedule|warmup>`: Filter by how the execution was triggered (can specify multiple, there is an 'OR' condition applied to these) (repeatable)
* `--phase <pending|active|terminal>`: Filter by lifecycle phase, derived from status (can specify multiple, OR across values). Composes with the status filter as AND. pending = queued; active = starting, running, awaiting\_confirmation, paused, paused\_by\_agent; terminal = completed, cancelled, failed. (repeatable)
* `--sort-field <created_at|status|started_at>`: Fields that can be used for sorting executions
* `--sort-direction <asc|desc>`
* `--workflow-id <string>`
* `--created-within <string>`: Filter executions created within this long before now: number-unit pairs with units w, d, h, m, longest first, e.g. 30m, 24h, 7d, 1d12h. Maximum 10 years. Cannot be combined with createdAfter
* `--metadata <string[]>`: Filter by metadata key=value pairs. Repeat the parameter for several pairs; every pair must match (repeatable)
* `--sort <string>`: Sort shorthand as field:direction, e.g. created\_at:desc. Fields: created\_at, status, started\_at. Cannot be combined with sortField or sortDirection
* `--profile-ids <string[]>`: Filter by login profile IDs (can specify multiple, there is an 'OR' condition applied to these) (repeatable)
* `--batch-id <string>`: Only executions started by this batch, an ID from `execution_batches_list`. Rows not yet triggered have no execution yet: list them with `scheduled_executions_list` and `batchId`.

### `asteroid execution message <execution-id> [flags]`

Send a message to a running or paused execution. The agent reads it as user input. When the agent is waiting for an answer, the message also resumes it. To attach files, upload them first with `execution_context_files_upload`, then send the message, as the platform does.

* `<execution-id>`
* `--message <string>`: The message the agent receives. (required)

### `asteroid execution metadata-keys [flags]`

List the distinct metadata keys used on an organization's executions, so you know what `metadataKey` values `executions_list` can filter on.

### `asteroid execution pause <execution-id> [flags]`

Pause a running execution. Resume it later with `execution_resume`.

* `<execution-id>`

### `asteroid execution pull <execution-id> [flags]`

Write an execution to `<workflow-name>/executions/<id>/`: summary.json, activities.md (the step-by-step log), and the files the run produced.

* `<execution-id>`
* `--files <string>`: Only download files whose path matches this glob. --no-files skips downloads.
* `--[no-]summary-only`: Write summary.json only: no activities, no files.
* `--max-file-size <integer>`: Skip files larger than this many bytes.
* `--dir <string>`: Write here instead of `<workflow-name>/executions/<id>/` under the current directory.

### `asteroid execution recording <execution-id> [flags]`

Download an execution's browser recording. The response redirects to the recording file.

* `<execution-id>`
* `--token <string>`: Optional token for authentication. Use this when the client cannot set Authorization headers (e.g., native video elements).

### `asteroid execution rerun <execution-id> [flags]`

Start a new execution of the same workflow version as the original, with its inputs, profile, metadata and execution options. Pass `inputs` or `profileId` to replace the copied values. Files staged for the original execution are not copied.

* `<execution-id>`
* `--inputs <json>`: Input variables for the new execution. Replaces the original inputs when set.
* `--inputs.<key> <json>`: One entry. The key is sent as written.
* `--profile-id <string>`: The ID of the login profile to use. Replaces the original profile when set.

### `asteroid execution resume <execution-id> [flags]`

Resume a paused execution. It continues from where it stopped. Also approves an execution in `awaiting_confirmation`, like Approve on the execution page: read the agent's reason in `execution_activities_get` first, and get the user's go-ahead before you approve for them. It waits up to 10 seconds for the run to leave the pause or hold.

* `<execution-id>`

### `asteroid execution sync <execution-id> [flags]`

Wait up to `timeoutSeconds` (1-25, default 25) for an execution's status to change. Returns as soon as the status differs from the one it had when the call began. A `paused`, `paused_by_agent` or `awaiting_confirmation` execution returns at once, since it needs a person. `returnReason` says why it returned: `ended` (with `executionResult` when the run recorded one), `needs_person`, `status_change` or `timed_out`. After `status_change` or `timed_out`, call it again to keep following the run. On `awaiting_confirmation`, `awaitingConfirmation.nodeName` names the node the run holds at: get the user's go-ahead, then approve with `execution_resume`. Use it after `workflow_execute_post`, or after `workflow_execute_sync_post` timed out, instead of polling `execution_get`.

* `<execution-id>`
* `--timeout-seconds <integer>`: Seconds to wait for a change before returning 202. Defaults to 25.

### `asteroid execution wait <execution-id> [flags]`

Call `execution sync` until it reports a reason to stop, then print the status. It returns as soon as the run's status changes, at once when the run has ended or needs a person, and otherwise at the timeout, when it prints the status the run still has so you can wait again. On `awaiting_confirmation` it names the node the run holds at when the API reports one, and otherwise points to `asteroid execution activities`. Approve it with `asteroid execution resume <execution-id>` once the user agrees.

* `<execution-id>`
* `--timeout <integer>`: Give up after this many seconds, 600 unless set, 3600 at most.

### `asteroid insight get <insight-id> [flags]`

Get one insight with its markdown content, status and the question it puts to the user, if any.

* `<insight-id>`

### `asteroid insight list [flags]`

List an organization's insights, most recently updated first. An insight is a markdown note Astro writes during a chat, such as a recommendation or an overview, with a type and a status. Filter by `chatId`, `workflowId` or one or more `status` values (any match). Page with `page` and `pageSize`.

* `--chat-id <string>`: Only insights produced by this Astro chat.
* `--workflow-id <string>`
* `--status <string[]>`: Filter by insight status (can specify multiple, there is an 'OR' condition applied to these) (repeatable)
* `--page-size <integer>`
* `--page <integer>`

### `asteroid insight pull [insight-id] [flags]`

Write insights to `insights/<name>.md`, one markdown file each with YAML frontmatter (id, type, status, name, next\_steps). Name an insight to pull that one. A file another insight or an unpushed draft already holds keeps its name; the pulled one gets a -2, -3 suffix.

* `[insight-id]`: One insight to pull. Without it, every insight, or one workflow's with --workflow-id.
* `--workflow-id <string>`: Only this workflow's insights.
* `--dir <string>`: Write here instead of `insights/` under the current directory.

### `asteroid integration create [flags]`

Create a webhook integration. Set `type` to `webhook` and `configuration` to `{type: webhook, url, headers}`. Put a shared secret in a header, such as `Authorization`. Asteroid signs every delivery; verify it with integration\_signing\_keys\_get. Slack is added in the platform app only.

* `--name <string>`: (required)
* `--type <webhook|slack|asteroid_management>`: The type of the integration (required)
* `--configuration <json>`: Configuration for an integration (required)

### `asteroid integration delete <id> [flags]`

Delete an integration and every workflow notification rule that sends to it.

* `<id>`

### `asteroid integration list [flags]`

List the organization's integrations: webhooks and Slack workspaces. Slack tokens are left out. Use an integration's `id` as `integrationId` in a workflow notification rule.

### `asteroid integration signing-keys [flags]`

Get the public keys that sign webhook deliveries. Verify a delivery against the key named in its `X-Asteroid-Webhook-Key-Id` header.

### `asteroid integration test <id> [flags]`

Send a test notification to an integration, such as a sample event to a webhook URL.

* `<id>`

### `asteroid integration update <id> [flags]`

Replace a webhook integration's name and configuration (`{type: webhook, url, headers}`). Slack integrations are edited in the platform app only.

* `<id>`
* `--name <string>`: (required)
* `--configuration <json>`: Configuration for an integration (required)

### `asteroid memory create [flags]`

Save something the next agent in this organization needs to know: how a portal behaves, why a workflow is built the way it is, a customer's or facility's rules. Give a one-line `description` and plain-text `content`. Link the `portalId` (from `skills_list`) or `portal` name when the memory is about a portal, and add `tags`. Set `workflowId` only when the memory is about how that one workflow works: leave it out for portal facts and anything another workflow could use. Run `memory_list` first and update a memory that already covers it instead of adding another. Never store patient names, member IDs, dates of birth or anything else about one patient or case: keep only what helps the next agent build or fix a workflow.

* `--description <string>`: One line, 1 to 200 characters, that tells the next agent what this memory holds. (required)
* `--content <string>`: Plain text, 1 to 4000 characters. One fact per memory. Leave out patient data and anything about one case. Keep what helps the next agent build or fix a workflow. (required)
* `--portal <string>`: The portal's name or host, when the memory is about a portal.
* `--portal-id <string>`: The portal's ID from `skills_list`.
* `--workflow-id <string>`: The workflow the memory is about, set only when it is about how that one workflow works. Portal facts, and anything another workflow could use, have none.
* `--tags <string[]>`: Up to 20 labels that make the memory easy to find. (repeatable)

### `asteroid memory delete <memory-id> [flags]`

Delete a memory for good, when it is wrong and no longer useful. Prefer `memory_update` when it only needs correcting.

* `<memory-id>`

### `asteroid memory get <memory-id> [flags]`

Get one memory with its content, by the id from `memory_list`.

* `<memory-id>`

### `asteroid memory list [flags]`

List the organization's memory: what its agents learned while building, one line per memory with its `description`, linked `portal`, `portalId`, `workflowId` and `tags`, newest first. Call it once at the start of a conversation, before other work, and pass `nextCursor` as `cursor` while one comes back. Filter by `workflowId`, `portalId` or `tag`, or search with `query`. A `workflowId` filter leaves out portal facts, which have no workflow. `memory_get` returns a memory's content.

* `--portal-id <string>`: Only memories linked to this portal.
* `--workflow-id <string>`: Only memories linked to this workflow. Portal facts have no workflow, so this filter leaves them out.
* `--tag <string>`: Only memories with this tag.
* `--query <string>`: Text to find in the description or content, case-insensitive.
* `--limit <integer>`: Up to 200. Defaults to 200.
* `--cursor <string>`: `nextCursor` from the previous page.

### `asteroid memory update <memory-id> [flags]`

Change a memory when what it says is out of date or incomplete. Send only the fields to change; `tags` replaces the list, and null unlinks `portal`, `portalId` or `workflowId`. Never store patient names, member IDs, dates of birth or anything else about one patient or case: keep only what helps the next agent build or fix a workflow.

* `<memory-id>`
* `--description <string>`
* `--content <string>`: Replaces the whole content. Plain text, 1 to 4000 characters. If over the character limit, consider creating separate memories per fact you're storing.
* `--portal <string>`: A portal's name or host. One line, 1 to 200 characters.
* `--portal-id <string>`
* `--workflow-id <string>`
* `--tags <string[]>`: Replaces the memory's tags. (repeatable)

### `asteroid model list [flags]`

List the model slugs valid for an agent node's `model` setting, with display name, description and whether the model supports computer use.

### `asteroid notification list [flags]`

List the workflow notification rules across the organization, by workflow name. Filter with `integrationId` or `workflowId`.

* `--integration-id <string>`: Only rules that notify this integration.
* `--workflow-id <string>`: Only this workflow's rules.

### `asteroid portal-skills add <portal-id> [flags]`

Add a portal's skills to an organization, by the `portalId` of a portal skill from `skills_list`. Needs a Startup plan or above. Astro loads the portal's skills once it is added, and `skill_get` serves them. Adding one the organization already has is a no-op.

* `<portal-id>`

### `asteroid profile clear-cache <profile-id> [flags]`

Clear the persisted browser cache (cookies, storage) for a login profile, resetting its browser state.

* `<profile-id>`

### `asteroid profile create [flags]`

Create a login profile: one identity a workflow can sign in as, with its attached secrets, email inbox, sticky IP and stored browser state. Attach secrets with `secretIds`. Secret values never pass through an agent: the person who holds them fills a secret request or the platform's secret form.

* `--name <string>`: Name of the agent profile (must be unique within organization) (required)
* `--description <string>`: (required)
* `--secret-ids <string[]>`: Secret IDs to attach to this profile. Do not set together with vaultItemIds. (repeatable)
* `--inbox-email-prefix <string>`: Optional custom prefix for the email inbox address. If set, the inbox will be \{prefix}@agentmail.asteroid.ai.

### `asteroid profile delete <profile-id> [flags]`

Delete a login profile.

* `<profile-id>`

### `asteroid profile duplicate <profile-id> [flags]`

Copy a login profile with its settings, cookies and attached secrets. The copy is created in the same organization. To copy it into another organization you belong to, pass that organization's ID as `organizationId`. Attached secrets are not copied across organizations.

* `<profile-id>`

### `asteroid profile get <profile-id> [flags]`

Get a login profile by ID, including its email inbox and attached secrets (keys and ##ITEM\_KEY.FIELD## placeholders; values are omitted).

* `<profile-id>`

### `asteroid profile inbox get <profile-id> <email-id> [flags]`

Read one email from a login profile's email inbox by `emailId`, including its text and HTML body.

* `<profile-id>`
* `<email-id>`: The Resend email ID

### `asteroid profile inbox list <profile-id> [flags]`

List the emails received by a login profile's email inbox, newest first, with sender, subject and time. Use `profile_inbox_email_get` for a message body. Useful for verification codes and confirmations sent to the profile's address.

* `<profile-id>`
* `--limit <integer>`

### `asteroid profile list [flags]`

List login profiles. A profile is one identity a workflow can sign in as: attached secrets, an email inbox, a sticky IP and stored browser state. Secret values are never returned. Reference a secret field in workflow instructions as ##ITEM\_KEY.FIELD##.

* `--page-size <integer>`
* `--page <integer>`
* `--search-name <string>`: Search profiles by name (partial match)
* `--sort-field <name|created_at|updated_at>`: Available fields for sorting agent profiles
* `--sort-direction <asc|desc>`

### `asteroid profile update <profile-id> [flags]`

Update a login profile. Attach secrets with `secretIdsToAdd` and detach them with `secretIdsToRemove`. `secretIds` replaces the full set.

* `<profile-id>`
* `--name <string>`
* `--description <string>`
* `--secret-ids <string[]>`: Secret IDs attached to this profile. Replaces the full list. To change part of it, use secretIdsToAdd and secretIdsToRemove. (repeatable)
* `--secret-ids-to-add <string[]>`: Secret IDs to attach. Secrets already attached stay. Cannot be combined with secretIds. (repeatable)
* `--secret-ids-to-remove <string[]>`: Secret IDs to detach. IDs that are not attached are ignored. Applied before secretIdsToAdd. Cannot be combined with secretIds. (repeatable)
* `--inbox-email-prefix <string>`: Optional custom prefix for the email inbox address. If set, the inbox will be \{prefix}@agentmail.asteroid.ai.

### `asteroid profile-group create [flags]`

Create an empty profile group with a unique `name`. Set `selectionStrategy` and whether one profile may serve concurrent executions, then add members with `profile_group_members_add`.

* `--name <string>`: Name of the agent profile pool (must be unique within organization) (required)
* `--selection-strategy <least_recently_used|most_recently_used>`: Strategy for selecting an available profile from a pool
* `--[no-]allow-concurrent-use`: Whether multiple executions can use the same profile concurrently

### `asteroid profile-group delete <group-id> [flags]`

Delete a profile group. The member profiles themselves are kept; schedules or executions that name the group will fail to select a profile.

* `<group-id>`

### `asteroid profile-group get <group-id> [flags]`

Get one profile group by ID with its selection settings.

* `<group-id>`

### `asteroid profile-group list [flags]`

List profile groups. A profile group is a set of interchangeable login profiles for one portal, with the same permissions. Each run takes a free profile from the group, so concurrent runs get different logins, unless the group sets `allowConcurrentUse`.

* `--page-size <integer>`
* `--page <integer>`
* `--search-name <string>`: Search pools by name (partial match)
* `--sort-field <name|created_at|updated_at>`: Available fields for sorting agent profile pools
* `--sort-direction <asc|desc>`

### `asteroid profile-group member add <group-id> [flags]`

Add existing profiles to a profile group by `profileIds`. Profiles must belong to the group's organization.

* `<group-id>`
* `--profile-ids <string[]>`: (required, repeatable)

### `asteroid profile-group member list <group-id> [flags]`

List the profiles in a profile group, paginated.

* `<group-id>`
* `--page-size <integer>`
* `--page <integer>`

### `asteroid profile-group member remove <group-id> [flags]`

Remove profiles from a profile group by `profileIds`. The profiles are not deleted.

* `<group-id>`
* `--profile-ids <string[]>`: (required, repeatable)

### `asteroid profile-group update <group-id> [flags]`

Rename a profile group or change its selection strategy and concurrent-use setting. Membership is changed with the members tools.

* `<group-id>`
* `--name <string>`
* `--selection-strategy <least_recently_used|most_recently_used>`: Strategy for selecting an available profile from a pool
* `--[no-]allow-concurrent-use`: Whether multiple executions can use the same profile concurrently

### `asteroid proxy-gateway get <proxy-gateway-id> [flags]`

Read one proxy gateway by ID, such as a custom environment's `proxyGatewayPresetId`, to see whether it is enabled and why it is not ready (`status`, `statusReason`). Never returns its credentials.

* `<proxy-gateway-id>`

### `asteroid proxy-gateway list [flags]`

List the organization's proxy gateways, or find one with `searchName`. Each has an `id`, `name`, `gatewayType`, `enabled` and `status`, and never its credentials. Route a custom environment through a gateway by setting its `settings.proxy` to `mode` `gateway` and `proxyGatewayPresetId` to the gateway's `id`. Creating a gateway, its credentials and its setup keys stay in the platform app.

* `--search-name <string>`: Case-insensitive search on the gateway name.

### `asteroid proxy-gateway update <proxy-gateway-id> [flags]`

Rename a proxy gateway with `name`, or turn it on or off with `enabled`. Only the fields sent change. Turning a gateway off stops new executions through it. Credentials and provider settings change in the platform app.

* `<proxy-gateway-id>`
* `--name <string>`
* `--[no-]enabled`: Whether the gateway is enabled. A disabled gateway takes no new executions.

### `asteroid schedule create <workflow-id> [flags]`

Create a recurring schedule on a workflow: a `name`, a five-field `cronExpression`, an IANA `timezone` (defaults to UTC), and the `inputs` each run receives. Pin a profile with `profileId` or a profile group with `profileGroupId`. Set `batchSource` to fan each tick out from a spreadsheet instead of one run.

* `<workflow-id>`
* `--name <string>`: (required)
* `--profile-id <string>`: Login profile each execution runs with. Mutually exclusive with profileGroupId.
* `--profile-group-id <string>`: Profile group to select a profile from for each execution. Mutually exclusive with profileId.
* `--timing <json>`: When the schedule fires. Send this or cronExpression, not both. A schedule needs a rule that recurs: at, every or cron.
* `--timing.timezone <string>`: IANA time zone every part is read in, such as America/New\_York. Required in every timing.
* `--timing.at <json>`
* `--timing.every <json>`
* `--timing.once <json>`
* `--timing.cron <json>`
* `--timing.start-at <string>`: No fire before this instant. Inclusive.
* `--timing.end-at <string>`: No fire at or after this instant.
* `--cron-expression <string>`: Five-field cron expression. Prefer timing.
* `--timezone <string>`: IANA time zone the cron expression is evaluated in. Defaults to UTC. Ignored when timing is sent.
* `--[no-]enabled`
* `--[no-]run-on-enable`: When true, enabling the schedule after it was disabled runs it once right away. Creating it does not.
* `--version <integer>`: Workflow version number to run. Omit it to run the published version.
* `--inputs <json>`
* `--inputs.<key> <json>`: One entry. The key is sent as written.
* `--batch-source <json>`: Set to make each tick create a batch from a spreadsheet instead of one execution
* `--batch-source.sheet-url <string>`: Google Sheets URL. The gid selects the tab; without one the first tab is used.
* `--batch-source.column-mappings <json>`: Maps a sheet column header to the workflow input it fills. Unmapped columns are ignored.
* `--batch-source.column-mappings.<key> <string>`: One entry. The key is sent as written.
* `--batch-source.required-inputs <string[]>`: Inputs a row must supply non-empty to count as valid. Rows missing any of them are skipped for that tick rather than failing the whole run. (repeatable)
* `--batch-source.config <json>`: How the resulting batch paces its executions
* `--execution-options <json>`: Per-execution runtime options applied to every run this schedule triggers.
* `--execution-options.variant-key <string>`: Identifies which variant this execution is for, scoping its shared files and scripts to a per-variant subdirectory under each node's shared folder. It does not change which workflow or version runs. Normalised to a filesystem-safe slug by the server. Requires the workflow to have `variant_mode` enabled, and a variant-mode workflow requires it on every execution.
* `--execution-options.soft-timeout-mins <integer>`: Soft timeout in minutes. When the execution has been running longer than this value, a message is injected on every subsequent step urging the agent to wrap up and produce output. Must be greater than 0 and less than the agent's hard timeout (max\_timeout\_mins).

### `asteroid schedule delete <workflow-id> <schedule-id> [flags]`

Delete a schedule so it stops creating runs. Executions it already started are unaffected. To pause instead, call `schedule_update` with `enabled: false`.

* `<workflow-id>`
* `<schedule-id>`

### `asteroid schedule get <workflow-id> <schedule-id> [flags]`

Get one schedule by `scheduleId`.

* `<workflow-id>`
* `<schedule-id>`

### `asteroid schedule list [flags]`

List the cron schedules across every workflow in an organization, most recently updated first. Each has its workflow, cron expression, time zone, enabled flag and next run time. Page with `page` and `pageSize`. Set `includeDisabled` to false to skip disabled schedules.

* `--page-size <integer>`
* `--page <integer>`
* `--[no-]include-disabled`: Include disabled schedules (default true)

### `asteroid schedule update <workflow-id> <schedule-id> [flags]`

Change a schedule's name, cron expression, time zone, inputs, profile or profile group, or toggle `enabled`. Omitted fields keep their value. `clearBatchSource` turns a batch schedule back into single runs; `clearProfileSelection` detaches both profile and profile group.

* `<workflow-id>`
* `<schedule-id>`
* `--name <string>`
* `--profile-id <string>`: Login profile each execution runs with. Mutually exclusive with profileGroupId.
* `--profile-group-id <string>`: Profile group to select a profile from for each execution. Mutually exclusive with profileId.
* `--timing <json>`: Replaces when the schedule fires. Send this or cronExpression, not both. To remove a start or end, send the timing without it.
* `--timing.timezone <string>`: IANA time zone every part is read in, such as America/New\_York. Required in every timing.
* `--timing.at <json>`
* `--timing.every <json>`
* `--timing.once <json>`
* `--timing.cron <json>`
* `--timing.start-at <string>`: No fire before this instant. Inclusive.
* `--timing.end-at <string>`: No fire at or after this instant.
* `--cron-expression <string>`: Five-field cron expression. Replaces the timing with a cron timing. Prefer timing.
* `--timezone <string>`: IANA time zone the timing is read in. Ignored when timing is sent.
* `--[no-]enabled`
* `--[no-]run-on-enable`: When true, enabling the schedule after it was disabled runs it once right away.
* `--version <integer>`: Workflow version number to run. Omit it to keep the current one.
* `--inputs <json>`
* `--inputs.<key> <json>`: One entry. The key is sent as written.
* `--batch-source <json>`: Replaces the batch source. Omit to leave it unchanged; use clearBatchSource to remove it.
* `--batch-source.sheet-url <string>`: Google Sheets URL. The gid selects the tab; without one the first tab is used.
* `--batch-source.column-mappings <json>`: Maps a sheet column header to the workflow input it fills. Unmapped columns are ignored.
* `--batch-source.column-mappings.<key> <string>`: One entry. The key is sent as written.
* `--batch-source.required-inputs <string[]>`: Inputs a row must supply non-empty to count as valid. Rows missing any of them are skipped for that tick rather than failing the whole run. (repeatable)
* `--batch-source.config <json>`: How the resulting batch paces its executions
* `--[no-]clear-batch-source`: Converts a batch schedule back into a single-execution one
* `--[no-]clear-profile-selection`: Detaches both the profile and the pool. Omitting the ids on their own means "leave unchanged", so this is the only way back to no profile.
* `--execution-options <json>`: Per-execution runtime options applied to every run this schedule triggers. Replaces the stored options in full, so send every field you want to keep.
* `--execution-options.variant-key <string>`: Identifies which variant this execution is for, scoping its shared files and scripts to a per-variant subdirectory under each node's shared folder. It does not change which workflow or version runs. Normalised to a filesystem-safe slug by the server. Requires the workflow to have `variant_mode` enabled, and a variant-mode workflow requires it on every execution.
* `--execution-options.soft-timeout-mins <integer>`: Soft timeout in minutes. When the execution has been running longer than this value, a message is injected on every subsequent step urging the agent to wrap up and produce output. Must be greater than 0 and less than the agent's hard timeout (max\_timeout\_mins).

### `asteroid scheduled-execution cancel <scheduled-execution-id> [flags]`

Cancel a pending scheduled execution before it fires. A cancelled item can be revived with `scheduled_execution_reschedule`.

* `<scheduled-execution-id>`

### `asteroid scheduled-execution create [flags]`

Queue one execution of `workflowId` to start at `executeAt` (ISO 8601). Its published version runs unless you pass `workflowVersionId`. Pass `inputs` and optional `metadata`, and a profile with `profileId`. Returns the scheduled item; its `executionId` is set once it fires.

* `--workflow-id <string>`: The workflow to schedule. Its published version runs unless workflowVersionId is set. A workflow version ID is still accepted here and runs that version (deprecated).
* `--workflow-version-id <string>`: The workflow version to schedule. Set this or workflowId.
* `--profile-id <string>`
* `--inputs <json>`
* `--inputs.<key> <json>`: One entry. The key is sent as written.
* `--metadata <json>`: String key/value pairs to label and filter executions.
* `--metadata.<key> <string>`: One entry. The key is sent as written.
* `--execute-at <string>`: When to start the run, in ISO 8601. (required)
* `--execution-options <json>`: Per-execution runtime options applied when this execution is triggered.
* `--execution-options.variant-key <string>`: Identifies which variant this execution is for, scoping its shared files and scripts to a per-variant subdirectory under each node's shared folder. It does not change which workflow or version runs. Normalised to a filesystem-safe slug by the server. Requires the workflow to have `variant_mode` enabled, and a variant-mode workflow requires it on every execution.
* `--execution-options.soft-timeout-mins <integer>`: Soft timeout in minutes. When the execution has been running longer than this value, a message is injected on every subsequent step urging the agent to wrap up and produce output. Must be greater than 0 and less than the agent's hard timeout (max\_timeout\_mins).

### `asteroid scheduled-execution list [flags]`

List one workflow's queued runs: one-off executions created with `scheduled_execution_create`, batch items, and runs held for capacity by `onCapacityLimit: queue`. Filter by `workflowId`, `workflowVersionId`, `status` or `batchId`. Cron schedule ticks do not appear here; they start executions directly.

* `--workflow-id <string>`: Filter by workflow ID. A workflow version ID is still accepted here and filters by that version (deprecated). Set this or workflowVersionId.
* `--workflow-version-id <string>`
* `--status <pending|triggered|cancelled|awaiting_capacity|batch_paused|failed>`
* `--batch-id <string>`
* `--order <asc|desc>`: Sort order for scheduled executions by execute\_at timestamp
* `--page-size <integer>`
* `--page <integer>`

### `asteroid scheduled-execution reschedule <scheduled-execution-id> [flags]`

Give a cancelled scheduled execution a new `executeAt` and return it to pending. Only cancelled items can be rescheduled.

* `<scheduled-execution-id>`
* `--execute-at <string>`: When to start the run, in ISO 8601. (required)

### `asteroid schema validate [flags]`

Check a JSON schema before you use it as an output node's schema. Returns the problems that would stop it from working as structured output.

* `--schema <json>`: (required)
* `--schema.<key> <json>`: One entry. The key is sent as written.

### `asteroid secret delete <secret-id> [flags]`

Delete a secret. Profiles that attached it lose that attachment. Returns 409 when the secret is in use in a way that blocks delete.

* `<secret-id>`

### `asteroid secret field remove <secret-id> <field-key> [flags]`

Remove a field the secret type does not require. Path is secret id plus field key (UPPER\_SNAKE).

* `<secret-id>`
* `<field-key>`: The field's key, in UPPER\_SNAKE case.

### `asteroid secret get <secret-id> [flags]`

Get one secret. Secret values are omitted. Readable field types may include `readableValue`. Use the `placeholder` on each field in agent instructions.

* `<secret-id>`

### `asteroid secret list [flags]`

List organization secrets, one page at a time. Secret values are never returned. Each field includes its ##ITEM\_KEY.FIELD## placeholder. Filter by name or item key with `searchName`. Sort with `sortField` (name, created\_at, updated\_at) and `sortDirection`. Page with `page` and `pageSize`; `total` counts every match. Attach a secret to a profile with `profile_update` (`secretIdsToAdd`).

* `--page-size <integer>`
* `--page <integer>`
* `--search-name <string>`: Case-insensitive substring match on the secret name or item key
* `--sort-field <name|created_at|updated_at>`
* `--sort-direction <asc|desc>`

### `asteroid secret update <secret-id> [flags]`

Update a secret's name and/or item key. A rename leaves the key unchanged. 409 when a profile using this secret already has another secret with the new key. Values are not returned.

* `<secret-id>`

### `asteroid secret versions <secret-id> [flags]`

List a secret's stored versions. Values are never returned.

* `<secret-id>`

### `asteroid secret-request create [flags]`

Create a secret request. The item key is derived from name unless itemKey is given. The recipient URL and its token are returned once and never listed again. Send it to the person who holds the credentials. They submit values on that page, which creates the secret.

* `--title <string>`: Title shown to the recipient of the secret request. (required)
* `--description <string>`: Explanation shown to the recipient of the secret request.
* `--name <string>`: Name of the secret the request creates. (required)
* `--item-key <string>`: Optional UPPER\_SNAKE key. Derived from name when omitted.
* `--template-id <string>`: Org template to snapshot. Mutually exclusive with kind and fields.
* `--kind <login|api_key|card|custom>`: Required when templateId is omitted.
* `--fields <json>`: Inline field blueprint. Required when templateId is omitted.
* `--steps <json>`: Inline step layout. Only valid with kind and fields; rejected with templateId.

### `asteroid secret-request delete <request-id> [flags]`

Delete a secret request in any state. A pending request stops working at once. The secret a completed request created is kept.

* `<request-id>`

### `asteroid secret-request list [flags]`

List organization secret requests. The token is never listed.

### `asteroid secret-request revoke <request-id> [flags]`

Revoke a pending secret request. 409 when the request is not pending.

* `<request-id>`

### `asteroid secret-template create [flags]`

Create an organization secret template (kind, fields, optional steps). Use it later when creating secrets via `templateId`.

* `--kind <login|api_key|card|custom>`: Kind of vault item. Templates and items need at least one field. Completeness is per-field required. (required)
* `--name <string>`: (required)
* `--description <string>`
* `--fields <json>`: (required)
* `--steps <json>`: How the fields are laid out as steps when someone fills in a secret request.

### `asteroid secret-template delete <template-id> [flags]`

Delete an organization secret template.

* `<template-id>`

### `asteroid secret-template duplicate <template-id> [flags]`

Copy a secret template into your organization: an Asteroid template to start using it, or one of your own to make a variant. Pass `name` to name the copy.

* `<template-id>`
* `--name <string>`

### `asteroid secret-template get <template-id> [flags]`

Get one organization secret template by id.

* `<template-id>`

### `asteroid secret-template list [flags]`

List organization secret templates, one page at a time. Filter by name with `searchName`. Sort with `sortField` (name, created\_at) and `sortDirection`. Page with `page` and `pageSize`; `total` counts every match.

* `--page-size <integer>`
* `--page <integer>`
* `--search-name <string>`: Case-insensitive substring match on the template name
* `--sort-field <name|created_at>`
* `--sort-direction <asc|desc>`

### `asteroid secret-template update <template-id> [flags]`

Update an organization secret template's name, description, kind, fields, or steps.

* `<template-id>`
* `--kind <login|api_key|card|custom>`: Kind of vault item. Templates and items need at least one field. Completeness is per-field required.
* `--name <string>`
* `--description <string>`
* `--fields <json>`
* `--steps <json>`: How the fields are laid out as steps when someone fills in a secret request.

### `asteroid skill get <name> [flags]`

Get one skill with the content of every file, SKILL.md first, in the Agent Skills format. A large skill can exceed your result limit: pass `paths` to fetch only some files, such as `SKILL.md` first and then the reference files it names. A link like `../building-workflows/references/drafting.md` is file `references/drafting.md` of skill `building-workflows`. `skills_list` gives every file's path and size. A name resolves to the public skill, then a portal's, then the organization's; set `kind` to pick one. A portal skill needs its portal added with `portal_skills_add`.

* `<name>`
* `--paths <string[]>`: Return only the files at these skill-relative paths, such as `SKILL.md` or `references/nodes.md`. A path that names no file yields no entry. (repeatable)
* `--kind <public|portal|organization>`: Only a skill of this kind.
* `--surface <cli|mcp>`: The surface the skill is rendered for. Defaults to `cli`.

### `asteroid skill list [flags]`

List the skills an organization can load, by kind then name: Asteroid's `public` skills, the `portal` skills (general knowledge of a third-party portal: sign-in, page quirks, field mappings) with whether the organization has added the portal, and the `organization`'s own. Filter with `kind`, or rank by a `query` such as `caloptima eligibility`. Each skill comes with its file paths and digests; `skill_get` returns the content. Add a portal with `portal_skills_add`.

* `--kind <public|portal|organization>`: Only skills of this kind.
* `--query <string>`: A skill name, portal name or task, at least three characters. Best matches first.
* `--surface <cli|mcp>`: The surface the skills are rendered for. Defaults to `cli`.

### `asteroid tag create [flags]`

Create a tag named `name` in a group, by `groupId` or by `protectedGroupKey`. To attach tags to a workflow, use `workflow_tags_patch`, which can also create missing tags by name in one call.

* `--group-id <string>`
* `--protected-group-key <portal|client|task>`: Protected group to create the tag in, materializing its row if needed
* `--name <string>`: Tag name; must not contain '::' (required)
* `--catalog-portal-id <string>`: Catalog portal to link (portal group only). When absent on a portal tag, a live portal with the same name links automatically.

### `asteroid tag delete <tag-id> [flags]`

Delete a tag from the organization. It is removed from every workflow that carried it.

* `<tag-id>`

### `asteroid tag list [flags]`

List an organization's workflow tags with how many workflows carry each. Filter to one group with `groupId`. Tags label workflows for filtering and grouping in the platform.

* `--group-id <string>`
* `--page-size <integer>`
* `--page <integer>`

### `asteroid tag update <tag-id> [flags]`

Rename a tag, or link or unlink the catalog portal it represents.

* `<tag-id>`
* `--name <string>`: New tag name; must not contain '::'. An unlinked portal tag shows a matching live portal's logo automatically; the stored link changes only through explicit linking.
* `--catalog-portal-id <string>`: Catalog portal to link (portal group only)
* `--[no-]unlink-portal`: True unlinks the tag from its catalog portal and stops automatic relinking. Exclusive with catalogPortalId.

### `asteroid tag-group delete <group-id> [flags]`

Delete a user-defined tag group. Its tags and their assignments on workflows are removed with it. The protected groups cannot be deleted.

* `<group-id>`

### `asteroid tag-group list [flags]`

List an organization's workflow tag groups with the number of tags in each. Tags live in groups; some groups are protected and managed by the platform.

* `--page-size <integer>`
* `--page <integer>`

### `asteroid tag-group update <group-id> [flags]`

Rename a user-defined tag group or change its icon. The protected groups (Portal, Client, Task) cannot be changed.

* `<group-id>`
* `--name <string>`: New group name; must not contain '::'
* `--icon <string>`: New lucide icon name; empty string clears it

### `asteroid temp-file upload [flags]`

Upload files before starting an execution, as multipart form field `files`. Pass the returned file references in `tempFiles` on `workflow_execute_post`.

* `--files <path>`: File to upload (repeatable)

### `asteroid tool list [flags]`

List the browser tools an agent node can use at run time, with a description and capability for each. Informational: nodes enable tools through capability flags, not a per-tool allowlist.

### `asteroid workflow create [flags]`

Create a new workflow (not a new version of an existing one). Only `name` is required. Without `version`, the workflow starts blank with a single start node, and version 1 stays unpublished and editable; build it with `workflow_files_patch`. Pass a `version` graph (same shape as `workflow_version_create`) to create it complete. A real graph publishes immediately as version 1 and runs right away with `workflow_execute_post`. A minimal runnable graph has a `start` node, one `iris` agent node, and `success` and `failure` `output` nodes. Check output schemas with `schema_validate`. Until the workflow publishes a version, `workflow_execute_post` runs the latest one. To run on a custom environment, set `settings.custom_environment_id` to an `id` from `custom_environments_list`.

* `--name <string>`: Name for the new workflow. Characters outside the workflow-name charset (letters, digits, spaces, hyphens) are sanitized server-side — create flows carry defaulted names (templates, prebuilt states) the user never typed, which must not fail validation. (required)
* `--version <json>`: The first version of the workflow. Omit it to start from a blank workflow with a single start node.
* `--version.parent-id <string>`: Optional parent workflow ID to derive from
* `--version.rules <string>`
* `--version.graph <json>`
* `--version.graph.nodes <json>`
* `--version.graph.transitions <json>`
* `--version.graph.sticky_notes <json>`
* `--version.inputs <json>`: Typed input definitions for this workflow. Names referenced in prompts but omitted here default to optional strings.
* `--version.settings <json>`: Configuration settings for workflow execution
* `--version.settings.viewport_width <integer>`: Browser viewport width in pixels
* `--version.settings.viewport_height <integer>`: Browser viewport height in pixels
* `--version.settings.max_timeout_mins <integer>`: Maximum timeout in minutes
* `--version.settings.custom_environment_id <string>`: Custom environment executions of this workflow boot on: its environment type and snapshot replace the workflow's own environment, its profile rows restrict which profile an execution may use, and a kept-warm environment hands out a pre-warmed copy. On a new version, omit it to keep the environment of the workflow's latest version (its editable head, which can be newer than the published one), or send null to boot the workflow's own environment. On a new workflow, there is nothing to keep: omit it or send null for no custom environment.
* `--version.environment-template <json>`: Optional environment template. On a new version, omit it to keep the template of the workflow's latest version (its editable head); on a new workflow, omitting it means a browser. Omits admin-only OS fields.
* `--version.environment-template.type <browser|os>`: Type of execution environment
* `--version.environment-template.config <json>`

### `asteroid workflow delete <workflow-id> [flags]`

Permanently delete a workflow and all of its versions by `workflowId`. This is irreversible. Only allowed when all of the workflow's executions are in a terminal status (completed, cancelled, or failed); otherwise the request is rejected.

* `<workflow-id>`

### `asteroid workflow duplicate <workflow-id> [flags]`

Copy a workflow's current editable head, including its scripts and shared files, into a new workflow. Pass `name` to override the copied name. Returns the new workflow and version IDs.

* `<workflow-id>`
* `--name <string>`: Optional name for the duplicate. Letters, digits, spaces, and punctuation excluding \_ \< > : " / \ | ? and \*. Defaults to the source workflow's name with a " (Copy)" suffix.

### `asteroid workflow execute <workflow-id> [flags]`

Start an execution. It runs the published version unless you pass `version` (a version number) or `head: true` (the unpublished editable head). Pass `inputs` for the workflow's input variables (see `workflow_version_inputs_get`), `profileId` or `profileGroupId` for the login, `tempFiles` for staged files, and optional `metadata`. When the organization is at its concurrency limit, `onCapacityLimit: queue` queues the run instead of failing. Returns the `executionId`; follow it with `execution_get`.

* `<workflow-id>`
* `--profile-id <string>`: The ID of the login profile to use for this execution. Mutually exclusive with profileGroupId.
* `--profile-group-id <string>`: The ID of the profile group to select a profile from. Mutually exclusive with profileId.
* `--inputs <json>`: Inputs to be merged into the placeholders defined in prompts
* `--inputs.<key> <json>`: One entry. The key is sent as written.
* `--temp-files <json>`: Array of temporary files to attach to the execution. Must have been pre-uploaded using the stage file endpoint
* `--metadata <json>`: Optional metadata key-value pairs (string keys and string values) for organizing and filtering executions
* `--metadata.<key> <string>`: One entry. The key is sent as written.
* `--version <integer>`: The version of the workflow to execute. If neither version nor head is provided, the published version is used.
* `--[no-]head`: Run the editable head instead of the published version. Cannot be combined with version.
* `--execution-options <json>`: Per-execution runtime options that override or extend the workflow's default settings.
* `--execution-options.variant-key <string>`: Identifies which variant this execution is for, scoping its shared files and scripts to a per-variant subdirectory under each node's shared folder. It does not change which workflow or version runs. Normalised to a filesystem-safe slug by the server. Requires the workflow to have `variant_mode` enabled, and a variant-mode workflow requires it on every execution.
* `--execution-options.soft-timeout-mins <integer>`: Soft timeout in minutes. When the execution has been running longer than this value, a message is injected on every subsequent step urging the agent to wrap up and produce output. Must be greater than 0 and less than the agent's hard timeout (max\_timeout\_mins).
* `--on-capacity-limit <reject|queue>`: What to do when the execution cannot start right now because the organisation is at its concurrency limit or every profile in the pool is in use. "reject" (the default) fails the request as today. "queue" accepts it: the execution is created in the "queued" status under the returned ID and starts automatically, oldest first, as capacity frees. Temp files cannot be queued.

### `asteroid workflow execute-sync <workflow-id> [flags]`

Start an execution and wait up to `timeoutSeconds` (1-25, default 25) for it to finish. Takes the same body as `workflow_execute_post`. Returns the terminal `status` and `executionResult` when it finishes in time. Otherwise returns `executionId` and the current status: the execution keeps running, so follow it with `execution_get` rather than calling this again, which would start a second execution. Use it for workflows that finish in seconds.

* `<workflow-id>`
* `--profile-id <string>`: The ID of the login profile to use for this execution. Mutually exclusive with profileGroupId.
* `--profile-group-id <string>`: The ID of the profile group to select a profile from. Mutually exclusive with profileId.
* `--inputs <json>`: Inputs to be merged into the placeholders defined in prompts
* `--inputs.<key> <json>`: One entry. The key is sent as written.
* `--temp-files <json>`: Array of temporary files to attach to the execution. Must have been pre-uploaded using the stage file endpoint
* `--metadata <json>`: Optional metadata key-value pairs (string keys and string values) for organizing and filtering executions
* `--metadata.<key> <string>`: One entry. The key is sent as written.
* `--version <integer>`: The version of the workflow to execute. If neither version nor head is provided, the published version is used.
* `--[no-]head`: Run the editable head instead of the published version. Cannot be combined with version.
* `--execution-options <json>`: Per-execution runtime options that override or extend the workflow's default settings.
* `--execution-options.variant-key <string>`: Identifies which variant this execution is for, scoping its shared files and scripts to a per-variant subdirectory under each node's shared folder. It does not change which workflow or version runs. Normalised to a filesystem-safe slug by the server. Requires the workflow to have `variant_mode` enabled, and a variant-mode workflow requires it on every execution.
* `--execution-options.soft-timeout-mins <integer>`: Soft timeout in minutes. When the execution has been running longer than this value, a message is injected on every subsequent step urging the agent to wrap up and produce output. Must be greater than 0 and less than the agent's hard timeout (max\_timeout\_mins).
* `--on-capacity-limit <reject|queue>`: What to do when the execution cannot start right now because the organisation is at its concurrency limit or every profile in the pool is in use. "reject" (the default) fails the request as today. "queue" accepts it: the execution is created in the "queued" status under the returned ID and starts automatically, oldest first, as capacity frees. Temp files cannot be queued.
* `--timeout-seconds <integer>`: Seconds to wait for the execution to finish before returning 202. Defaults to 25.

### `asteroid workflow get <workflow-id> [flags]`

Get one workflow by `workflowId`: the workflow record, its published version (or the version named by `version`), and metadata for every version. Use this instead of paging `workflow_list` when you already know the ID.

* `<workflow-id>`
* `--version <integer>`: Optional published version number to return

### `asteroid workflow head publish <workflow-id> [flags]`

Publish the workflow's editable head, assigning it the next version number and making it the default for `workflow_execute_post`. Use after `workflow_files_patch`; `workflow_version_publish` does the same for a version you already have the ID of. `schemaChanges` lists the input and output schema changes against the version published before, which can break callers that send inputs or read outputs by name.

* `<workflow-id>`

### `asteroid workflow head revert <workflow-id> [flags]`

Replace the workflow's editable head with the version named by `versionId`, so that version becomes the draft again. Unpublished edits on the head are lost. Returns the resulting version.

* `<workflow-id>`
* `--version-id <string>`: The ID of the version to copy over the editable head (required)

### `asteroid workflow head snapshot <workflow-id> [flags]`

Pin the editable head's current state and return its `versionId`, so `workflow_version_execute` can run exactly what is edited without publishing. Nothing changes for other callers.

* `<workflow-id>`

### `asteroid workflow head validate <workflow-id> [flags]`

Check the workflow's editable head the way publish and run do, without changing it. Returns blocking errors and advisory warnings, each with the path of the field it names, such as \["nodes", "Login", "model"]. Use after `workflow_files_patch` and before `workflow_head_publish`; an empty `issues` list means the head can publish and run. The same list comes back on every `workflow_files_patch` response.

* `<workflow-id>`

### `asteroid workflow list [flags]`

List workflows, one page at a time. Filter by name with `searchName`. Filter by tags with `tagIds` (from `workflow_tags_list`): `tagMatch=any` (the default) needs at least one of the tags, `all` needs every one. `withoutTagGroupId` keeps only workflows with no tag in that group. Sort with `sortField` and `sortDirection`. Page with `page` and `pageSize`; `total` counts every match.

* `--page-size <integer>`
* `--page <integer>`
* `--search-name <string>`: Return results whose name contains this text, case-insensitive.
* `--sort-field <name|created_at>`
* `--sort-direction <asc|desc>`
* `--tag-ids <string[]>`: Restrict the results to workflows carrying these tags (repeatable)
* `--tag-match <any|all>`: How tagIds combine: any (default) or all
* `--without-tag-group-id <string>`: Restrict the results to workflows with no tag in this group. Backs the 'No \<group>' bucket.

### `asteroid workflow list-stats [flags]`

List workflows with execution stats on each row, like the platform's workflows table: execution and version counts, last run time, average run time and the last 5 executions. Takes the same filters as `workflow_list`: `searchName`, `tagIds` with `tagMatch`, `withoutTagGroupId`. Sort by `sortField`, including `execution_count` and `last_execution_start_time`. Page with `page` and `pageSize`.

* `--page-size <integer>`
* `--page <integer>`
* `--search-name <string>`: Return results whose name contains this text, case-insensitive.
* `--agent-id <string[]>`: (repeatable)
* `--sort-field <name|created_at|latest_version_created_at|last_execution_start_time|execution_count|version_count>`
* `--sort-direction <asc|desc>`
* `--tag-ids <string[]>`: Restrict the results to workflows carrying these tags (repeatable)
* `--tag-match <any|all>`: How tagIds combine: any (default) or all
* `--without-tag-group-id <string>`: Restrict the results to workflows with no tag in this group. Backs the 'No \<group>' bucket.

### `asteroid workflow notification create <workflow-id> [flags]`

Send a workflow's events to an integration. `eventRules` omitted sends every event, `[]` sends none, a list sends only matching events (see event\_types\_list for event types and filter fields). `metadataFilter` sends only executions whose metadata matches every key and value. One rule per integration per workflow.

* `<workflow-id>`
* `--integration-id <string>`: (required)
* `--event-rules <json>`: Event notification rules. Three possible states: null/omitted (notify on ALL events), \[] (notify on NO events), \[A,B,C] (notify only on specific events)
* `--metadata-filter <json>`: Metadata filter for execution routing. Only sends notifications for executions whose metadata matches all specified key-value pairs. Null or omitted means no filtering.
* `--metadata-filter.<key> <string>`: One entry. The key is sent as written.

### `asteroid workflow notification delete <workflow-id> <integration-id> [flags]`

Stop sending a workflow's events to one integration.

* `<workflow-id>`
* `<integration-id>`

### `asteroid workflow notification list <workflow-id> [flags]`

List the notification rules of a workflow. Each sends events to one integration.

* `<workflow-id>`

### `asteroid workflow notification update <workflow-id> <integration-id> [flags]`

Replace the `eventRules` and `metadataFilter` of the workflow's rule for one integration. Omitted fields are cleared.

* `<workflow-id>`
* `<integration-id>`
* `--event-rules <json>`: Event notification rules. Three possible states: null/omitted (notify on ALL events), \[] (notify on NO events), \[A,B,C] (notify only on specific events)
* `--metadata-filter <json>`: Metadata filter for execution routing. Only sends notifications for executions whose metadata matches all specified key-value pairs. Null or omitted clears any existing filter.
* `--metadata-filter.<key> <string>`: One entry. The key is sent as written.

### `asteroid workflow pull <workflow-id> [flags]`

List the workflow's editable head as a directory of files: the graph rendered as structural files (settings.yaml, per-node instructions.md, scripts) alongside the workflow's own files. Those files are referenced by fileId unless contents=all is set. Pass paths to read named files only, or contents=none for a manifest with no bodies. The returned rev is what you pass as baseRev to write.

* `<workflow-id>`
* `--contents <none|structural|all>`: Which contents come inline: none (a pure manifest), structural (the default), or all (structural plus file bytes within the response budget).
* `--paths <string[]>`: Return only the files at these exact tree paths. A path that names nothing yields no entry. The inline budget applies to the filtered set, so a narrow read can inline files a whole-tree read would have to skip. (repeatable)
* `--variants <string>`: Narrow which variants/\<key>/ files the tree carries: "none" strips every variant, a comma-separated list keeps only those variant keys. Files outside variants/ are always kept, and the response's variantKeys still names every variant. Ignored unless the workflow has variant mode enabled; absent keeps every variant.
* `--max-file-bytes <integer>`: Per-file ceiling, in bytes, for inlined file contents. Clamped to the server maximum. Files above the ceiling stay references.
* `--max-total-bytes <integer>`: Ceiling, in bytes, on the total inlined file contents in one response. Clamped to the server maximum. Files are admitted in path order until the ceiling is reached; the rest stay references.
* `--out <dir>`: Write here instead of ./\<workflow-name>/head (a version: ./\<workflow-name>/.versions/...). --json prints the file listing instead
* `--keep-edits`: Into a folder pulled before: keep every file you edited since that pull and refresh the rest. From a head, a later push sends those edits on top of the new revision

### `asteroid workflow push [workflow-id] [flags]`

Write and delete files on the workflow's editable head in one patch. Structural files re-derive the graph; the workflow's own files go to its file store, you just write paths. Pass the rev from `workflow_files_list` as baseRev; a stale value is rejected with 409, so re-read and retry. Editing a published or already-executed version forks a new one instead of rewriting it. Each write carries the file as `content` (UTF-8 text) or `contentBase64` (base64 bytes, for binary files), exactly one.

* `[workflow-id]`
* `--base-rev <integer>`: The revision this edit is based on. Agent-file-only patches overlay the current head even when this is stale. A structural-file patch is rejected with 409 when it does not match the stored head revision. (required)
* `--writes <json>`: Files to upsert. (required)
* `--deletes <string[]>`: (required, repeatable)
* `--from <dir>`: The pulled head folder to push. Defaults to the current folder
* `--rebase`: When the head moved since your pull, pull it with --keep-edits and push again, twice at most

### `asteroid workflow rename <workflow-id> [flags]`

Rename an existing workflow: set a new human-friendly `name` for the workflow identified by `workflowId`. The name must be non-empty and 100 characters or less.

* `<workflow-id>`
* `--name <string>`: New name for the workflow. Letters, digits, spaces, and punctuation excluding \_ \< > : " / \ | ? and \*.

### `asteroid workflow schedules <workflow-id> [flags]`

List the cron schedules on a workflow, each with its cron expression, time zone, enabled flag, inputs and next run time.

* `<workflow-id>`

### `asteroid workflow stats <workflow-id> [flags]`

Per-workflow execution counts and outcomes as a time series plus a summary, for `timeRange` 7d, 30d, 90d or all. Filter to specific `version` numbers to compare versions.

* `<workflow-id>`
* `--time-range <7d|30d|90d|all>`: `7d`, `30d`, `90d` or `all`. Defaults to `30d`.
* `--version <integer[]>`: Restrict the statistics to these version numbers (repeatable)
* `--timezone <string>`: IANA time zone for bucketing. Defaults to UTC.

### `asteroid workflow tag list <workflow-id> [flags]`

List the tags attached to one workflow. `workflow_tags_list` lists every tag in the organization instead.

* `<workflow-id>`

### `asteroid workflow tag set <workflow-id> [flags]`

Change a workflow's tags in one call: `add` existing tag IDs, `create` tags by group and name (created when missing, along with the group), and `remove` tag IDs. Returns the resulting tag set.

* `<workflow-id>`
* `--add <string[]>`: Existing tag ids to add; all must be in the workflow's organization (repeatable)
* `--create <json>`: Tags to add by name, created when missing
* `--remove <string[]>`: (repeatable)

### `asteroid workflow validate [flags]`

Check the `version` spec you are about to pass to `workflow_create`, without creating anything. Returns `issues`, each with a `severity` (`error` blocks creation, `warning` is advisory), a `message`, and a `path` to the offending field. Reports every issue, where create surfaces one at a time. Use this for a new workflow; for a new version of an existing workflow use `workflow_version_validate`. Several rules relate a transition to the node it leaves: the `start` node's single outgoing transition must be `outcome_success` and must not point at an output node. No JSON schema expresses them, so this is the only way to catch them before the call.

* `--parent-id <string>`: Optional parent workflow ID to derive from
* `--rules <string>`: (required)
* `--graph <json>`: (required)
* `--graph.nodes <json>`
* `--graph.transitions <json>`
* `--graph.sticky_notes <json>`
* `--inputs <json>`: Typed input definitions for this workflow. Names referenced in prompts but omitted here default to optional strings.
* `--settings <json>`: Configuration settings for workflow execution (required)
* `--settings.viewport_width <integer>`: Browser viewport width in pixels
* `--settings.viewport_height <integer>`: Browser viewport height in pixels
* `--settings.max_timeout_mins <integer>`: Maximum timeout in minutes
* `--settings.custom_environment_id <string>`: Custom environment executions of this workflow boot on: its environment type and snapshot replace the workflow's own environment, its profile rows restrict which profile an execution may use, and a kept-warm environment hands out a pre-warmed copy. On a new version, omit it to keep the environment of the workflow's latest version (its editable head, which can be newer than the published one), or send null to boot the workflow's own environment. On a new workflow, there is nothing to keep: omit it or send null for no custom environment.
* `--environment-template <json>`: Optional environment template. On a new version, omit it to keep the template of the workflow's latest version (its editable head); on a new workflow, omitting it means a browser. Omits admin-only OS fields.
* `--environment-template.type <browser|os>`: Type of execution environment
* `--environment-template.config <json>`

### `asteroid workflow version create <workflow-id> [flags]`

Create a version from a full graph (nodes, transitions), rules and settings. To edit a workflow, prefer `workflow_files_patch` on the editable head, then `workflow_head_publish`. Set `parentId` to the current version's ID to maintain lineage. The new version is unpublished until you call `workflow_version_publish`. Settings and fields the request omits keep the values of the workflow's latest version (its editable head, which can be newer than the published one): leave out `settings.custom_environment_id` to stay on the same custom environment, set it to switch, or send `null` to boot the workflow's own environment. Leave out `environmentTemplate` to keep the latest version's.

* `<workflow-id>`
* `--parent-id <string>`: Optional parent workflow ID to derive from
* `--rules <string>`: (required)
* `--graph <json>`: (required)
* `--graph.nodes <json>`
* `--graph.transitions <json>`
* `--graph.sticky_notes <json>`
* `--inputs <json>`: Typed input definitions for this workflow. Names referenced in prompts but omitted here default to optional strings.
* `--settings <json>`: Configuration settings for workflow execution (required)
* `--settings.viewport_width <integer>`: Browser viewport width in pixels
* `--settings.viewport_height <integer>`: Browser viewport height in pixels
* `--settings.max_timeout_mins <integer>`: Maximum timeout in minutes
* `--settings.custom_environment_id <string>`: Custom environment executions of this workflow boot on: its environment type and snapshot replace the workflow's own environment, its profile rows restrict which profile an execution may use, and a kept-warm environment hands out a pre-warmed copy. On a new version, omit it to keep the environment of the workflow's latest version (its editable head, which can be newer than the published one), or send null to boot the workflow's own environment. On a new workflow, there is nothing to keep: omit it or send null for no custom environment.
* `--environment-template <json>`: Optional environment template. On a new version, omit it to keep the template of the workflow's latest version (its editable head); on a new workflow, omitting it means a browser. Omits admin-only OS fields.
* `--environment-template.type <browser|os>`: Type of execution environment
* `--environment-template.config <json>`

### `asteroid workflow version delete <workflow-id> <version-id> [flags]`

Delete an unpublished workflow version that has no executions. Published versions and versions with runs are refused.

* `<workflow-id>`
* `<version-id>`

### `asteroid workflow version execute <workflow-id> <version-id> [flags]`

Run one version by `versionId`, published or not, to test it before publishing. Takes `inputs`, `profileId` or `profileGroupId`, `tempFiles` and `metadata`, like `workflow_execute_post`.

* `<workflow-id>`
* `<version-id>`
* `--inputs <json>`: Inputs to be merged into the placeholders defined in prompts. Do not set together with inputVariables.
* `--inputs.<key> <json>`: One entry. The key is sent as written.
* `--metadata <json>`: Optional metadata key-value pairs for organizing and filtering executions
* `--metadata.<key> <string>`: One entry. The key is sent as written.
* `--profile-id <string>`: The ID of the login profile to use. Mutually exclusive with profileGroupId.
* `--profile-group-id <string>`: The ID of the profile group to select a profile from. Mutually exclusive with profileId.
* `--temp-files <json>`: Array of temporary files to attach to the execution. Must have been pre-uploaded using the stage file endpoint
* `--execution-options <json>`: Per-execution runtime options that override or extend the workflow's default settings.
* `--execution-options.variant-key <string>`: Identifies which variant this execution is for, scoping its shared files and scripts to a per-variant subdirectory under each node's shared folder. It does not change which workflow or version runs. Normalised to a filesystem-safe slug by the server. Requires the workflow to have `variant_mode` enabled, and a variant-mode workflow requires it on every execution.
* `--execution-options.soft-timeout-mins <integer>`: Soft timeout in minutes. When the execution has been running longer than this value, a message is injected on every subsequent step urging the agent to wrap up and produce output. Must be greater than 0 and less than the agent's hard timeout (max\_timeout\_mins).
* `--parent-execution-id <string>`: ID of the execution this is a rerun of. Sets parent\_execution\_id on the new execution and has\_been\_rerun on the parent.

### `asteroid workflow version file url <workflow-id> <version-id> <file-id> [flags]`

Get a short-lived signed URL for downloading one of a workflow version's files directly from storage. Prefer this over a redirect-based download when reading a file's contents.

* `<workflow-id>`
* `<version-id>`
* `<file-id>`

### `asteroid workflow version get <workflow-id> <version-id> [flags]`

Get a full workflow version by `versionId`, including the complete node graph, rules, and settings.

* `<workflow-id>`
* `<version-id>`

### `asteroid workflow version inputs <workflow-id> <version-id> [flags]`

List the input variable names a workflow version accepts at execution time. Use it to build the `inputs` object before `workflow_execute_post` or `workflow_version_execute`.

* `<workflow-id>`
* `<version-id>`

### `asteroid workflow version list <workflow-id> [flags]`

List all versions of a workflow (lightweight refs with IDs, parents, and version numbers).

* `<workflow-id>`

### `asteroid workflow version output-schemas <workflow-id> <version-id> [flags]`

Return the JSON schemas configured on a workflow version's output nodes, keyed by output node name. Tells you the shape of `executionResult.result` for runs of that version.

* `<workflow-id>`
* `<version-id>`

### `asteroid workflow version publish <workflow-id> <version-id> [flags]`

Publish a workflow version, assigning it a permanent version number and making it the default for `workflow_execute_post`. This also publishes an older version again. `schemaChanges` lists the input and output schema changes against the version published before, which can break callers that send inputs or read outputs by name.

* `<workflow-id>`
* `<version-id>`

### `asteroid workflow version pull <workflow-id> <version-id> [flags]`

List a version's files, like `workflow_files_list` does for the editable head. Versions are immutable, so this is read-only.

* `<workflow-id>`
* `<version-id>`
* `--contents <none|structural|all>`: Which contents come inline: none (a pure manifest), structural (the default), or all (structural plus file bytes within the response budget).
* `--paths <string[]>`: Return only the files at these exact tree paths. A path that names nothing yields no entry. The inline budget applies to the filtered set, so a narrow read can inline files a whole-tree read would have to skip. (repeatable)
* `--variants <string>`: Narrow which variants/\<key>/ files the tree carries: "none" strips every variant, a comma-separated list keeps only those variant keys. Files outside variants/ are always kept, and the response's variantKeys still names every variant. Ignored unless the workflow has variant mode enabled; absent keeps every variant.
* `--max-file-bytes <integer>`: Per-file ceiling, in bytes, for inlined file contents. Clamped to the server maximum. Files above the ceiling stay references.
* `--max-total-bytes <integer>`: Ceiling, in bytes, on the total inlined file contents in one response. Clamped to the server maximum. Files are admitted in path order until the ceiling is reached; the rest stay references.
* `--out <dir>`: Write here instead of ./\<workflow-name>/head (a version: ./\<workflow-name>/.versions/...). --json prints the file listing instead
* `--keep-edits`: Into a folder pulled before: keep every file you edited since that pull and refresh the rest. From a head, a later push sends those edits on top of the new revision

### `asteroid workflow version validate <workflow-id> [flags]`

Check a version spec against an existing workflow without persisting it, returning the same `issues` list as `workflow_spec_validate`. Use before `workflow_version_create` when revising a workflow; use `workflow_spec_validate` when there is no workflow yet.

* `<workflow-id>`
* `--parent-id <string>`: Optional parent workflow ID to derive from
* `--rules <string>`: (required)
* `--graph <json>`: (required)
* `--graph.nodes <json>`
* `--graph.transitions <json>`
* `--graph.sticky_notes <json>`
* `--inputs <json>`: Typed input definitions for this workflow. Names referenced in prompts but omitted here default to optional strings.
* `--settings <json>`: Configuration settings for workflow execution (required)
* `--settings.viewport_width <integer>`: Browser viewport width in pixels
* `--settings.viewport_height <integer>`: Browser viewport height in pixels
* `--settings.max_timeout_mins <integer>`: Maximum timeout in minutes
* `--settings.custom_environment_id <string>`: Custom environment executions of this workflow boot on: its environment type and snapshot replace the workflow's own environment, its profile rows restrict which profile an execution may use, and a kept-warm environment hands out a pre-warmed copy. On a new version, omit it to keep the environment of the workflow's latest version (its editable head, which can be newer than the published one), or send null to boot the workflow's own environment. On a new workflow, there is nothing to keep: omit it or send null for no custom environment.
* `--environment-template <json>`: Optional environment template. On a new version, omit it to keep the template of the workflow's latest version (its editable head); on a new workflow, omitting it means a browser. Omits admin-only OS fields.
* `--environment-template.type <browser|os>`: Type of execution environment
* `--environment-template.config <json>`


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.