--- title: personas description: Manage reusable audience personas and generated candidates. canonical_url: https://orchestor.io/docs/en/cli/persona markdown_url: https://orchestor.io/docs/en/cli/persona.md contentType: reference --- # personas `orc personas` manages audience personas in a Workspace. Create, retrieve, update, and delete profiles containing names, descriptions, behavior, demographics, and employment information. You can also asynchronously generate candidates from a brand and save reviewed profiles. Configure authentication and specify the target Workspace. Creating a persona does not attach it to prompts or start measurement. Use its saved ID in `persona_ids` through [`orc prompts`](https://orchestor.io/docs/cli/prompt.md). Profiles are user-described hypotheses, not verified customer attributes. ## Usage ```bash title="terminal" orc personas list --workspace ``` *Inspect saved personas and their IDs.* ## Subcommands ### `suggestions refresh` Generate buyer persona hypotheses asynchronously from a brand in the current Workspace. Acceptance may already report dispatch failure, so inspect status using the returned generation ID. Generation does not save personas, attach them, or start measurement. ```bash title="terminal" orc personas 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 personas suggestions refresh --idempotency-key ``` ##### `--brand-id` (required) Brand in the selected workspace whose profile supplies generation context. Type: `string`. Optional. ```bash title="terminal" orc personas suggestions refresh --brand-id ``` ##### `--count` Requested number of persona candidates, from 1 to 5. Defaults to 3. Type: `number`. Optional. ```bash title="terminal" orc personas suggestions refresh --count ``` ##### `--language-code` Language for the generated candidates. Defaults to ja-JP. Type: `string`. Optional. ```bash title="terminal" orc personas suggestions refresh --language-code ``` ##### `--instructions` Optional guidance for generation, up to 2000 characters. Omit for no additional instructions.; max 2000 chars Type: `string`. Optional. ```bash title="terminal" orc personas suggestions refresh --instructions ``` ### `suggestions generations get` Retrieve candidate generation status and results by generation ID. Review and edit candidates, then save selected profiles with `personas create`. ```bash title="terminal" orc personas suggestions generations get [options] ``` ### `list` List non-deleted personas newest first by creation time. This does not filter by brand. Pass the returned cursor unchanged for the next page. ```bash title="terminal" orc personas list [options] ``` ### `create` Only `name` is required. Omitted `description` becomes null; omitted `persona` becomes an empty profile. Creation requires `workspace:settings` permission. ```bash title="terminal" orc personas 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 personas create --idempotency-key ``` ##### `--name` (required) Display name for this audience persona. Type: `string`. Optional. ```bash title="terminal" orc personas create --name ``` ##### `--description` Optional audience summary. Omit or send null to store no description.; (use "null" or "reset" to clear) Type: `string`. Optional. ```bash title="terminal" orc personas create --description ``` ##### `--persona` Optional audience attributes grouped into behavior, demographics and employment, plus visual identity. Omit unknown groups or fields. Nullable leaf values can be null. Text and string arrays describe the audience; they are not validated against demographic taxonomies. Use employment.roleSeniority; the removed employment.seniority field is rejected.; (JSON object, e.g. '{"custom_id":"x"}') Type: `string`. Optional. ```bash title="terminal" orc personas create --persona ``` #### Examples ```bash title="terminal" orc personas create --stdin --workspace < persona.json ``` *Save a structured profile* ### `get` Retrieve details using a persona ID from listing. Missing, deleted, or other-Workspace IDs return 404. ```bash title="terminal" orc personas get [options] ``` ### `update` Change only supplied fields. `description: null` clears the description. Supplying `persona` replaces the entire profile rather than merging nested fields. Use an empty JSON object to clear the profile. ```bash title="terminal" orc personas update [options] ``` #### Unique options ##### `--name` Replacement display name. Omit to keep the current name. Type: `string`. Optional. ```bash title="terminal" orc personas update --name ``` ##### `--description` Replacement summary. Send null to clear it; omit to retain it.; (use "null" or "reset" to clear) Type: `string`. Optional. ```bash title="terminal" orc personas update --description ``` ##### `--persona` Optional audience attributes grouped into behavior, demographics and employment, plus visual identity. Omit unknown groups or fields. Nullable leaf values can be null. Text and string arrays describe the audience; they are not validated against demographic taxonomies. Use employment.roleSeniority; the removed employment.seniority field is rejected.; (JSON object, e.g. '{"custom_id":"x"}') Type: `string`. Optional. ```bash title="terminal" orc personas update --persona ``` ### `delete` Soft-delete a persona. If it is attached to a non-deleted prompt, return 409. Remove it from each prompt’s `persona_ids` before retrying. ```bash title="terminal" orc personas delete [options] ``` ## Examples ### Persona input ```json title="persona.json" { "name": "Mid-market SaaS CTO", "description": "Evaluates search software.", "persona": { "behavior": { "motivations": "Reduce research time", "painPoints": null }, "employment": { "jobTitle": [ "CTO" ], "roleSeniority": [ "Executive" ] } } } ``` *Persona input* ## Profile structure The main `persona` groups are `behavior`, `demographics`, and `employment`. Field names use camelCase. Omit unknown groups or fields; nullable leaf values can be null. `behavior` contains `motivations` and `painPoints`. `demographics` contains `ageRange`, `gender`, `location`, `income`, and `education`. `employment` contains `companySize`, `industry`, `jobTitle`, `roleSeniority`, and `department`. Demographic and employment values are arrays of strings. Use `roleSeniority`, not the removed `employment.seniority`. Optional `avatar` contains `colorToken`, `identityKind`, `iconToken`, `emoji`, and `imageFileId`. Null restores the default avatar. Sending only part of a profile on update also replaces the rest, so send the complete profile containing fields you want to preserve. ## 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 personas`: - [`--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) - [`--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)