--- title: workspaces description: Manage Workspace settings, measurement, and members. canonical_url: https://orchestor.io/docs/en/cli/workspaces markdown_url: https://orchestor.io/docs/en/cli/workspaces.md contentType: reference --- # workspaces `orc workspaces` creates and inspects Workspaces and manages settings, member access, and measurement pause/resume. You can also check initial setup progress, measurement countries and languages, model configuration, and revision history. Authentication is required. Settings operations for the current Workspace use the CLI selection; operations targeting a particular Workspace take its ID. Credentials for organization capacity, creation, and access grants have a different scope from credentials that read an individual Workspace’s measurement data. ## Usage ```bash title="terminal" orc workspaces list --json ``` *List accessible Workspaces.* ## Subcommands ### `setup get` Retrieves the saved initial setup checkpoint. Use `--wait` to wait until setup and first observation reach a terminal state, and `--timeout` and `--poll-interval` to control the wait duration and polling interval. The default polling interval is `5s`. ```bash title="terminal" orc workspaces setup get [options] ``` ### `measurement-targets get` Retrieves saved measurement countries and languages, defaults, selectable codes, and contract limits including add-on capacity. ```bash title="terminal" orc workspaces measurement-targets get [options] ``` ### `measurement-targets update` Updates country and language arrays. Each array replaces the whole stored value, and its first entry becomes the default. Include existing values when adding entries. Limits are checked against countries and languages used by active prompts too; this operation does not purchase add-on capacity. ```bash title="terminal" orc workspaces measurement-targets update [options] ``` #### Unique options ##### `--measurement-country-codes` Configured measurement countries. The first entry is the default. Limited by the workspace contract and add-ons.; csv Type: `string`. Optional. ```bash title="terminal" orc workspaces measurement-targets update --measurement-country-codes ``` ##### `--measurement-language-codes` Configured measurement languages. The first entry is the default. Base languages count toward the workspace allowance.; csv Type: `string`. Optional. ```bash title="terminal" orc workspaces measurement-targets update --measurement-language-codes ``` ##### `--default-country-code` Workspace measurement target country; browser runs use managed proxy geolocation. Type: `string`. Optional. ```bash title="terminal" orc workspaces measurement-targets update --default-country-code ``` ##### `--default-language-code` Workspace measurement language applied to subsequent measurements. Type: `string`. Optional. ```bash title="terminal" orc workspaces measurement-targets update --default-language-code ``` ### `list` Lists accessible Workspaces. Include archived entries with `--include-archived`, or brand, monitoring configuration, and production prompt entitlement summaries with `--include-management`. ```bash title="terminal" orc workspaces list [options] ``` #### Unique options ##### `--include-archived` Include archived workspaces in the response.; enum: true|false Type: `string`. Optional. ```bash title="terminal" orc workspaces list --include-archived ``` ##### `--include-management` Include brand, monitoring configuration, and production prompt entitlement summaries for accessible workspaces.; enum: true|false Type: `string`. Optional. ```bash title="terminal" orc workspaces list --include-management ``` ### `create` Creates a Workspace from its name and other settings. A supplied `brand` is registered as an active owned brand without separate activation. `setup_mode` of `empty` skips candidate generation and measurement, `suggestions` stops after generation, and `measure` generates and measures. Activate manually created draft prompts before measuring them. ```bash title="terminal" orc workspaces 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 workspaces create --idempotency-key ``` ##### `--name` (required) Workspace display name after trimming surrounding whitespace. Must contain 1 to 120 characters.; max 120 chars Type: `string`. Optional. ```bash title="terminal" orc workspaces create --name ``` ##### `--slug` Preferred workspace URL slug. Omit or send an empty string to derive it from name. The server normalizes to lowercase letters, digits and hyphens and resolves conflicts within the organization. Type: `string`. Optional. ```bash title="terminal" orc workspaces create --slug ``` ##### `--workspace-type` Workspace type. Omission creates a team workspace.; enum: personal|team Type: `string`. Optional. ```bash title="terminal" orc workspaces create --workspace-type ``` ##### `--client-label` Optional client-facing label. Surrounding whitespace is removed; omitted, null or empty values store no label.; (use "null" or "reset" to clear) Type: `string`. Optional. ```bash title="terminal" orc workspaces create --client-label ``` ##### `--purpose` Commercial workspace purpose, defaulting to client in the extended flow. Supplying this field selects extended creation. pitch requires an agency organization and consumes monthly and active pitch quotas.; enum: client|pitch Type: `string`. Optional. ```bash title="terminal" orc workspaces create --purpose ``` ##### `--setup-mode` Creation stopping point. A supplied owned brand is initialized active in every mode; no separate brand activation is required. Brand readiness does not start measurement. empty skips setup generation and measurement; brand is optional. suggestions generates review candidates without starting measurement. measure generates and measures. Omission uses measure if any extended setup field is present; otherwise creation is empty. Pitch quotas and seven-day expiry begin at creation in every mode.; enum: empty|suggestions|measure Type: `string`. Optional. ```bash title="terminal" orc workspaces create --setup-mode ``` ##### `--brand` Managed brand to initialize. Required for suggestions and measure. Optional for empty; when provided, both name and domain are required. Supplying brand without setup_mode starts the measure flow.; (JSON object, e.g. '{"custom_id":"x"}') Type: `string`. Optional. ```bash title="terminal" orc workspaces create --brand ``` ##### `--default-country-code` Two-letter default observation country code. Trimmed and uppercased. Defaults to JP in the extended flow. Supplying this field selects extended creation even without setup_mode. Type: `string`. Optional. ```bash title="terminal" orc workspaces create --default-country-code ``` ##### `--default-language-code` Default observation language code, optionally with a regional suffix. Trimmed and lowercased, for example ja or en-us. Defaults to ja in the extended flow. Supplying this field selects extended creation even without setup_mode. Type: `string`. Optional. ```bash title="terminal" orc workspaces create --default-language-code ``` ### `quotas get` Retrieves organization Workspace capacity. A Workspace-scoped key receives `403 insufficient_scope`; this does not mean the capacity is empty. ```bash title="terminal" orc workspaces quotas get [options] ``` ### `get` Retrieves information for a Workspace ID. ```bash title="terminal" orc workspaces get [options] ``` ### `update` Updates a Workspace’s name, URL slug, appearance, and other settings by ID. Also supports converting a non-archived pitch Workspace to `purpose: client`. ```bash title="terminal" orc workspaces 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 workspaces update --idempotency-key ``` ##### `--is-default` Set this workspace as the organization default. Must be true and the only field in the body. Requires a human organization owner or admin; machine credentials cannot perform this change.; enum: true Type: `string`. Optional. ```bash title="terminal" orc workspaces update --is-default ``` ##### `--name` Replacement workspace display name. Omit to retain the current value.; max 120 chars Type: `string`. Optional. ```bash title="terminal" orc workspaces update --name ``` ##### `--slug` Replacement preferred slug. Normalized and made unique within the organization. Omit to retain the current slug. Type: `string`. Optional. ```bash title="terminal" orc workspaces update --slug ``` ##### `--client-label` Replacement client-facing label. Omit to retain it; null or an empty string clears it. Nonempty strings are trimmed.; (use "null" or "reset" to clear) Type: `string`. Optional. ```bash title="terminal" orc workspaces update --client-label ``` ##### `--color-token` Workspace visual identity color. Omit to retain the current token.; enum: default|gray|brown|orange|yellow|green|blue|purple|pink|red Type: `string`. Optional. ```bash title="terminal" orc workspaces update --color-token ``` ##### `--identity-kind` Workspace visual identity rendering mode. Omit to retain the current mode. Set the corresponding icon, emoji or image value separately when needed.; enum: color|initial|icon|emoji|image Type: `string`. Optional. ```bash title="terminal" orc workspaces update --identity-kind ``` ##### `--icon-token` Icon identifier used by icon identity mode. Omit to retain it; null or an empty string clears it. Does not change identity_kind.; (use "null" or "reset" to clear); max 64 chars Type: `string`. Optional. ```bash title="terminal" orc workspaces update --icon-token ``` ##### `--emoji` Emoji value used by emoji identity mode. Omit to retain it; null or an empty string clears it. Does not change identity_kind.; (use "null" or "reset" to clear); max 32 chars Type: `string`. Optional. ```bash title="terminal" orc workspaces update --emoji ``` ##### `--image-file-id` File ID used by image identity mode. Omit to retain it; null or an empty string clears it. Does not change identity_kind.; (use "null" or "reset" to clear) Type: `string`. Optional. ```bash title="terminal" orc workspaces update --image-file-id ``` ##### `--purpose` Set client to convert an unarchived pitch workspace. Submit only purpose and optional dry_run. The conversion is irreversible. A request to convert to pitch is rejected.; enum: client|pitch Type: `string`. Optional. ```bash title="terminal" orc workspaces update --purpose ``` ### `archive` Archives a Workspace by ID. Use `restore` to restore it. ```bash title="terminal" orc workspaces archive [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 workspaces archive --idempotency-key ``` ### `restore` Restores an archived Workspace by ID. ```bash title="terminal" orc workspaces restore [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 workspaces restore --idempotency-key ``` ### `pause` Pauses measurement for the specified Workspace. `--dry-run` returns the resulting response without persisting the change. ```bash title="terminal" orc workspaces pause [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 workspaces pause --idempotency-key ``` ### `resume` Resumes measurement for a paused Workspace. ```bash title="terminal" orc workspaces resume [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 workspaces resume --idempotency-key ``` ### `members list` Lists members for a Workspace ID. ```bash title="terminal" orc workspaces members list [options] ``` ### `members create` Grants access using the target Workspace ID and an active human user ID in the same organization in `--user-id`. API key synthetic IDs are not valid human user IDs. ```bash title="terminal" orc workspaces members 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 workspaces members create --idempotency-key ``` ##### `--user-id` (required) User ID of an active member of the workspace organization. This is not a workspace-member assignment ID. The user must already belong to the organization. Type: `string`. Optional. ```bash title="terminal" orc workspaces members create --user-id ``` ##### `--workspace-role` Workspace role to assign, defaulting to member. If the assignment already exists, this role replaces its current role and the assignment becomes active.; enum: owner|member Type: `string`. Optional. ```bash title="terminal" orc workspaces members create --workspace-role ``` ### `members delete` Removes a member’s access using a Workspace ID and user ID. ```bash title="terminal" orc workspaces members delete [options] ``` ### `measurement-configurations get` Retrieves the current Workspace’s measurement configuration, including the configured location, language, and model selection. ```bash title="terminal" orc workspaces measurement-configurations get [options] ``` ### `measurement-configurations update` Updates configuration using JSON objects in `default_location` and `platform_selection` and a language code in `default_language`. Send complete JSON with `--stdin` to submit all three settings as one resource. ```bash title="terminal" orc workspaces measurement-configurations update [options] ``` #### Unique options ##### `--default-location` (required) Execution location. Choose global without code, or country with an uppercase two-letter code. Region and city locations are not accepted for execution. Type: `string`. Optional. ```bash title="terminal" orc workspaces measurement-configurations update --default-location ``` ##### `--default-language` (required) Default execution language tag, such as ja-JP. Used when a measurement inherits the workspace language. Type: `string`. Optional. ```bash title="terminal" orc workspaces measurement-configurations update --default-language ``` ##### `--platform-selection` (required) Choose all eligible observation channels, or provide a non-empty explicit set. Direct provider API channels are not supported for saved measurement configuration. Type: `string`. Optional. ```bash title="terminal" orc workspaces measurement-configurations update --platform-selection ``` ##### `--cadence` Preferred cadence; weekly billing entitlements remain weekly.; enum: daily|weekly Type: `string`. Optional. ```bash title="terminal" orc workspaces measurement-configurations update --cadence ``` ### `measurement-configurations revisions list` Lists append-only measurement configuration revisions. Paginate with `--limit` and `--cursor`. ```bash title="terminal" orc workspaces measurement-configurations revisions list [options] ``` ## Examples ### Wait for setup and first observation to finish. ```bash title="terminal" orc workspaces setup get --wait --timeout 5m --json ``` *Wait for setup and first observation to finish.* ### Retrieve saved measurement countries and languages. ```bash title="terminal" orc workspaces measurement-targets get --workspace wks_example --json ``` *Retrieve saved measurement countries and languages.* ### Replace countries and languages, including existing values. ```bash title="terminal" printf '%s' '{"measurement_country_codes":["JP","US"],"measurement_language_codes":["ja","en"]}' | orc workspaces measurement-targets update --workspace wks_example --stdin --json ``` *Replace countries and languages, including existing values.* ### Update measurement configuration with complete JSON. ```bash title="terminal" orc workspaces measurement-configurations update --stdin < measurement-configuration.json --json ``` *Update measurement configuration with complete JSON.* ### Grant human access to a Workspace after creation. ```bash title="terminal" orc workspaces members create WORKSPACE_ID --user-id USER_ID --workspace-role member --json ``` *Grant human access to a Workspace after creation.* ## Access grants and organization capacity Access grants target an active human Organization user ID in the same organization. An organization-scoped write API key or a Workspace owner/admin can perform the operation. Do not pass an API key’s `apikey:...` synthetic ID as a human ID. A Workspace created with an organization key does not automatically create human `workspace_members`, so run `members create` after creation. A target outside the organization boundary returns `404`; read-only keys or humans without permission receive `403`. After the grant, use `orc workspace use ` in the human profile, or `--workspace ` on data commands. Use the organization key for capacity, Workspace creation, and access grants. Read setup, brands, prompts, and reports with the granted human or Workspace-scoped credentials. ## Measurement target API and MCP The measurement target APIs are `GET /v1/workspaces/current/measurement-targets` and `PATCH /v1/workspaces/current/measurement-targets`. Specify `Authorization: Bearer ` and `X-Workspace-ID` for API requests. Retrieval requires read scope; updates require write scope. For MCP, use `workspace_measurement_targets_get` and `workspace_measurement_targets_update`. Enable the write profile for updates and provide `idempotency_key` and the arrays to change. After the user approves, resend the same input with the `approval_id` from the initial `approval_required` response as `approval_receipt`. Nothing is saved before approval. ## Global Options The following [global options](https://orchestor.io/docs/cli/global-flags.md) can be used with `orc workspaces`: - [`--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)