Skip to main content
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; 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>