--- title: domains description: Manage brand domains for verification and ingestion. canonical_url: https://orchestor.io/docs/en/cli/domain markdown_url: https://orchestor.io/docs/en/cli/domain.md contentType: reference --- # domains `orc domains` manages Domain resources used for brand verification and ingestion. List, inspect, create, update, or delete domains, start ownership checks, inspect status, and request rechecks. Filter lists by the `primary` or `alternate` role, verification state, or ingestion state. Authentication and access to the target Workspace are required. The `id` is the Domain resource ID returned by listing, not a hostname. This is separate from a brand’s `domain` and `domains` registry. Check the saved verification method and token-publication instructions before starting verification. ## Usage ```bash title="terminal" orc domains list --workspace ``` *Inspect Domain resources and verification status.* ## Subcommands ### `list` List non-deleted Domains. Combine `--brand-id`, `--role`, `--verification-status`, and `--ingestion-status` to filter results. Preserve filters while following cursors. ```bash title="terminal" orc domains list [options] ``` #### Unique options ##### `--brand-id` Filter by brand id in the selected workspace. Omit to include domains or suggestions for all brands. Type: `string`. Optional. ```bash title="terminal" orc domains list --brand-id ``` ##### `--role` Filter by the stored domain role. Omit to include both primary and alternate domains.; enum: primary|alternate Type: `string`. Optional. ```bash title="terminal" orc domains list --role ``` ##### `--verification-status` Filter by the stored ownership verification state. Omit to include all states.; enum: unverified|pending|verified|failed Type: `string`. Optional. ```bash title="terminal" orc domains list --verification-status ``` ##### `--ingestion-status` Filter by the stored ingestion state. Omit to include all states.; enum: not_configured|configured|active|error Type: `string`. Optional. ```bash title="terminal" orc domains list --ingestion-status ``` ### `create` `domain` and a `brand_id` in the current Workspace are required. Role defaults to `alternate`, and verification starts as `unverified`. Setting a verification method creates a token but does not start verification. ```bash title="terminal" orc domains 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 domains create --idempotency-key ``` ##### `--domain` (required) Hostname stored for ownership verification and ingestion, without a protocol or path. Type: `string`. Optional. ```bash title="terminal" orc domains create --domain ``` ##### `--brand-id` (required) Existing non-deleted brand in the selected workspace to which this domain belongs. Type: `string`. Optional. ```bash title="terminal" orc domains create --brand-id ``` ##### `--role` Stored domain role: primary for the main domain, alternate for an additional domain. Defaults to alternate.; enum: primary|alternate Type: `string`. Optional. ```bash title="terminal" orc domains create --role ``` ##### `--verification-method` Ownership check method: dns_txt publishes the token in DNS; file_upload serves it at /.well-known/orchestor-domain-verify; manual requires support. Null means no method is configured. Omitted or null leaves the method unconfigured.; enum: |dns_txt|file_upload|manual; (use "null" or "reset" to clear) Type: `string`. Optional. ```bash title="terminal" orc domains create --verification-method ``` ##### `--ingestion-method` Configured traffic ingestion method. Null means no method is selected. Omitted or null leaves the method unconfigured.; enum: |log_forwarder|edge_worker|manual_upload; (use "null" or "reset" to clear) Type: `string`. Optional. ```bash title="terminal" orc domains create --ingestion-method ``` #### Examples ```bash title="terminal" orc domains create --domain acme.example --brand-id --verification-method dns_txt --workspace ``` *Register a Domain for DNS verification* ### `get` Retrieve details by Domain ID. Use `verification get` for the token and instructions. Missing, deleted, or out-of-Workspace IDs return 404. ```bash title="terminal" orc domains get [options] ``` ### `update` Change only supplied `role`, `verification_method`, and `ingestion_method`. A non-null verification method regenerates the token and resets status to `unverified`, even if unchanged. Null clears the method but retains the stored token and state. Verification does not start. ```bash title="terminal" orc domains update [options] ``` #### Unique options ##### `--role` Stored domain role: primary for the main domain, alternate for an additional domain. Omit to keep the stored value.; enum: primary|alternate Type: `string`. Optional. ```bash title="terminal" orc domains update --role ``` ##### `--verification-method` Ownership check method: dns_txt publishes the token in DNS; file_upload serves it at /.well-known/orchestor-domain-verify; manual requires support. Null means no method is configured. Omit to keep the stored value. A non-null value replaces the token and resets status to unverified. Null clears the method without clearing the existing token or status.; enum: |dns_txt|file_upload|manual; (use "null" or "reset" to clear) Type: `string`. Optional. ```bash title="terminal" orc domains update --verification-method ``` ##### `--ingestion-method` Configured traffic ingestion method. Null means no method is selected. Omit to keep the stored value.; enum: |log_forwarder|edge_worker|manual_upload; (use "null" or "reset" to clear) Type: `string`. Optional. ```bash title="terminal" orc domains update --ingestion-method ``` ### `delete` Soft-delete a Domain and return `id` and `deleted: true`. Subsequent lists and reads exclude it. Missing or deleted IDs return 404. ```bash title="terminal" orc domains delete [options] ``` ### `verify` Start asynchronous ownership verification using the saved `verification_method`. An unset method returns 400. Status becomes `pending`, and attempts and previous errors are reset. Check status through the returned `poll_url`. ```bash title="terminal" orc domains verify [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 domains verify --idempotency-key ``` #### Examples ```bash title="terminal" orc domains verify --workspace ``` *Start verification after publishing the token* ### `verification get` Retrieve saved status, token, and method-specific instructions. A verified Domain checked more than 24 hours ago may enqueue a background recheck. `stale_recheck_enqueued` indicates a request, not completion. ```bash title="terminal" orc domains verification get [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 domains verification get --idempotency-key ``` #### Examples ```bash title="terminal" orc domains verification get --workspace --json ``` *Retrieve the token and publication instructions* ### `verification refresh` Request another ownership check with the configured method and published token. Return 202 and `poll_url`, with status set to `pending`. Check instructions first if the token needs to be republished. ```bash title="terminal" orc domains verification 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 domains verification refresh --idempotency-key ``` ### `verification recheck` Recheck domain verification ```bash title="terminal" orc domains verification recheck [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 domains verification recheck --idempotency-key ``` ## Ownership verification flow 1. Set `verification_method` through `create` or `update`. Methods are `dns_txt`, `file_upload`, and `manual`. 2. Publish DNS records or files following the token and instructions from `verification get`. Manual verification requires support. 3. Run `verify` or `verification refresh`. Acceptance does not mean verification succeeded. 4. Poll `verification get` and inspect the `verified` or `failed` result. Passing a method to `verify` does not override saved settings. Change it with `update --verification-method`. Registration and verification settings alone do not guarantee active ingestion. Ingestion methods are `log_forwarder`, `edge_worker`, and `manual_upload`. ## 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 domains`: - [`--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)