--- title: brands description: Manage brands, profiles, and suggestions. canonical_url: https://orchestor.io/docs/en/cli/brand markdown_url: https://orchestor.io/docs/en/cli/brand.md contentType: reference --- # brands `orc brands` manages owned and competing brands and their profiles in a Workspace. Retrieve lists and details, and create or update brand names, domains, aliases, offerings, audiences, and visual identities. Review generated brand suggestions before accepting or rejecting them. Configure CLI authentication first and select the target with `--workspace`. Retrieve owned brands with `--relation owned`. Use returned brand IDs with `get` and `update`; they are different from Workspace IDs. A brand’s domain registry is managed separately from the ownership-verification and ingestion resources in [`orc domains`](https://orchestor.io/docs/cli/domain.md). ## Usage ```bash title="terminal" orc brands list --relation owned --workspace ``` *Inspect owned brand IDs and profiles.* ## Profile fields | UI field | Input field | | --- | --- | | Description and industry | `notes`, `industry` | | Brand identity | `tags` | | Products and services | `offerings`, `products_and_services` | | Audience composition | `audience` | | Brand and display names | `name`, `display_name` | | Domains and aliases | `domain`, `domains`, `aliases` | | Colors and icons | `color_token`, `color_hex`, `identity_kind`, `icon_token`, `emoji`, `image_file_id` | `products_and_services` is a structured list with a required name per entry and takes precedence over `offerings` in the same request. Name-only edits through `offerings` retain existing details for matching names. Both lists support up to 100 entries. `audience` contains up to 20 entries with `id`, `label`, `description`, `percentage`, and `enabled`. Preserve existing audience IDs while editing. Each percentage is between 0 and 100. For a meaningful composition, arrange enabled entries to total 100%; the API does not validate the sum. `domains` rejects duplicates after normalization and uses the first value as `domain`. Pass values containing commas as JSON arrays through standard input rather than CSV. `color_token` takes precedence over `color_hex`. `profile_suggestion_decisions` maps suggestion keys to `accepted` or `rejected`. See [Set up brand information](https://orchestor.io/docs/cli/workflows/brand-setup.md) for an editing workflow. ## Subcommands ### `list` List brands. Filter `--relation` by `owned`, `direct_competitor`, `indirect_competitor`, or `ignored`. Omitting it includes owned brands and direct competitors. Keep filters unchanged when following a returned cursor. ```bash title="terminal" orc brands list [options] ``` #### Unique options ##### `--relation` Filter by relation. When omitted, owned and direct_competitor are returned by default.; enum: owned|direct_competitor|indirect_competitor|ignored Type: `string`. Optional. ```bash title="terminal" orc brands list --relation ``` ### `create` Create a brand with `name` and `domain`. `relation` defaults to `direct_competitor` and `status` to `active`. When `domains` is supplied, its first entry becomes the primary domain. This does not create a verification or ingestion Domain resource. ```bash title="terminal" orc brands 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 brands create --idempotency-key ``` ##### `--name` (required) Human-readable brand name.; max 255 chars Type: `string`. Optional. ```bash title="terminal" orc brands create --name ``` ##### `--domain` (required) Primary normalized domain in the brand registry. This field does not create a verification or ingestion Domain resource. Used when domains is omitted; otherwise the first domains entry takes precedence.; max 255 chars Type: `string`. Optional. ```bash title="terminal" orc brands create --domain ``` ##### `--relation` Single-axis brand relation. Intent-specific labels can be reserved in tags using intent:* when needed.; enum: owned|direct_competitor|indirect_competitor|ignored Type: `string`. Optional. ```bash title="terminal" orc brands create --relation ``` ##### `--tags` Labels attached to the brand. Strings are trimmed and empty strings are removed. Defaults to an empty array.; csv Type: `string`. Optional. ```bash title="terminal" orc brands create --tags ``` ##### `--logo-url` Logo URL or file reference; null when none is stored.; (use "null" or "reset" to clear) Type: `string`. Optional. ```bash title="terminal" orc brands create --logo-url ``` ##### `--display-name` Display name distinct from the stored brand name; null when unset.; (use "null" or "reset" to clear) Type: `string`. Optional. ```bash title="terminal" orc brands create --display-name ``` ##### `--industry` Industry label stored on the brand; null when unset.; (use "null" or "reset" to clear) Type: `string`. Optional. ```bash title="terminal" orc brands create --industry ``` ##### `--status` Lifecycle status. Defaults to `active`; `disabled` preserves history and stops future execution.; enum: active|disabled Type: `string`. Optional. ```bash title="terminal" orc brands create --status ``` ##### `--domains` Full brand domain registry. Values are trimmed, lowercased and stripped of an HTTP(S) scheme, leading [www](http://www/). and trailing slash. The first value becomes domain. Duplicate normalized values are rejected. When omitted, the registry contains domain only.; csv Type: `string`. Optional. ```bash title="terminal" orc brands create --domains ``` ##### `--aliases` Alternate brand names used for matching. Strings are trimmed and empty strings are removed. Defaults to an empty array.; csv Type: `string`. Optional. ```bash title="terminal" orc brands create --aliases ``` ##### `--color-hex` Six-digit hexadecimal display color. color_token takes precedence when both are supplied.; (use "null" or "reset" to clear) Type: `string`. Optional. ```bash title="terminal" orc brands create --color-hex ``` ##### `--color-token` Named display color. Writing this field also sets its corresponding color_hex. Defaults to default when neither color field is supplied.; enum: default|gray|brown|orange|yellow|green|blue|purple|pink|red Type: `string`. Optional. ```bash title="terminal" orc brands create --color-token ``` ##### `--identity-kind` Presentation style for the brand identity. Defaults to initial unless an image file selects image mode.; enum: color|initial|icon|emoji|image Type: `string`. Optional. ```bash title="terminal" orc brands create --identity-kind ``` ##### `--icon-token` Icon reference used for an icon identity; null when unset.; (use "null" or "reset" to clear) Type: `string`. Optional. ```bash title="terminal" orc brands create --icon-token ``` ##### `--emoji` Emoji used for an emoji identity; null when unset.; (use "null" or "reset" to clear) Type: `string`. Optional. ```bash title="terminal" orc brands create --emoji ``` ##### `--image-file-id` File reference used for an image identity. Writing this field also sets logo_url; null clears both and switches identity_kind to initial.; (use "null" or "reset" to clear) Type: `string`. Optional. ```bash title="terminal" orc brands create --image-file-id ``` ##### `--notes` Free-form brand profile notes; null when unset.; (use "null" or "reset" to clear) Type: `string`. Optional. ```bash title="terminal" orc brands create --notes ``` ##### `--regex-pattern` Stored regular expression for advanced brand matching; null when unset.; (use "null" or "reset" to clear) Type: `string`. Optional. ```bash title="terminal" orc brands create --regex-pattern ``` ##### `--products-and-services` Full replacement product and service list, with a required name per entry. Also replaces offerings with those names and takes precedence over offerings in the same request. An empty array clears the list. Defaults to an empty array when neither product list nor offerings is supplied.; JSON array of objects (use --stdin for large resources) Type: `string`. Optional. ```bash title="terminal" orc brands create --products-and-services ``` ##### `--offerings` Product and service names. Name-only edits retain stored details for matching names; products_and_services takes precedence when supplied. Defaults to an empty array.; csv Type: `string`. Optional. ```bash title="terminal" orc brands create --offerings ``` ##### `--audience` Audience segment list, up to 20 entries. Each percentage must be 0 to 100; this endpoint does not validate their sum. Defaults to an empty array when omitted.; JSON array of objects (use --stdin for large resources) Type: `string`. Optional. ```bash title="terminal" orc brands create --audience ``` ##### `--profile-suggestion-decisions` Map from generated profile suggestion keys to accepted or rejected decisions. Defaults to an empty object.; (JSON object, e.g. '{"custom_id":"x"}') Type: `string`. Optional. ```bash title="terminal" orc brands create --profile-suggestion-decisions ``` #### Examples ```bash title="terminal" orc brands create --name "Acme" --domain acme.example --relation owned --workspace ``` *Create an owned brand* ### `suggestions list` List stored brand suggestions. Filter by `pending`, `accepted`, or `rejected` with `--status`. Reading the list does not generate suggestions. ```bash title="terminal" orc brands suggestions list [options] ``` #### Unique options ##### `--status` Filter by suggestion status. Omit to include all statuses.; enum: pending|accepted|rejected Type: `string`. Optional. ```bash title="terminal" orc brands suggestions list --status ``` ### `suggestions refresh` Start asynchronous brand suggestion generation. `--wait` waits for completion; adjust waiting with `--timeout` and `--poll-interval`. Generation and acceptance are separate operations. ```bash title="terminal" orc brands 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 brands suggestions refresh --idempotency-key ``` ### `suggestions generations get` Retrieve asynchronous generation status using the ID returned when generation started. This is not a brand ID or suggestion ID. ```bash title="terminal" orc brands suggestions generations get [options] ``` ### `suggestions accept` Accept a pending suggestion by ID. Adjust the name with `--edit-name` and set the brand relationship with `--relation`. ```bash title="terminal" orc brands 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 brands suggestions accept --idempotency-key ``` ##### `--edit-name` Name for the created resource. When omitted, uses the suggestion name.; max 255 chars Type: `string`. Optional. ```bash title="terminal" orc brands suggestions accept --edit-name ``` ##### `--relation` Single-axis brand relation. Intent-specific labels can be reserved in tags using intent:* when needed.; enum: owned|direct_competitor|indirect_competitor|ignored Type: `string`. Optional. ```bash title="terminal" orc brands suggestions accept --relation ``` ### `suggestions reject` Reject a suggestion by ID. This does not create a brand. ```bash title="terminal" orc brands 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 brands suggestions reject --idempotency-key ``` ### `get` Retrieve details, including the profile, using a brand ID from the list. The brand must be in the current Workspace. ```bash title="terminal" orc brands get [options] ``` ### `update` Change only supplied fields. Arrays and suggestion-decision maps replace their entire stored values. Pass long descriptions or structured `products_and_services` and `audience` through JSON with `--stdin`. Nullable fields can be cleared with `null`. `disabled` preserves history and stops future execution; reactivation does not backfill the inactive interval. ```bash title="terminal" orc brands update [options] ``` #### Unique options ##### `--name` Human-readable brand name. Omit to retain the current value.; max 255 chars Type: `string`. Optional. ```bash title="terminal" orc brands update --name ``` ##### `--domain` Primary normalized domain in the brand registry. This field does not create a verification or ingestion Domain resource. Omit to retain the current value. When domains is omitted, supplying domain replaces the registry with this single value.; max 255 chars Type: `string`. Optional. ```bash title="terminal" orc brands update --domain ``` ##### `--relation` Single-axis brand relation. Intent-specific labels can be reserved in tags using intent:* when needed.; enum: owned|direct_competitor|indirect_competitor|ignored Type: `string`. Optional. ```bash title="terminal" orc brands update --relation ``` ##### `--tags` Labels attached to the brand. Strings are trimmed and empty strings are removed. Omit to retain the current value. Send [] to clear.; csv Type: `string`. Optional. ```bash title="terminal" orc brands update --tags ``` ##### `--logo-url` Logo URL or file reference; null when none is stored. Omit to retain the current value.; (use "null" or "reset" to clear) Type: `string`. Optional. ```bash title="terminal" orc brands update --logo-url ``` ##### `--display-name` Display name distinct from the stored brand name; null when unset. Omit to retain the current value.; (use "null" or "reset" to clear) Type: `string`. Optional. ```bash title="terminal" orc brands update --display-name ``` ##### `--industry` Industry label stored on the brand; null when unset. Omit to retain the current value.; (use "null" or "reset" to clear) Type: `string`. Optional. ```bash title="terminal" orc brands update --industry ``` ##### `--status` Lifecycle transition. `disabled` preserves history and stops future execution; returning to `active` does not backfill the disabled interval.; enum: active|disabled Type: `string`. Optional. ```bash title="terminal" orc brands update --status ``` ##### `--domains` Full brand domain registry. Values are trimmed, lowercased and stripped of an HTTP(S) scheme, leading [www](http://www/). and trailing slash. The first value becomes domain. Duplicate normalized values are rejected. Omit to retain the current value.; csv Type: `string`. Optional. ```bash title="terminal" orc brands update --domains ``` ##### `--aliases` Alternate brand names used for matching. Strings are trimmed and empty strings are removed. Omit to retain the current value. Send [] to clear.; csv Type: `string`. Optional. ```bash title="terminal" orc brands update --aliases ``` ##### `--color-hex` Six-digit hexadecimal display color. color_token takes precedence when both are supplied. Omit to retain the current value.; (use "null" or "reset" to clear) Type: `string`. Optional. ```bash title="terminal" orc brands update --color-hex ``` ##### `--notes` Free-form brand profile notes; null when unset. Omit to retain the current value.; (use "null" or "reset" to clear) Type: `string`. Optional. ```bash title="terminal" orc brands update --notes ``` ##### `--regex-pattern` Stored regular expression for advanced brand matching; null when unset. Omit to retain the current value.; (use "null" or "reset" to clear) Type: `string`. Optional. ```bash title="terminal" orc brands update --regex-pattern ``` ##### `--color-token` Named display color. Writing this field also sets its corresponding color_hex. Omit to retain the current value.; enum: default|gray|brown|orange|yellow|green|blue|purple|pink|red Type: `string`. Optional. ```bash title="terminal" orc brands update --color-token ``` ##### `--identity-kind` Presentation style for the brand identity. Omit to retain the current value.; enum: color|initial|icon|emoji|image Type: `string`. Optional. ```bash title="terminal" orc brands update --identity-kind ``` ##### `--icon-token` Icon reference used for an icon identity; null when unset. Omit to retain the current value.; (use "null" or "reset" to clear) Type: `string`. Optional. ```bash title="terminal" orc brands update --icon-token ``` ##### `--emoji` Emoji used for an emoji identity; null when unset. Omit to retain the current value.; (use "null" or "reset" to clear) Type: `string`. Optional. ```bash title="terminal" orc brands update --emoji ``` ##### `--image-file-id` File reference used for an image identity. Writing this field also sets logo_url; null clears both and switches identity_kind to initial. Omit to retain the current value.; (use "null" or "reset" to clear) Type: `string`. Optional. ```bash title="terminal" orc brands update --image-file-id ``` ##### `--products-and-services` Full replacement product and service list, with a required name per entry. Also replaces offerings with those names and takes precedence over offerings in the same request. An empty array clears the list. Omit to retain stored details unless offerings is supplied.; JSON array of objects (use --stdin for large resources) Type: `string`. Optional. ```bash title="terminal" orc brands update --products-and-services ``` ##### `--offerings` Product and service names. Name-only edits retain stored details for matching names; products_and_services takes precedence when supplied. Omit to retain the current value. Send [] to clear.; csv Type: `string`. Optional. ```bash title="terminal" orc brands update --offerings ``` ##### `--audience` Audience segment list, up to 20 entries. Each percentage must be 0 to 100; this endpoint does not validate their sum. Supplying the array replaces all stored segments; an empty array clears them. Omit to retain the current list.; JSON array of objects (use --stdin for large resources) Type: `string`. Optional. ```bash title="terminal" orc brands update --audience ``` ##### `--profile-suggestion-decisions` Map from generated profile suggestion keys to accepted or rejected decisions. Omit to retain the current value.; (JSON object, e.g. '{"custom_id":"x"}') Type: `string`. Optional. ```bash title="terminal" orc brands update --profile-suggestion-decisions ``` #### Examples Omitted fields are preserved. Sending one array entry replaces that array with a single entry. ```bash title="terminal" orc brands update --stdin --workspace < brand-profile.patch.json ``` *Update a profile from JSON* ### `delete` Soft-delete the specified brand. Check the target ID and Workspace before running the command. ```bash title="terminal" orc brands delete [options] ``` ## Examples ### Profile update input ```json title="brand-profile.patch.json" { "notes": "Enterprise search software.", "offerings": [ "Acme Search" ], "audience": [ { "id": "developers", "label": "Developers", "description": "Software teams", "percentage": 100, "enabled": true } ] } ``` *Profile update input* ## 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 brands`: - [`--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)