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.
Downloads write raw bytes. login, logout and use 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.
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.
Commands
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 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 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.
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. Users create and edit custom environments on the platform’s Environments page; no tool changes them.
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. 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). The workflow arm needs a workflow to resolve against, so it requiresworkflowId.--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’sconnectiononly 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 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)
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)
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.
<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 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.--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.
<execution-id>
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 update <insight-id> [flags]
Change an insight’s name, content or status. Omitted fields keep their value. The status must be valid for the insight’s type: a recommendation is open, actioned or dismissed; an overview is unread or read.
<insight-id>--name <string>--content <string>--status <string>: New status. Must be one of the insight type’s statuses.
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 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 (create them with secrets_create).
--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 agent’s inbox email 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)--proxy-mode <none|managed|custom|gateway>: Filter by proxy mode (can specify multiple, there is an ‘OR’ condition applied to these) (repeatable)--operating-system <macos|windows>: Filter by emulated operating system (can specify multiple, there is an ‘OR’ condition applied to these). Profiles without an explicit operating system count as macOS. (repeatable)--feature <extraStealth|allow3rdCookies|captchaSolverActive|stickyIP|cachePersistence|adblockActive|popupBlockerActive|forcePopupsAsTabsActive|mediaBlockerActive>: Filter by active browser features (can specify multiple, there is an ‘AND’ condition applied to these — every listed feature must be enabled) (repeatable)--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 agent’s inbox email 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 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.--cron-expression <string>: Five-field cron expression. (required)--timezone <string>: IANA time zone the cron expression is evaluated in. Defaults to UTC.--[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>--batch-source <json>: Set to make each tick create a batch from a spreadsheet instead of one execution--execution-options <json>: Per-execution runtime options applied to every run this schedule triggers.
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.--cron-expression <string>: Five-field cron expression.--timezone <string>: IANA time zone the cron expression is evaluated in.--[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>--batch-source <json>: Replaces the batch source. Omit to leave it unchanged; use clearBatchSource to remove it.--[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.
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>--metadata <json>: String key/value pairs to label and filter executions.--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.
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)
asteroid secret create [flags]
Create an organization secret. The item key is derived from name unless itemKey is given. Values are stored; responses are masked. Pass either templateId or kind+fields, plus values. Attach the returned id to a profile with profile_update.secretIdsToAdd. Reference fields as ##ITEM_KEY.FIELD##. Many secrets may share a key; a profile cannot attach two secrets with the same key.
--name <string>: (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.--values <json>: Field values askey/valuepairs. (required)
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 add <secret-id> [flags]
Add a non-required field to a secret. Pass field (label, type, required) and value. Secret values are never returned.
<secret-id>--field <json>: Write shape for a field. The server derives key from label. (required)--value <string>: (required)
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 rotate <secret-id> [flags]
Replace field values on a secret in one write. Supply values as key/value pairs. Secret values are never returned.
<secret-id>--values <json>: New field values askey/valuepairs. (required)
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 share token is returned once and never listed again. The recipient submits values on the public page; that 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 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 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.
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--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--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.--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--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--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.--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 file list <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.
asteroid workflow file patch <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 contentBase64: base64-encode the file content, plain text is rejected with 400.
<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)
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.
<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 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 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,90dorall. Defaults to30d.--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)--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)--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.
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)--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)--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.
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.--metadata <json>: Optional metadata key-value pairs for organizing and filtering executions--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.--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 list <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.
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.
<workflow-id><version-id>
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)--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)--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.