Temporal CLI cloud custom-role command reference
This page provides a reference for the temporal cloud custom-role commands. The flags applicable to each subcommand are presented in a table within the heading for the subcommand. Refer to Global Flags for flags that you can use with every subcommand.
apply
Apply a custom role configuration to Temporal Cloud. Creates a new role if no role with the given name exists, or updates the existing one to match the specification.
The specification can be provided as inline JSON or loaded from a file by prefixing the path with '@'.
Example:
temporal cloud custom-role apply --spec @custom-role.json
Use the following options to change the behavior of this command. You can also use any of the global flags that apply to all subcommands.
| Flag | Required | Description |
|---|---|---|
--api-key | No | string API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. |
--async | No | bool Return immediately after initiating the operation instead of waiting for completion. Use the returned operation ID to check status later. |
--async-operation-id | No | string Custom identifier for tracking this async operation. If not provided, a unique ID is generated automatically. |
--idempotent | No | bool Succeed silently if the resource already exists or matches the specification. Without this flag, the command errors when no changes are needed. |
--poll-interval | No | duration Time to wait between status checks when waiting for operation completion. Cannot be greater than 10 minutes. Supports minutes (m) and seconds (s). |
--resource-version, -v | No | string Resource version for optimistic concurrency control. If not provided, the current version is fetched automatically. |
--server | No | string Override the Temporal Cloud API server address. Used for connecting to non-production environments. |
--spec | Yes | string Custom role specification in JSON format. Provide inline JSON directly, or use '@path/to/file.json' to load from a file. |
--verbose-diff | No | bool Show detailed differences between the current and desired namespace configurations when changes are detected. |
create
Create a new Temporal Cloud custom role from a JSON specification.
The specification can be provided as inline JSON or loaded from a file by prefixing the path with '@'.
Example with inline JSON:
temporal cloud custom-role create --spec '{"name":"reader","description":"...","permissions":[...]}'
Example with file path:
temporal cloud custom-role create --spec @custom-role.json
Use the following options to change the behavior of this command. You can also use any of the global flags that apply to all subcommands.
| Flag | Required | Description |
|---|---|---|
--api-key | No | string API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. |
--async | No | bool Return immediately after initiating the operation instead of waiting for completion. Use the returned operation ID to check status later. |
--async-operation-id | No | string Custom identifier for tracking this async operation. If not provided, a unique ID is generated automatically. |
--idempotent | No | bool Succeed silently if the resource already exists or matches the specification. Without this flag, the command errors when no changes are needed. |
--poll-interval | No | duration Time to wait between status checks when waiting for operation completion. Cannot be greater than 10 minutes. Supports minutes (m) and seconds (s). |
--server | No | string Override the Temporal Cloud API server address. Used for connecting to non-production environments. |
--spec | Yes | string Custom role specification in JSON format. Provide inline JSON directly, or use '@path/to/file.json' to load from a file. |
delete
Delete a Temporal Cloud custom role. This action is irreversible.
Example:
temporal cloud custom-role delete --role-id my-role-id
Use the following options to change the behavior of this command. You can also use any of the global flags that apply to all subcommands.
| Flag | Required | Description |
|---|---|---|
--api-key | No | string API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. |
--async | No | bool Return immediately after initiating the operation instead of waiting for completion. Use the returned operation ID to check status later. |
--async-operation-id | No | string Custom identifier for tracking this async operation. If not provided, a unique ID is generated automatically. |
--idempotent | No | bool Succeed silently if the resource already exists or matches the specification. Without this flag, the command errors when no changes are needed. |
--poll-interval | No | duration Time to wait between status checks when waiting for operation completion. Cannot be greater than 10 minutes. Supports minutes (m) and seconds (s). |
--resource-version, -v | No | string Resource version for optimistic concurrency control. If not provided, the current version is fetched automatically. |
--role-id | Yes | string The ID of the custom role. |
--server | No | string Override the Temporal Cloud API server address. Used for connecting to non-production environments. |
edit
Open a custom role configuration in your default editor for interactive modification. After saving and closing the editor, the changes are applied to Temporal Cloud.
The editor is determined by the EDITOR environment variable, falling back to 'vi' if not set.
Example:
temporal cloud custom-role edit --role-id my-role-id
Use the following options to change the behavior of this command. You can also use any of the global flags that apply to all subcommands.
| Flag | Required | Description |
|---|---|---|
--api-key | No | string API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. |
--async | No | bool Return immediately after initiating the operation instead of waiting for completion. Use the returned operation ID to check status later. |
--async-operation-id | No | string Custom identifier for tracking this async operation. If not provided, a unique ID is generated automatically. |
--idempotent | No | bool Succeed silently if the resource already exists or matches the specification. Without this flag, the command errors when no changes are needed. |
--poll-interval | No | duration Time to wait between status checks when waiting for operation completion. Cannot be greater than 10 minutes. Supports minutes (m) and seconds (s). |
--resource-version, -v | No | string Resource version for optimistic concurrency control. If not provided, the current version is fetched automatically. |
--role-id | Yes | string The ID of the custom role. |
--server | No | string Override the Temporal Cloud API server address. Used for connecting to non-production environments. |
--verbose-diff | No | bool Show detailed differences between the current and desired namespace configurations when changes are detected. |
get
Retrieve the configuration and status of a Temporal Cloud custom role.
Example:
temporal cloud custom-role get --role-id my-role-id
Use the following options to change the behavior of this command. You can also use any of the global flags that apply to all subcommands.
| Flag | Required | Description |
|---|---|---|
--api-key | No | string API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. |
--role-id | Yes | string The ID of the custom role. |
--server | No | string Override the Temporal Cloud API server address. Used for connecting to non-production environments. |
list
List all Temporal Cloud custom roles accessible with the current authentication credentials.
Example:
temporal cloud custom-role list
Use the following options to change the behavior of this command. You can also use any of the global flags that apply to all subcommands.
| Flag | Required | Description |
|---|---|---|
--api-key | No | string API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. |
--page-size | No | int Number of custom roles to return per page. Use for paginated results. |
--page-token | No | string Token for retrieving the next page of results in a paginated list. |
--server | No | string Override the Temporal Cloud API server address. Used for connecting to non-production environments. |
update
Update an existing Temporal Cloud custom role from a JSON specification. Replaces the role's spec with the provided one.
Example:
temporal cloud custom-role update --role-id my-role-id --spec @custom-role.json
Use the following options to change the behavior of this command. You can also use any of the global flags that apply to all subcommands.
| Flag | Required | Description |
|---|---|---|
--api-key | No | string API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. |
--async | No | bool Return immediately after initiating the operation instead of waiting for completion. Use the returned operation ID to check status later. |
--async-operation-id | No | string Custom identifier for tracking this async operation. If not provided, a unique ID is generated automatically. |
--idempotent | No | bool Succeed silently if the resource already exists or matches the specification. Without this flag, the command errors when no changes are needed. |
--poll-interval | No | duration Time to wait between status checks when waiting for operation completion. Cannot be greater than 10 minutes. Supports minutes (m) and seconds (s). |
--resource-version, -v | No | string Resource version for optimistic concurrency control. If not provided, the current version is fetched automatically. |
--role-id | Yes | string The ID of the custom role. |
--server | No | string Override the Temporal Cloud API server address. Used for connecting to non-production environments. |
--spec | Yes | string Custom role specification in JSON format. Provide inline JSON directly, or use '@path/to/file.json' to load from a file. |
Global Flags
The following options can be used with any command.
| Flag | Required | Description | Default |
|---|---|---|---|
--api-key | No | string API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. | |
--auto-confirm | No | bool Automatically confirm prompts and actions that require user confirmation. Useful for scripting and automation. | |
--config-dir | No | string Directory path where CLI configuration files are stored, including authentication tokens and settings. | |
--disable-pop-up | No | bool Prevent the CLI from opening a browser window during authentication. Useful for headless environments or when using alternative auth methods. | |
--server | No | string Override the Temporal Cloud API server address. Used for connecting to non-production environments. | saas-api.tmprl.cloud:443 |