--- title: workspace description: Inspect and save the Workspace selected by the CLI. canonical_url: https://orchestor.io/docs/en/cli/workspace markdown_url: https://orchestor.io/docs/en/cli/workspace.md contentType: reference --- # workspace `orc workspace` inspects the selected Workspace and saves a link for the current directory or a default for future commands. It does not create Workspaces or change their server-side settings. See [`orc workspaces`](https://orchestor.io/docs/cli/workspaces.md) for API operations. Selecting a Workspace locally does not grant access to it. ## Usage ```bash title="terminal" orc workspace current ``` *Inspect the selected Workspace and its source.* ## Subcommands ### `current` Returns the selected `id` and its `source`. When unconfigured, returns `id: null`, `source: none`, and guidance for selecting a Workspace. ```bash title="terminal" orc workspace current [options] ``` ### `link` Saves a Workspace ID in `.orchestor/workspace.json` in the current directory. If ID is omitted, uses the currently resolved Workspace. No available target is a validation error. Returns `workspaceId` and `path`. ```bash title="terminal" orc workspace link [id] [options] ``` ### `unlink` Removes `.orchestor/workspace.json` from the current directory. Returns a result even if the file did not exist; `unlinked` indicates whether it existed. Does not remove the global default Workspace. ```bash title="terminal" orc workspace unlink [options] ``` ### `use` Saves the required ID as local configuration `defaultWorkspace`. Returns `defaultWorkspace` and `configPath`. A directory link or environment variable takes precedence over this default. ```bash title="terminal" orc workspace use [options] ``` ### `list` List workspaces ```bash title="terminal" orc workspace list [options] ``` #### Unique options ##### `--include-archived` Include archived workspaces in the response.; enum: true|false Type: `string`. Optional. ```bash title="terminal" orc workspace 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 workspace list --include-management ``` ### `create` Create workspace ```bash title="terminal" orc workspace 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 workspace 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 workspace 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 workspace create --slug ``` ##### `--workspace-type` Workspace type. Omission creates a team workspace.; enum: personal|team Type: `string`. Optional. ```bash title="terminal" orc workspace 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 workspace 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 workspace 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 workspace 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 workspace 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 workspace 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 workspace create --default-language-code ``` ### `get` Get workspace ```bash title="terminal" orc workspace get [options] ``` ### `update` Update workspace ```bash title="terminal" orc workspace 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 workspace 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 workspace update --is-default ``` ##### `--name` Replacement workspace display name. Omit to retain the current value.; max 120 chars Type: `string`. Optional. ```bash title="terminal" orc workspace 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 workspace 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 workspace 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 workspace 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 workspace 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 workspace 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 workspace 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 workspace 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 workspace update --purpose ``` ### `archive` Archive workspace ```bash title="terminal" orc workspace 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 workspace archive --idempotency-key ``` ### `restore` Restore workspace ```bash title="terminal" orc workspace 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 workspace restore --idempotency-key ``` ## Examples ### Link the current directory. ```bash title="terminal" orc workspace link ``` *Link the current directory.* ### Set the default Workspace. ```bash title="terminal" orc workspace use ``` *Set the default Workspace.* ### Remove the directory link. ```bash title="terminal" orc workspace unlink ``` *Remove the directory link.* ## Selection precedence Selection uses `--workspace`, `ORCHESTOR_WORKSPACE_ID`, `.orchestor/workspace.json` in the current directory, then global `defaultWorkspace`. If the target is unexpected, check `current` output `source` and higher-priority settings. `link` and `use` save local selection. The server checks authentication and membership when an operation is performed. ## Global Options The following [global options](https://orchestor.io/docs/cli/global-flags.md) can be used with `orc workspace`: - [`--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)