---
title: organization
description: Manage organization settings, members, and invitations.
canonical_url: https://orchestor.io/docs/en/cli/organization
markdown_url: https://orchestor.io/docs/en/cli/organization.md
contentType: reference
---

# organization

`orc organization` lists your Organizations, switches the CLI target, and manages organization settings, members, and invitations. You can change the organization name and Brand / Agency settings, update members’ organization roles, and send or revoke invitations.

Before running the command, authenticate with `orc auth login`. Switching organizations requires membership in the target organization and an available Workspace. API keys operate within the authenticated organization’s scope. To change your own display name, use [`orc profile`](https://orchestor.io/docs/cli/profile.md).

`use` saves the CLI selection. It keeps the current Workspace if it belongs to the target organization; otherwise, it selects an available Workspace in the target organization. Directory Workspace links that do not belong to the target organization are removed.

## Usage

```bash title="terminal"
orc organization list
```

*List the IDs, names, and organization roles of your organizations.*

## Switching organizations and Workspaces

Pass the organization ID from `organization list` to `organization use`. Organization names and slugs are not accepted. There is no interactive selection when the ID is omitted.

```bash title="terminal"
orc organization use <organization-id>
orc organization current
orc workspace current
```

*Switch organizations and check the selected organization and Workspace.*

Switching retrieves your organization memberships and available Workspaces, validates the selected Workspace through the API, then saves it in the current CLI profile. If no Workspace is available in the target organization, the command returns an error without changing the selection. To select another Workspace, use `list` and `use` in `orc workspace`.

```bash title="terminal"
orc workspace list
orc workspace use <workspace-id>
orc workspace link <workspace-id>
```

*Select a Workspace in the same organization and optionally link it to the current directory.*

Workspaces are resolved in this order: `--workspace`, `ORCHESTOR_WORKSPACE_ID`, the directory link, then the saved default. To specify a target for one API operation, use `--workspace <workspace-id>`. Switching organizations removes directory links that do not belong to the target organization. If `ORCHESTOR_WORKSPACE_ID` points outside the target organization, unset the environment variable before running the command again.

## Subcommands

### `use`

Saves the CLI selection using an organization ID. Keeps the current Workspace if it belongs to the target organization; otherwise, selects an available Workspace. Nothing is saved until membership checks and API validation succeed.

```bash title="terminal"
orc organization use <organization-id> [options]
```

#### Examples

```bash title="terminal"
orc organization use <organization-id>
```

*Save the CLI selection using an organization ID.*

### `current`

Displays the settings of the organization resolved from the current Workspace and your organization role. You can check the organization name, `organization_type`, `slug`, `website_url`, and `member_count`.

```bash title="terminal"
orc organization current [options]
```

#### Examples

```bash title="terminal"
orc organization current --json
```

*Display the organization settings resolved from the current Workspace and your organization role.*

### `update`

Updates the organization’s `name`, `type`, `slug`, and `website_url`. `type` is `brand` or `agency`. Omitted fields are preserved, and `website_url` can be cleared with `null`. Do not specify both `type` and the compatibility field `organization_type`.

```bash title="terminal"
orc organization update [options]
```

#### Unique options

##### `--name`

Body field: name

Type: `string`. Optional.

```bash title="terminal"
orc organization update --name <value>
```

##### `--slug`

Body field: slug

Type: `string`. Optional.

```bash title="terminal"
orc organization update --slug <value>
```

##### `--organization-type`

Body field: organization_type; enum: brand|agency

Type: `string`. Optional.

```bash title="terminal"
orc organization update --organization-type <value>
```

##### `--website-url`

The agency Organization's own website URL. Brand Organizations may leave this null because the managed brand URL belongs to Workspace setup.; (use "null" or "reset" to clear)

Type: `string`. Optional.

```bash title="terminal"
orc organization update --website-url <value>
```

##### `--type`

Body field: type; enum: brand|agency

Type: `string`. Optional.

```bash title="terminal"
orc organization update --type <value>
```

#### Examples

```bash title="terminal"
orc organization update --stdin < organization.json
```

*Update the organization’s name, type, slug, and website_url.*

### `invites list`

Lists invitation IDs, recipients, `org_role`, `workspace_assignments`, expiration, and status for the current organization. Filter with `--state pending|accepted|expired|revoked`. For the next page, pass the response’s `next_cursor` to `--cursor`; use `--limit` to set the number of items per page.

```bash title="terminal"
orc organization invites list [options]
```

#### Unique options

##### `--state`

enum: pending|accepted|expired|revoked

Type: `string`. Optional.

```bash title="terminal"
orc organization invites list --state <value>
```

#### Examples

```bash title="terminal"
orc organization invites list --state pending --limit 50 --json
```

*List invitation IDs, recipients, org_role, workspace_assignments, expiration, and status for the current organization.*

### `invites create`

Invites one person using `email` and `role` in the request body. `role` is `owner`, `admin`, or `member`. The compatibility field `org_role` is also supported, but it cannot be specified alongside `role` with a different value. Only an `owner` can invite an `owner`. Recipients who are already members or have an active invitation are rejected.

```bash title="terminal"
orc organization invites 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 organization invites create --idempotency-key <value>
```

##### `--email`

(required) Body field: email; max 255 chars

Type: `string`. Optional.

```bash title="terminal"
orc organization invites create --email <value>
```

##### `--org-role`

Body field: org_role; enum: owner|admin|member

Type: `string`. Optional.

```bash title="terminal"
orc organization invites create --org-role <value>
```

##### `--workspace-assignments`

Body field: workspace_assignments; JSON array of objects (use --stdin for large resources)

Type: `string`. Optional.

```bash title="terminal"
orc organization invites create --workspace-assignments <value>
```

##### `--role`

Body field: role; enum: owner|admin|member

Type: `string`. Optional.

```bash title="terminal"
orc organization invites create --role <value>
```

#### Examples

```bash title="terminal"
orc organization invites create --stdin < invitation.json
```

*Invite one person using email and role in the request body.*

### `invites delete`

Revokes a `pending` invitation using its ID from invites list. Invitations with `accepted`, `expired`, or `revoked` status cannot be revoked. To remove a member who has accepted an invitation, use `members delete`.

```bash title="terminal"
orc organization invites delete <id> [options]
```

#### Examples

```bash title="terminal"
orc organization invites delete <invite-id> --dry-run
```

*Revoke a pending invitation using its ID from invites list.*

### `list`

Lists the IDs, names, and organization roles of your organizations. Human accounts receive only active memberships; API keys receive the authenticated organization’s scope.

```bash title="terminal"
orc organization list [options]
```

#### Examples

```bash title="terminal"
orc organization list --json
```

*List the IDs, names, and organization roles of your organizations.*

### `members list`

Lists `user_id`, `first_name`, `last_name`, and `role` for members with active membership in the current organization. The list is not limited to a single Workspace.

```bash title="terminal"
orc organization members list [options]
```

#### Examples

```bash title="terminal"
orc organization members list --json
```

*List user_id, first_name, last_name, and role for active members of the current organization.*

### `members update`

Changes an organization role using the `user_id` from `members list` and `role` in the request body. `role` is `owner`, `admin`, or `member`. Only an `owner` can manage an `owner`, and demoting the last `owner` is rejected.

```bash title="terminal"
orc organization members update <user-id> [options]
```

#### Unique options

##### `--role`

(required) Body field: role; enum: owner|admin|member

Type: `string`. Optional.

```bash title="terminal"
orc organization members update <user-id> --role <value>
```

#### Examples

```bash title="terminal"
orc organization members update <user-id> --stdin < member.json
```

*Change an organization role using user_id from members list and role in the request body.*

### `members delete`

Removes membership in the current organization and the associated Workspace access. Does not delete the account itself. Only an `owner` can remove an `owner`, and the last `owner` cannot be removed. The command asks you to confirm the target.

```bash title="terminal"
orc organization members delete <user-id> [options]
```

#### Examples

```bash title="terminal"
orc organization members delete <user-id> --dry-run
```

*Remove membership in the current organization and its associated Workspace access.*

## Examples

### Check organizations and the current target.

The `id` from `list` is the organization ID to pass to `use`. The `workos_organization_id` from `current` represents the same organization identifier.

```bash title="terminal"
orc organization list --json
orc organization current --json
```

*Check organizations and the current target.*

### Prepare an organization settings update body.

Omitted `name` and `type` fields are preserved. `type` is `brand` or `agency`.

```json title="organization.json"
{
  "name": "Example Agency",
  "type": "agency"
}
```

*Prepare an organization settings update body.*

### Inspect the organization settings request before updating.

For updates, `--dry-run` displays a request preview without calling the update API. It does not guarantee that server-side permission checks will succeed.

```bash title="terminal"
orc organization update --stdin < organization.json --dry-run
orc organization update --stdin < organization.json
```

*Inspect the organization settings request before updating.*

### Prepare a body to change an organization role.

Organization roles are `owner`, `admin`, and `member`. They are separate from Workspace roles.

```json title="member.json"
{
  "role": "member"
}
```

*Prepare a body to change an organization role.*

### Find the user ID in the member list and change the role.

Specify `user_id` from `members list`. Do not use a Workspace member ID or invitation ID.

```bash title="terminal"
orc organization members list --json
orc organization members update <user-id> --stdin < member.json
```

*Find the user ID in the member list and change the role.*

### Specify the invitation recipient and organization role.

Each operation invites one person. Granting an organization role and assigning Workspace access are separate inputs.

```json title="invitation.json"
{
  "email": "member@example.com",
  "role": "member"
}
```

*Specify the invitation recipient and organization role.*

### Create an invitation and check pending invitations.

Creating an invitation is rejected if the recipient is already a member or has an active invitation. Check the API response for the successful invitation’s ID, status, and expiration.

```bash title="terminal"
orc organization invites create --stdin < invitation.json
orc organization invites list --state pending --json
```

*Create an invitation and check pending invitations.*

## Organization roles and Workspace access

Organization roles are `owner`, `admin`, and `member`. Only an organization `owner` can invite, modify, or remove an `owner`. An `admin` can manage `member` and `admin` roles, but cannot grant or manage `owner`. Demoting or removing the last organization `owner` is rejected.

`members delete` removes membership in that organization and disables the Workspace access associated with the membership. It does not delete the account itself or membership in other organizations. When using `workspace_assignments` in an invitation, specify `workspace_id` and `workspace_role` in each item. Workspace roles are `owner` or `member`; Workspaces in other organizations cannot be assigned.

```json title="invitation.json"
{
  "email": "member@example.com",
  "role": "member",
  "workspace_assignments": [
    { "workspace_id": "<workspace-id>", "workspace_role": "member" }
  ]
}
```

*Specify an organization invitation and access to a Workspace in the same organization.*

## Permissions

Lists, current organization details, and member lists are available within your authenticated membership scope. Updating organization settings requires the organization `owner` or `admin` role and `workspace:settings` permission. Invitation operations require the organization `owner` or `admin` role and `workspace:invite` permission. Updating or removing members requires the organization `owner` or `admin` role. Being a Workspace `owner` does not automatically grant organization management permissions.

## Global Options

The following [global options](https://orchestor.io/docs/cli/global-flags.md) can be used with `orc organization`:

- [`--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)

For details and examples, see [global options](https://orchestor.io/docs/cli/global-flags.md).

## Troubleshooting

### Cannot switch organizations

Check that you are specifying `id` from `organization list` and that an available Workspace exists in the target organization. Unset `ORCHESTOR_WORKSPACE_ID` if it points to another organization. You cannot switch beyond an API key’s organization scope. Sign in with a human account and run the command again.

### Cannot change organization settings or members

Check `role` in `organization current`. Workspace management permissions and organization management permissions are separate. An `admin` cannot grant or manage `owner`, and the last `owner` cannot be removed. Use `user_id` from `members list` to identify a member.

### Cannot create or revoke an invitation

You cannot create a duplicate invitation when the recipient is already a member or an active invitation remains. Check the status with `invites list --state pending`. Only `pending` invitations can be revoked. To remove a member who has accepted an invitation, use `members delete`.

### Removing access in a non-interactive environment

DELETE operations require confirmation. For automated execution, verify the target ID and organization, then specify [`--yes`](https://orchestor.io/docs/cli/global-flags.md#yes). You can first inspect the target request with `--dry-run`.

## Related

- `orc auth`: Sign in to the CLI and check credentials.
- `orc workspace`: Select Workspaces and link them to directories.
- [`orc profile`](https://orchestor.io/docs/cli/profile.md): Inspect and update your own profile.
- [Global options](https://orchestor.io/docs/cli/global-flags.md): JSON output, standard input, request previews, and deletion confirmation.

---

[Documentation index](https://orchestor.io/docs/llms.txt)