> ## Documentation Index > Fetch the complete documentation index at: https://docs.asteroid.ai/llms.txt > Use this file to discover all available pages before exploring further. # CLI reference > Every asteroid command, its arguments and its flags Sign in with `asteroid login`, or set `ASTEROID_API_KEY` for CI and agents. Commands that return data print compact text. Add `--json` to get the response as JSON. The text output may change between releases. Scripts should read `--json`. 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 `: Act in this organization for one command. Also ASTEROID\_ORG. * `--body `: Request body as JSON, a file, or stdin. Flags override its fields. * `--output `: 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 ` 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 [flags]` Cancel a batch and every item it has not yet triggered. Runs already started continue. A cancelled batch cannot be resumed. * `` ### `asteroid batch get [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`. * `` ### `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 `: Filter by workflow ID. Set this or agentId. * `--status `: Execution batch status * `--page-size ` * `--page ` ### `asteroid batch pause [flags]` Pause a running batch. Items not yet triggered wait; runs already started continue. Resume with `execution_batch_resume`. * `` ### `asteroid batch resume [flags]` Resume a paused batch. Trigger times for the remaining items are recalculated from now. * `` ### `asteroid context [flags]` Get who you are: your user ID and email, and the organizations this request can act in, with IDs and names. With an organization API key there is no user, so the ID and email are empty. When you belong to several organizations, use this to find the `organizationId` to pass. The Asteroid platform is at [https://platform.asteroid.ai](https://platform.asteroid.ai); use it as the base for dashboard links. ### `asteroid custom-environment get [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. * `` ### `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 `: (required) * `--format `: How search result content is returned ### `asteroid environment get [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. * `` ### `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 `: Only environments bound to this workflow. Omit for every standalone environment in the organisation, the unbound ones included. * `--lifecycle `: 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 `: 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 `: 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 requires `workflowId`. * `--profile-id `: 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 [flags]` Stop a running standalone environment by environment ID. Idempotent: stopping an already-stopped environment is a no-op. * `` ### `asteroid execution activities [flags]` List an execution's activity log: what the agent did, step by step. Set `order` (asc or desc by time) and `limit`. * `` * `--order `: Sort order for activities by timestamp * `--limit ` ### `asteroid execution cancel [flags]` Cancel an execution. The execution stops and cannot be resumed. * `` ### `asteroid execution context-file download [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. * `` * `` ### `asteroid execution context-file list [flags]` List the files attached to an execution, such as `tempFiles` staged before it started. Download one with `execution_context_file_signed_url`. * `` ### `asteroid execution context-file upload [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`. * `` * `--files `: File to upload (repeatable) ### `asteroid execution context-file url [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`. * `` * `` ### `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 `: Search by execution ID (partial, case-insensitive match) * `--status `: Filter by execution status (can specify multiple, there is an 'OR' condition applied to these) (repeatable) * `--created-after ` * `--created-before ` * `--human-labels `: Filter by human labels (can specify multiple label IDs, there is an 'OR' condition applied to these) (repeatable) * `--outcome-label `: Filter by execution result outcome (partial, case-insensitive match) * `--metadata-key `: Filter by metadata key - must be used together with metadataValue * `--metadata-value `: Filter by metadata value - must be used together with metadataKey * `--inputs-key `: Filter by input variable key - must be used together with inputsValue * `--inputs-value `: Filter by input variable value (partial, case-insensitive match) - must be used together with inputsKey * `--workflow-version ` * `--[no-]has-script-failures` * `--trigger-source `: Filter by how the execution was triggered (can specify multiple, there is an 'OR' condition applied to these) (repeatable) * `--phase `: 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 ` * `--created-within `: 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 `: Filter by metadata key=value pairs. Repeat the parameter for several pairs; every pair must match (repeatable) * `--profile-ids `: Filter by login profile IDs (can specify multiple, there is an 'OR' condition applied to these) (repeatable) ### `asteroid execution file download [flags]` Download one execution file by `fileId`, from the listing returned by `execution_files_get`. The response redirects to the file in storage. * `` * `` ### `asteroid execution file list [flags]` List an execution's files, grouped by directory (uploads, downloads, workspace, shared). Download one with `execution_file_signed_url`. * `` ### `asteroid execution file url [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. * `` * `` ### `asteroid execution get [flags]` Get one execution: status, result, timing, workflow and version, inputs, metadata, profile, and live-view and recording URLs. * `` ### `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 ` * `--page ` * `--execution-id `: Search by execution ID (partial, case-insensitive match) * `--status `: Filter by execution status (can specify multiple, there is an 'OR' condition applied to these) (repeatable) * `--created-after ` * `--created-before ` * `--human-labels `: Filter by human labels (can specify multiple label IDs, there is an 'OR' condition applied to these) (repeatable) * `--outcome-label `: Filter by execution result outcome (partial, case-insensitive match) * `--metadata-key `: Filter by metadata key - must be used together with metadataValue * `--metadata-value `: Filter by metadata value - must be used together with metadataKey * `--inputs-key `: Filter by input variable key - must be used together with inputsValue * `--inputs-value `: Filter by input variable value (partial, case-insensitive match) - must be used together with inputsKey * `--workflow-version ` * `--[no-]has-script-failures` * `--trigger-source `: Filter by how the execution was triggered (can specify multiple, there is an 'OR' condition applied to these) (repeatable) * `--phase `: 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 `: Fields that can be used for sorting executions * `--sort-direction ` * `--workflow-id ` * `--created-within `: 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 `: Filter by metadata key=value pairs. Repeat the parameter for several pairs; every pair must match (repeatable) * `--sort `: 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 `: Filter by login profile IDs (can specify multiple, there is an 'OR' condition applied to these) (repeatable) ### `asteroid execution message [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. * `` * `--message `: 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 [flags]` Pause a running execution. Resume it later with `execution_resume`. * `` ### `asteroid execution recording [flags]` Download an execution's browser recording. The response redirects to the recording file. * `` * `--token `: Optional token for authentication. Use this when the client cannot set Authorization headers (e.g., native video elements). ### `asteroid execution rerun [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. * `` * `--inputs `: Input variables for the new execution. Replaces the original inputs when set. * `--profile-id `: The ID of the login profile to use. Replaces the original profile when set. ### `asteroid execution resume [flags]` Resume a paused execution. It continues from where it stopped. * `` ### `asteroid insight get [flags]` Get one insight with its markdown content, status and the question it puts to the user, if any. * `` ### `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 `: Only insights produced by this Astro chat. * `--workflow-id ` * `--status `: Filter by insight status (can specify multiple, there is an 'OR' condition applied to these) (repeatable) * `--page-size ` * `--page ` ### `asteroid insight update [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. * `` * `--name ` * `--content ` * `--status `: 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 [flags]` Clear the persisted browser cache (cookies, storage) for a login profile, resetting its browser state. * `` ### `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 `: Name of the agent profile (must be unique within organization) (required) * `--description `: (required) * `--secret-ids `: Secret IDs to attach to this profile. Do not set together with vaultItemIds. (repeatable) * `--inbox-email-prefix `: Optional custom prefix for the agent's inbox email address. If set, the inbox will be \{prefix}@agentmail.asteroid.ai. ### `asteroid profile delete [flags]` Delete a login profile. * `` ### `asteroid profile duplicate [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. * `` ### `asteroid profile get [flags]` Get a login profile by ID, including its Email Inbox and attached secrets (keys and ##ITEM\_KEY.FIELD## placeholders; values are omitted). * `` ### `asteroid profile inbox get [flags]` Read one email from a login profile's Email Inbox by `emailId`, including its text and HTML body. * `` * ``: The Resend email ID ### `asteroid profile inbox list [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. * `` * `--limit ` ### `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 ` * `--page ` * `--search-name `: Search profiles by name (partial match) * `--proxy-mode `: Filter by proxy mode (can specify multiple, there is an 'OR' condition applied to these) (repeatable) * `--operating-system `: 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 `: 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 `: Available fields for sorting agent profiles * `--sort-direction ` ### `asteroid profile update [flags]` Update a login profile. Attach secrets with `secretIdsToAdd` and detach them with `secretIdsToRemove`. `secretIds` replaces the full set. * `` * `--name ` * `--description ` * `--secret-ids `: Secret IDs attached to this profile. Replaces the full list. To change part of it, use secretIdsToAdd and secretIdsToRemove. (repeatable) * `--secret-ids-to-add `: Secret IDs to attach. Secrets already attached stay. Cannot be combined with secretIds. (repeatable) * `--secret-ids-to-remove `: Secret IDs to detach. IDs that are not attached are ignored. Applied before secretIdsToAdd. Cannot be combined with secretIds. (repeatable) * `--inbox-email-prefix `: 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 `: Name of the agent profile pool (must be unique within organization) (required) * `--selection-strategy `: 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 [flags]` Delete a profile group. The member profiles themselves are kept; schedules or executions that name the group will fail to select a profile. * `` ### `asteroid profile-group get [flags]` Get one profile group by ID with its selection settings. * `` ### `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 ` * `--page ` * `--search-name `: Search pools by name (partial match) * `--sort-field `: Available fields for sorting agent profile pools * `--sort-direction ` ### `asteroid profile-group member add [flags]` Add existing profiles to a profile group by `profileIds`. Profiles must belong to the group's organization. * `` * `--profile-ids `: (required, repeatable) ### `asteroid profile-group member list [flags]` List the profiles in a profile group, paginated. * `` * `--page-size ` * `--page ` ### `asteroid profile-group member remove [flags]` Remove profiles from a profile group by `profileIds`. The profiles are not deleted. * `` * `--profile-ids `: (required, repeatable) ### `asteroid profile-group update [flags]` Rename a profile group or change its selection strategy and concurrent-use setting. Membership is changed with the members tools. * `` * `--name ` * `--selection-strategy `: 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 [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. * `` * `--name `: (required) * `--profile-id `: Login profile each execution runs with. Mutually exclusive with profileGroupId. * `--profile-group-id `: Profile group to select a profile from for each execution. Mutually exclusive with profileId. * `--cron-expression `: Five-field cron expression. (required) * `--timezone `: 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 `: Workflow version number to run. Omit it to run the published version. * `--inputs ` * `--batch-source `: Set to make each tick create a batch from a spreadsheet instead of one execution * `--execution-options `: Per-execution runtime options applied to every run this schedule triggers. ### `asteroid schedule delete [flags]` Delete a schedule so it stops creating runs. Executions it already started are unaffected. To pause instead, call `schedule_update` with `enabled: false`. * `` * `` ### `asteroid schedule get [flags]` Get one schedule by `scheduleId`. * `` * `` ### `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 ` * `--page ` * `--[no-]include-disabled`: Include disabled schedules (default true) ### `asteroid schedule update [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. * `` * `` * `--name ` * `--profile-id `: Login profile each execution runs with. Mutually exclusive with profileGroupId. * `--profile-group-id `: Profile group to select a profile from for each execution. Mutually exclusive with profileId. * `--cron-expression `: Five-field cron expression. * `--timezone `: 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 `: Workflow version number to run. Omit it to keep the current one. * `--inputs ` * `--batch-source `: 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 `: 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 [flags]` Cancel a pending scheduled execution before it fires. A cancelled item can be revived with `scheduled_execution_reschedule`. * `` ### `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 `: 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 `: The workflow version to schedule. Set this or workflowId. * `--profile-id ` * `--inputs ` * `--metadata `: String key/value pairs to label and filter executions. * `--execute-at `: When to start the run, in ISO 8601. (required) * `--execution-options `: 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 `: 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 ` * `--status ` * `--batch-id ` * `--order `: Sort order for scheduled executions by execute\_at timestamp * `--page-size ` * `--page ` ### `asteroid scheduled-execution reschedule [flags]` Give a cancelled scheduled execution a new `executeAt` and return it to pending. Only cancelled items can be rescheduled. * `` * `--execute-at `: 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 `: (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 `: (required) * `--item-key `: Optional UPPER\_SNAKE key. Derived from name when omitted. * `--template-id `: Org template to snapshot. Mutually exclusive with kind and fields. * `--kind `: Required when templateId is omitted. * `--fields `: Inline field blueprint. Required when templateId is omitted. * `--values `: Field values as `key`/`value` pairs. (required) ### `asteroid secret delete [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. * `` ### `asteroid secret field add [flags]` Add a non-required field to a secret. Pass `field` (label, type, required) and `value`. Secret values are never returned. * `` * `--field `: Write shape for a field. The server derives key from label. (required) * `--value `: (required) ### `asteroid secret field remove [flags]` Remove a field the secret type does not require. Path is secret id plus field key (UPPER\_SNAKE). * `` * ``: The field's key, in UPPER\_SNAKE case. ### `asteroid secret get [flags]` Get one secret. Secret values are omitted. Readable field types may include `readableValue`. Use the `placeholder` on each field in agent instructions. * `` ### `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 ` * `--page ` * `--search-name `: Case-insensitive substring match on the secret name or item key * `--sort-field ` * `--sort-direction ` ### `asteroid secret rotate [flags]` Replace field values on a secret in one write. Supply `values` as key/value pairs. Secret values are never returned. * `` * `--values `: New field values as `key`/`value` pairs. (required) ### `asteroid secret update [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. * `` ### `asteroid secret versions [flags]` List a secret's stored versions. Values are never returned. * `` ### `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 `: Title shown to the recipient of the secret request. (required) * `--description `: Explanation shown to the recipient of the secret request. * `--name `: Name of the secret the request creates. (required) * `--item-key `: Optional UPPER\_SNAKE key. Derived from name when omitted. * `--template-id `: Org template to snapshot. Mutually exclusive with kind and fields. * `--kind `: Required when templateId is omitted. * `--fields `: Inline field blueprint. Required when templateId is omitted. * `--steps `: 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 [flags]` Revoke a pending secret request. 409 when the request is not pending. * `` ### `asteroid secret-template create [flags]` Create an organization secret template (kind, fields, optional steps). Use it later when creating secrets via `templateId`. * `--kind `: Kind of vault item. Templates and items need at least one field. Completeness is per-field required. (required) * `--name `: (required) * `--description ` * `--fields `: (required) * `--steps `: How the fields are laid out as steps when someone fills in a secret request. ### `asteroid secret-template delete [flags]` Delete an organization secret template. * `` ### `asteroid secret-template duplicate [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. * `` * `--name ` ### `asteroid secret-template get [flags]` Get one organization secret template by 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 ` * `--page ` * `--search-name `: Case-insensitive substring match on the template name * `--sort-field ` * `--sort-direction ` ### `asteroid secret-template update [flags]` Update an organization secret template's name, description, kind, fields, or steps. * `` * `--kind `: Kind of vault item. Templates and items need at least one field. Completeness is per-field required. * `--name ` * `--description ` * `--fields ` * `--steps `: 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 ` * `--protected-group-key `: Protected group to create the tag in, materializing its row if needed * `--name `: Tag name; must not contain '::' (required) * `--catalog-portal-id `: 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 [flags]` Delete a tag from the organization. It is removed from every workflow that carried it. * `` ### `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 ` * `--page-size ` * `--page ` ### `asteroid tag update [flags]` Rename a tag, or link or unlink the catalog portal it represents. * `` * `--name `: 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 `: 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 [flags]` Delete a user-defined tag group. Its tags and their assignments on workflows are removed with it. The protected groups cannot be deleted. * `` ### `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 ` * `--page ` ### `asteroid tag-group update [flags]` Rename a user-defined tag group or change its icon. The protected groups (Portal, Client, Task) cannot be changed. * `` * `--name `: New group name; must not contain '::' * `--icon `: 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 `: 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 `: 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 `: The first version of the workflow. Omit it to start from a blank workflow with a single start node. ### `asteroid workflow delete [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. * `` ### `asteroid workflow duplicate [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. * `` * `--name `: 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 [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`. * `` * `--profile-id `: The ID of the login profile to use for this execution. Mutually exclusive with profileGroupId. * `--profile-group-id `: The ID of the profile group to select a profile from. Mutually exclusive with profileId. * `--inputs `: Inputs to be merged into the placeholders defined in prompts * `--temp-files `: Array of temporary files to attach to the execution. Must have been pre-uploaded using the stage file endpoint * `--metadata `: Optional metadata key-value pairs (string keys and string values) for organizing and filtering executions * `--version `: 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 `: Per-execution runtime options that override or extend the workflow's default settings. * `--on-capacity-limit `: 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 [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. * `` * `--profile-id `: The ID of the login profile to use for this execution. Mutually exclusive with profileGroupId. * `--profile-group-id `: The ID of the profile group to select a profile from. Mutually exclusive with profileId. * `--inputs `: Inputs to be merged into the placeholders defined in prompts * `--temp-files `: Array of temporary files to attach to the execution. Must have been pre-uploaded using the stage file endpoint * `--metadata `: Optional metadata key-value pairs (string keys and string values) for organizing and filtering executions * `--version `: 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 `: Per-execution runtime options that override or extend the workflow's default settings. * `--on-capacity-limit `: 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 `: Seconds to wait for the execution to finish before returning 202. Defaults to 25. ### `asteroid workflow file list [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. * `` * `--contents `: Which contents come inline: none (a pure manifest), structural (the default), or all (structural plus file bytes within the response budget). * `--paths `: 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 `: Narrow which variants/\/ 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 `: Per-file ceiling, in bytes, for inlined file contents. Clamped to the server maximum. Files above the ceiling stay references. * `--max-total-bytes `: 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 [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. * `` * `--base-rev `: 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 `: Files to upsert. (required) * `--deletes `: (required, repeatable) ### `asteroid workflow get [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. * `` * `--version `: Optional published version number to return ### `asteroid workflow head publish [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. * `` ### `asteroid workflow head revert [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. * `` * `--version-id `: The ID of the version to copy over the editable head (required) ### `asteroid workflow head snapshot [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. * `` ### `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 ` * `--page ` * `--search-name `: Return results whose name contains this text, case-insensitive. * `--sort-field ` * `--sort-direction ` * `--tag-ids `: Restrict the results to workflows carrying these tags (repeatable) * `--tag-match `: How tagIds combine: any (default) or all * `--without-tag-group-id `: Restrict the results to workflows with no tag in this group. Backs the 'No \' bucket. ### `asteroid workflow rename [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. * `` * `--name `: New name for the workflow. Letters, digits, spaces, and punctuation excluding \_ \< > : " / \ | ? and \*. ### `asteroid workflow schedules [flags]` List the cron schedules on a workflow, each with its cron expression, time zone, enabled flag, inputs and next run time. * `` ### `asteroid workflow stats [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. * `` * `--time-range <7d|30d|90d|all>`: `7d`, `30d`, `90d` or `all`. Defaults to `30d`. * `--version `: Restrict the statistics to these version numbers (repeatable) * `--timezone `: IANA time zone for bucketing. Defaults to UTC. ### `asteroid workflow tag list [flags]` List the tags attached to one workflow. `workflow_tags_list` lists every tag in the organization instead. * `` ### `asteroid workflow tag set [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. * `` * `--add `: Existing tag ids to add; all must be in the workflow's organization (repeatable) * `--create `: Tags to add by name, created when missing * `--remove `: (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 `: Optional parent workflow ID to derive from * `--rules `: (required) * `--graph `: (required) * `--inputs `: Typed input definitions for this workflow. Names referenced in prompts but omitted here default to optional strings. * `--settings `: Configuration settings for workflow execution (required) * `--environment-template `: 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 [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. * `` * `--parent-id `: Optional parent workflow ID to derive from * `--rules `: (required) * `--graph `: (required) * `--inputs `: Typed input definitions for this workflow. Names referenced in prompts but omitted here default to optional strings. * `--settings `: Configuration settings for workflow execution (required) * `--environment-template `: 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 [flags]` Delete an unpublished workflow version that has no executions. Published versions and versions with runs are refused. * `` * `` ### `asteroid workflow version execute [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`. * `` * `` * `--inputs `: Inputs to be merged into the placeholders defined in prompts. Do not set together with inputVariables. * `--metadata `: Optional metadata key-value pairs for organizing and filtering executions * `--profile-id `: The ID of the login profile to use. Mutually exclusive with profileGroupId. * `--profile-group-id `: The ID of the profile group to select a profile from. Mutually exclusive with profileId. * `--temp-files `: Array of temporary files to attach to the execution. Must have been pre-uploaded using the stage file endpoint * `--execution-options `: Per-execution runtime options that override or extend the workflow's default settings. * `--parent-execution-id `: 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 [flags]` List a version's files, like `workflow_files_list` does for the editable head. Versions are immutable, so this is read-only. * `` * `` * `--contents `: Which contents come inline: none (a pure manifest), structural (the default), or all (structural plus file bytes within the response budget). * `--paths `: 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 `: Narrow which variants/\/ 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 `: Per-file ceiling, in bytes, for inlined file contents. Clamped to the server maximum. Files above the ceiling stay references. * `--max-total-bytes `: 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 [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. * `` * `` * `` ### `asteroid workflow version get [flags]` Get a full workflow version by `versionId`, including the complete node graph, rules, and settings. * `` * `` ### `asteroid workflow version inputs [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`. * `` * `` ### `asteroid workflow version list [flags]` List all versions of a workflow (lightweight refs with IDs, parents, and version numbers). * `` ### `asteroid workflow version output-schemas [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. * `` * `` ### `asteroid workflow version publish [flags]` Publish a workflow version, assigning it a permanent version number and making it the default for `workflow_execute_post`. * `` * `` ### `asteroid workflow version validate [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. * `` * `--parent-id `: Optional parent workflow ID to derive from * `--rules `: (required) * `--graph `: (required) * `--inputs `: Typed input definitions for this workflow. Names referenced in prompts but omitted here default to optional strings. * `--settings `: Configuration settings for workflow execution (required) * `--environment-template `: 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. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.