--- title: prompts description: Manage monitored questions, configuration, suggestions, and tags. canonical_url: https://orchestor.io/docs/en/cli/prompt markdown_url: https://orchestor.io/docs/en/cli/prompt.md contentType: reference --- # prompts `orc prompts` manages questions monitored in a Workspace. Create or update question text, topics, personas, measurement channels, regions, and languages, and enable or disable execution. It also handles suggestion generation and acceptance, and reading or replacing tags. New questions default to `draft` and do not run or consume active prompt quota. Authentication and Workspace access are required. Use prompt IDs returned by creation or listing. Discover channel IDs with [`orc channels list`](https://orchestor.io/docs/cli/model.md) and region codes with [`orc regions list`](https://orchestor.io/docs/cli/region.md). Activation needs remaining prompt quota. Creating a question is separate from working with results through [`orc runs`](https://orchestor.io/docs/cli/runs.md). ## Usage ```bash title="terminal" orc prompts list --workspace ``` *Inspect question IDs, lifecycle state, and persisted result aggregates.* ## Channels, locale, and execution settings `platforms` contains consumer AI observation channel IDs. The default is `chatgpt-ui`; recognized observation aliases are normalized. Direct provider API channels are rejected. Specify up to 20 existing persona IDs in the same Workspace. Supported `country_code` forms such as `JP`, `jp`, `JPN`, and `ja-JP` are normalized to alpha-2 and can fill omitted region and language defaults. Explicit values are preserved. These are measurement conditions, not organization data residency. `language_code` uses BCP 47. `schedule` is a stored cron expression of at most 100 characters. Omitting it on creation stores null. Execution also depends on question lifecycle and Workspace measurement configuration; saving cron does not guarantee execution. `branding` is `non_branded` or `branded`; `intent_type` is `informational`, `commercial`, or `transactional`. Omitting branding classifies against brand names, aliases, and domains; intent defaults to informational. These classify the question, not answer sentiment. Omitted classifications are preserved on update. ## Subcommands ### `list` Filter with `--topic-id` and `--status`. Omitting status includes all lifecycle states; soft-deleted prompts and prompts under deleted parents are excluded. Persisted answer aggregates are included, but measurement does not start. ```bash title="terminal" orc prompts list [options] ``` #### Unique options ##### `--topic-id` Existing accessible Topic ID. Omit to include prompts across topics and prompts without a topic. A missing or inaccessible Topic returns 404. Type: `string`. Optional. ```bash title="terminal" orc prompts list --topic-id ``` ##### `--status` Return only this lifecycle state. Omit to include draft, active, disabled and archived prompts; deleted prompts remain excluded.; enum: draft|active|disabled|archived Type: `string`. Optional. ```bash title="terminal" orc prompts list --status ``` ##### `--metric-platforms` Comma-separated platform or channel IDs restricting answer metrics and mentioned brands. Prompt membership is unchanged. Omit for all platforms.; max 2000 chars Type: `string`. Optional. ```bash title="terminal" orc prompts list --metric-platforms ``` ### `create` `text` is required and limited to 2,000 characters. Supply a supported `country_code`, or both `region_id` and `language_code`. Active questions without a topic are assigned the Workspace default topic and need an active owned brand. Duplicate text and country return 409. ```bash title="terminal" orc prompts create [options] ``` #### Unique options ##### `--idempotency-key` Retry identity for operations that support idempotency. Use a unique key for each new operation, and reuse it only when retrying the same HTTP method, path, query values and exact request body. JSON whitespace changes can count as a different body. Keys contain 1–255 characters after trimming and expire after 24 hours. A completed JSON response is replayed without repeating the operation. A different request using the same key returns 409 idempotency_error. An in-progress request returns 409 idempotency_in_progress with Retry-After: 2. Whether this header is required depends on the operation. Type: `string`. Optional. ```bash title="terminal" orc prompts create --idempotency-key ``` ##### `--topic-id` Existing Topic ID in this workspace. Omit or set null to leave a draft or disabled prompt unassigned. Persisted active creation resolves the workspace default topic; preview does not.; (use "null" or "reset" to clear) Type: `string`. Optional. ```bash title="terminal" orc prompts create --topic-id ``` ##### `--text` (required) The prompt text to send to LLM platforms.; max 2000 chars Type: `string`. Optional. ```bash title="terminal" orc prompts create --text ``` ##### `--persona-ids` Existing Persona IDs in this workspace. Omit or use an empty array for no persona associations. Missing or inaccessible IDs return 404.; csv Type: `string`. Optional. ```bash title="terminal" orc prompts create --persona-ids ``` ##### `--platforms` Consumer AI observation channel IDs. Defaults to chatgpt-ui. Recognized observation aliases are normalized; direct provider API channels are rejected.; csv of: chatgpt-ui|gemini-ui|perplexity-ui|copilot-ui|google-ai-overview|google-ai-mode Type: `string`. Optional. ```bash title="terminal" orc prompts create --platforms ``` ##### `--region-id` Execution region. Required unless the supplied country or another recognized locale field resolves a supported default. Explicit values are preserved. This does not control data residency. Type: `string`. Optional. ```bash title="terminal" orc prompts create --region-id ``` ##### `--language-code` Execution language. Required unless the supplied country or another recognized locale field resolves a supported default. Explicit values are preserved. Type: `string`. Optional. ```bash title="terminal" orc prompts create --language-code ``` ##### `--country-code` ISO 3166 observation country used when executing this prompt. Common forms such as `JP`, `jp`, `JPN`, and locale-style `ja-JP` are normalized to the canonical alpha-2 country code when supported. This does not control Organization residency.; (use "null" or "reset" to clear) Type: `string`. Optional. ```bash title="terminal" orc prompts create --country-code ``` ##### `--status` Lifecycle status. `draft` is editable and excluded from measurement and active prompt quota until explicitly activated. Defaults to `draft`; `disabled` preserves history and stops future execution.; enum: draft|active|disabled Type: `string`. Optional. ```bash title="terminal" orc prompts create --status ``` ##### `--schedule` Stored cron expression for periodic collection. Omit to store null. Actual execution also depends on prompt lifecycle and workspace measurement configuration.; max 100 chars Type: `string`. Optional. ```bash title="terminal" orc prompts create --schedule ``` ##### `--branding` Whether the prompt text names a brand (branded) or is generic (non_branded). On creation, omission classifies against registered workspace brand names, aliases and domains. An explicit value takes precedence; measurement does not overwrite manual classifications.; enum: non_branded|branded Type: `string`. Optional. ```bash title="terminal" orc prompts create --branding ``` ##### `--intent-type` Search-intent classification of the prompt question. Defaults to informational on creation; omission in a partial update preserves the stored value.; enum: informational|commercial|transactional Type: `string`. Optional. ```bash title="terminal" orc prompts create --intent-type ``` ##### `--preview` When `true`, validate and resolve the Prompt without persistence. Requires `Idempotency-Key`; read-scope API keys may use only this mode. Type: `string`. Optional. ```bash title="terminal" orc prompts create --preview ``` #### Examples ```bash title="terminal" orc prompts create --text "What is the best CRM for startups?" --country-code JP --platforms chatgpt-ui --workspace ``` *Create a draft question* ### `get` Retrieve a question and its persona associations. Use `config_revision` from this response for updates. Single-item reads do not calculate answer aggregates; inspect them through `list`. ```bash title="terminal" orc prompts get [options] ``` ### `update` Change only supplied fields, except that supplied locale values may populate omitted locale fields. Disable an active question before changing its text. Supply the latest `config_revision`; on a 409 conflict, retrieve again and review the change. `persona_ids` and `platforms` replace complete selections. ```bash title="terminal" orc prompts update [options] ``` #### Unique options ##### `--idempotency-key` Retry identity for operations that support idempotency. Use a unique key for each new operation, and reuse it only when retrying the same HTTP method, path, query values and exact request body. JSON whitespace changes can count as a different body. Keys contain 1–255 characters after trimming and expire after 24 hours. A completed JSON response is replayed without repeating the operation. A different request using the same key returns 409 idempotency_error. An in-progress request returns 409 idempotency_in_progress with Retry-After: 2. Whether this header is required depends on the operation. Type: `string`. Optional. ```bash title="terminal" orc prompts update --idempotency-key ``` ##### `--text` Replacement question text. Omit to retain it. An active prompt must be disabled before its text changes.; max 2000 chars Type: `string`. Optional. ```bash title="terminal" orc prompts update --text ``` ##### `--topic-id` Replacement accessible Topic ID. Omit to retain the association. Null clears a non-active association; an active prompt resolves a default topic and requires an active owned brand.; (use "null" or "reset" to clear) Type: `string`. Optional. ```bash title="terminal" orc prompts update --topic-id ``` ##### `--persona-ids` Complete replacement of persona associations. Omit to retain them; use [] to clear them. Every ID must belong to this workspace.; csv Type: `string`. Optional. ```bash title="terminal" orc prompts update --persona-ids ``` ##### `--platforms` Complete replacement of observation channels. Omit to retain the selection. Recognized observation aliases are normalized; direct provider API channels are rejected.; csv of: chatgpt-ui|gemini-ui|perplexity-ui|copilot-ui|google-ai-overview|google-ai-mode Type: `string`. Optional. ```bash title="terminal" orc prompts update --platforms ``` ##### `--region-id` Replacement execution region. Omit to retain it unless another supplied locale field derives a supported default. Type: `string`. Optional. ```bash title="terminal" orc prompts update --region-id ``` ##### `--language-code` Replacement execution language. Omit to retain it unless another supplied locale field derives a supported default. Type: `string`. Optional. ```bash title="terminal" orc prompts update --language-code ``` ##### `--country-code` Replacement observation country. Supported country and locale forms are normalized and can populate omitted region_id and language_code. Omit all locale fields to retain the current locale.; (use "null" or "reset" to clear) Type: `string`. Optional. ```bash title="terminal" orc prompts update --country-code ``` ##### `--status` Lifecycle transition. `disabled` preserves history and stops future execution; `archived` removes the prompt from active work while preserving its history.; enum: draft|active|disabled|archived Type: `string`. Optional. ```bash title="terminal" orc prompts update --status ``` ##### `--schedule` Replacement stored cron expression. Omit to retain it. This request schema does not accept null.; max 100 chars Type: `string`. Optional. ```bash title="terminal" orc prompts update --schedule ``` ##### `--branding` Whether the prompt text names a brand (branded) or is generic (non_branded). On creation, omission classifies against registered workspace brand names, aliases and domains. An explicit value takes precedence; measurement does not overwrite manual classifications.; enum: non_branded|branded Type: `string`. Optional. ```bash title="terminal" orc prompts update --branding ``` ##### `--intent-type` Search-intent classification of the prompt question. Defaults to informational on creation; omission in a partial update preserves the stored value.; enum: informational|commercial|transactional Type: `string`. Optional. ```bash title="terminal" orc prompts update --intent-type ``` ##### `--config-revision` Latest revision from a prompt response. A mismatch returns 409 when applying a change. Omission remains accepted during the migration window; do not use a preview revision as a saved revision. Type: `number`. Optional. ```bash title="terminal" orc prompts update --config-revision ``` ##### `--preview` When `true`, validate and resolve the update without persistence. Requires `Idempotency-Key`; read-scope API keys may use only this mode. Type: `string`. Optional. ```bash title="terminal" orc prompts update --preview ``` #### Examples ```bash title="terminal" orc prompts update --text "Which CRM fits small teams?" --config-revision --workspace ``` *Change a disabled question’s text* ### `delete` Soft-delete a question and hide it from ordinary lists and reads. The question and observation history are permanently removed by daily purge after the 30-day retention window. Use `disable` to stop only future observation. Repeating deletion returns 404. ```bash title="terminal" orc prompts delete [options] ``` ### `disable` Move a draft, active, or archived question to disabled, preserving configuration and history while stopping future observation. An already disabled question returns 409. The response includes the updated `config_revision`. ```bash title="terminal" orc prompts disable [options] ``` #### Unique options ##### `--idempotency-key` Retry identity for operations that support idempotency. Use a unique key for each new operation, and reuse it only when retrying the same HTTP method, path, query values and exact request body. JSON whitespace changes can count as a different body. Keys contain 1–255 characters after trimming and expire after 24 hours. A completed JSON response is replayed without repeating the operation. A different request using the same key returns 409 idempotency_error. An in-progress request returns 409 idempotency_in_progress with Retry-After: 2. Whether this header is required depends on the operation. Type: `string`. Optional. ```bash title="terminal" orc prompts disable --idempotency-key ``` ### `enable` Activate a draft, disabled, or archived question. Insufficient active quota returns 402; already active returns 409. Default-topic assignment for an unassigned question needs an active owned brand. Inactive periods are not backfilled, and this does not return completed measurement results. ```bash title="terminal" orc prompts enable [options] ``` #### Unique options ##### `--idempotency-key` Retry identity for operations that support idempotency. Use a unique key for each new operation, and reuse it only when retrying the same HTTP method, path, query values and exact request body. JSON whitespace changes can count as a different body. Keys contain 1–255 characters after trimming and expire after 24 hours. A completed JSON response is replayed without repeating the operation. A different request using the same key returns 409 idempotency_error. An in-progress request returns 409 idempotency_in_progress with Retry-After: 2. Whether this header is required depends on the operation. Type: `string`. Optional. ```bash title="terminal" orc prompts enable --idempotency-key ``` ### `suggestions list` Read stored suggestions filtered by `status` and `topic_id`. Omitted status includes pending, accepted, and rejected suggestions. This read does not generate suggestions. ```bash title="terminal" orc prompts suggestions list [options] ``` #### Unique options ##### `--status` Review state to include. Omit for all states.; enum: pending|accepted|rejected Type: `string`. Optional. ```bash title="terminal" orc prompts suggestions list --status ``` ##### `--topic-id` Limit results to this parent topic. Omit to include all topics in the workspace. Type: `string`. Optional. ```bash title="terminal" orc prompts suggestions list --topic-id ``` ### `suggestions refresh` Start asynchronous generation for existing Workspace topic IDs. `--topic-ids` is required. Omit or empty `persona_ids` to generate without persona context. `instructions` allows up to 2,000 characters and applies to all selected topics. Acceptance can already report dispatch failure. Generation does not activate questions. ```bash title="terminal" orc prompts suggestions refresh [options] ``` #### Unique options ##### `--idempotency-key` Retry identity for operations that support idempotency. Use a unique key for each new operation, and reuse it only when retrying the same HTTP method, path, query values and exact request body. JSON whitespace changes can count as a different body. Keys contain 1–255 characters after trimming and expire after 24 hours. A completed JSON response is replayed without repeating the operation. A different request using the same key returns 409 idempotency_error. An in-progress request returns 409 idempotency_in_progress with Retry-After: 2. Whether this header is required depends on the operation. Type: `string`. Optional. ```bash title="terminal" orc prompts suggestions refresh --idempotency-key ``` ##### `--topic-ids` (required) Existing topic IDs in this workspace. Select 1–20 entries; repeated IDs are deduplicated before generation. Missing or deleted topics are rejected.; csv Type: `string`. Optional. ```bash title="terminal" orc prompts suggestions refresh --topic-ids ``` ##### `--persona-ids` Existing workspace Persona IDs to distribute across generated suggestions. Omit or send an empty array to generate without Persona context.; csv Type: `string`. Optional. ```bash title="terminal" orc prompts suggestions refresh --persona-ids ``` ##### `--prompts-per-topic` Requested new candidates per distinct topic, from 1 to 20. Defaults to 5. Deduplication or generation results can produce fewer stored candidates. Type: `number`. Optional. ```bash title="terminal" orc prompts suggestions refresh --prompts-per-topic ``` ##### `--language-code` Language context for generated prompt text. Defaults to ja-JP. Type: `string`. Optional. ```bash title="terminal" orc prompts suggestions refresh --language-code ``` ##### `--country-code` Country context for generation. Defaults to JP. Type: `string`. Optional. ```bash title="terminal" orc prompts suggestions refresh --country-code ``` ##### `--instructions` Optional generation guidance applied to every selected topic.; max 2000 chars Type: `string`. Optional. ```bash title="terminal" orc prompts suggestions refresh --instructions ``` #### Examples ```bash title="terminal" orc prompts suggestions refresh --topic-ids --wait --workspace ``` *Generate suggestions for a topic and wait* ### `suggestions generations get` Retrieve generation state and results by returned generation ID. Use this and the suggestion list to inspect generation started without `--wait`. ```bash title="terminal" orc prompts suggestions generations get [options] ``` ### `suggestions accept` Promote a pending suggestion to a new disabled question and mark it accepted in the same transaction. Measurement does not start automatically. Supply `--edit-text` and `--topic-id` as needed; a suggestion without a topic requires one. Resolved suggestions return 409. ```bash title="terminal" orc prompts suggestions accept [options] ``` #### Unique options ##### `--idempotency-key` Retry identity for operations that support idempotency. Use a unique key for each new operation, and reuse it only when retrying the same HTTP method, path, query values and exact request body. JSON whitespace changes can count as a different body. Keys contain 1–255 characters after trimming and expire after 24 hours. A completed JSON response is replayed without repeating the operation. A different request using the same key returns 409 idempotency_error. An in-progress request returns 409 idempotency_in_progress with Retry-After: 2. Whether this header is required depends on the operation. Type: `string`. Optional. ```bash title="terminal" orc prompts suggestions accept --idempotency-key ``` ##### `--topic-id` Destination topic in the same workspace. Omit to use the suggestion topic. Required when the suggestion has no topic. Type: `string`. Optional. ```bash title="terminal" orc prompts suggestions accept --topic-id ``` ##### `--edit-text` Replacement prompt text, up to 2000 characters. Omit to preserve the suggestion text. Providing an edit also causes branding to be resolved for the edited text.; max 2000 chars Type: `string`. Optional. ```bash title="terminal" orc prompts suggestions accept --edit-text ``` ### `suggestions reject` Mark a pending suggestion rejected and record resolution time. No question is created; the suggestion remains in rejected lists. Resolved suggestions return 409 and missing IDs 404. ```bash title="terminal" orc prompts suggestions reject [options] ``` #### Unique options ##### `--idempotency-key` Retry identity for operations that support idempotency. Use a unique key for each new operation, and reuse it only when retrying the same HTTP method, path, query values and exact request body. JSON whitespace changes can count as a different body. Keys contain 1–255 characters after trimming and expire after 24 hours. A completed JSON response is replayed without repeating the operation. A different request using the same key returns 409 idempotency_error. An in-progress request returns 409 idempotency_in_progress with Retry-After: 2. Whether this header is required depends on the operation. Type: `string`. Optional. ```bash title="terminal" orc prompts suggestions reject --idempotency-key ``` ### `tags get` Retrieve active tags attached to a question, oldest first by creation time. This is not paginated. The current API resolves prompts through non-deleted topics and brands, so an unassigned question returns 404. ```bash title="terminal" orc prompts tags get [options] ``` ### `tags update` Replace all associations with the complete `tag_ids` list. Supply the latest `config_revision`. Even when adding one tag, include every ID you want to preserve. ```bash title="terminal" orc prompts tags update [options] ``` #### Unique options ##### `--idempotency-key` Retry identity for operations that support idempotency. Use a unique key for each new operation, and reuse it only when retrying the same HTTP method, path, query values and exact request body. JSON whitespace changes can count as a different body. Keys contain 1–255 characters after trimming and expire after 24 hours. A completed JSON response is replayed without repeating the operation. A different request using the same key returns 409 idempotency_error. An in-progress request returns 409 idempotency_in_progress with Retry-After: 2. Whether this header is required depends on the operation. Type: `string`. Optional. ```bash title="terminal" orc prompts tags update --idempotency-key ``` ##### `--tag-ids` (required) Complete replacement tag set. Supply distinct active IDs from this workspace; [] removes all tags. Unknown or repeated IDs are rejected.; csv Type: `string`. Optional. ```bash title="terminal" orc prompts tags update --tag-ids ``` ##### `--config-revision` Current prompt revision for optimistic concurrency. A mismatch returns 409 without changing tags. Omission currently skips the revision check. Type: `number`. Optional. ```bash title="terminal" orc prompts tags update --config-revision ``` ## Examples ### Validate configuration on the server before saving `preview` returns a non-persisted projection. Unlike `--dry-run`, it sends to the API. It does not reserve quota, reject stored duplicates, or create a default topic. ```bash title="terminal" orc prompts create --text "What is the best CRM for startups?" --country-code JP --preview true --idempotency-key --workspace ``` *Validate configuration on the server before saving* ## Preview and concurrent edits Creation and update with `preview true` require `Idempotency-Key` and support read-scope API keys. Persisted creation requires write scope; updates and other configuration changes require `workspace:settings`. Do not use a preview revision as a saved revision. Omitting `config_revision` is accepted only during the migration window. Edit with the latest saved value; on conflict, retrieve again and review rather than overwriting. Prefer `enable` and `disable` for lifecycle changes. They do not restore soft-deleted questions. ## Permissions Access to the target Workspace is required. Changes require the corresponding write permissions. ## Global Options The following [global options](https://orchestor.io/docs/cli/global-flags.md) can be used with `orc prompts`: - [`--help`](https://orchestor.io/docs/cli/global-flags.md#help) - [`--workspace`](https://orchestor.io/docs/cli/global-flags.md#workspace) - [`--json`](https://orchestor.io/docs/cli/global-flags.md#json-output) - [`--pretty`](https://orchestor.io/docs/cli/global-flags.md#json-output) - [`--format`](https://orchestor.io/docs/cli/global-flags.md#output-format) - [`--field`](https://orchestor.io/docs/cli/global-flags.md#field-selection) - [`--fields`](https://orchestor.io/docs/cli/global-flags.md#field-selection) - [`--raw`](https://orchestor.io/docs/cli/global-flags.md#raw-output) - [`--output`](https://orchestor.io/docs/cli/global-flags.md#file-output) - [`--no-pager`](https://orchestor.io/docs/cli/global-flags.md#pager) - [`--dry-run`](https://orchestor.io/docs/cli/global-flags.md#dry-run) - [`--yes`](https://orchestor.io/docs/cli/global-flags.md#confirmation) - [`--limit`](https://orchestor.io/docs/cli/global-flags.md) - [`--cursor`](https://orchestor.io/docs/cli/global-flags.md) - [`--stdin`](https://orchestor.io/docs/cli/global-flags.md#standard-input) - [`--from-stdin`](https://orchestor.io/docs/cli/global-flags.md#standard-input) - [`--page-all`](https://orchestor.io/docs/cli/global-flags.md#all-pages) - [`--timing`](https://orchestor.io/docs/cli/global-flags.md#request-timing) - [`--wait`](https://orchestor.io/docs/cli/global-flags.md) - [`--timeout`](https://orchestor.io/docs/cli/global-flags.md) - [`--poll-interval`](https://orchestor.io/docs/cli/global-flags.md) - [`--readonly`](https://orchestor.io/docs/cli/global-flags.md#read-only-mode) - [`--wrap-untrusted`](https://orchestor.io/docs/cli/global-flags.md#untrusted-content-wrapping) For details and examples, see [global options](https://orchestor.io/docs/cli/global-flags.md). --- [Documentation index](https://orchestor.io/docs/llms.txt)