Temporal CLI cloud service-account command reference
The temporal cloud CLI extension is in Pre-release.
Commands and options may change before the stable release.
This page provides a reference for the temporal cloud service-account 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.
create
Create a new Temporal Cloud service account with account-level access. Optionally assign an account role and namespace-level permissions.
Account roles: owner, admin, developer, finance-admin, read, metrics-read. Namespace access format: 'namespace=permission' where permission is one of: admin, write, read.
Example:
temporal cloud service-account create --name my-sa --account-role developer \
--namespace-access my-namespace.my-account=write
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 |
|---|---|---|
--account-role | No | string The account-level role to assign. Valid values: owner, admin, developer, finance-admin, read, metrics-read. |
--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. |
--custom-role | No | string[] Custom role ID to assign. Repeat to assign multiple. |
--description | No | string An optional description for the service account. |
--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. |
--name | Yes | string The name of the service account. Must be unique across all active service accounts. |
--namespace-access | No | string[] Namespace access to grant, in the format 'namespace=permission'. Permission must be one of: admin, write, read. Can be repeated. |
--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. |
create-namespace-scoped
Create a new Temporal Cloud service account scoped to a single namespace.
Example:
temporal cloud service-account create-namespace-scoped --name my-sa \
--namespace my-namespace.my-account --namespace-permission write
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. |
--description | No | string An optional description for the service account. |
--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. |
--name | Yes | string The name of the service account. Must be unique across all active service accounts. |
--namespace | Yes | string The namespace to scope the service account to. |
--namespace-permission | Yes | string The permission to grant on the namespace. Valid values: admin, write, read. |
--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. |
delete
Delete a Temporal Cloud service account. This action is irreversible.
Example:
temporal cloud service-account delete --service-account-id my-sa-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. |
--server | No | string Override the Temporal Cloud API server address. Used for connecting to non-production environments. |
--service-account-id | Yes | string The ID of the service account to delete. |
edit
Open a service account 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 service-account edit --service-account-id my-sa-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. |
--server | No | string Override the Temporal Cloud API server address. Used for connecting to non-production environments. |
--service-account-id | Yes | string The ID of the service account to edit. |
--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 service account.
Example:
temporal cloud service-account get --service-account-id my-sa-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. |
--server | No | string Override the Temporal Cloud API server address. Used for connecting to non-production environments. |
--service-account-id | Yes | string The ID of the service account to retrieve. |
list
List all Temporal Cloud service accounts accessible with the current authentication credentials.
Example:
temporal cloud service-account 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 service accounts 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. |
set-custom-roles
Set the custom roles assigned to a Temporal Cloud service account. Replaces the service account's current custom role list. Pass no --custom-role flags to remove all custom roles.
Not valid for namespace-scoped service accounts.
Example:
temporal cloud service-account set-custom-roles --service-account-id my-sa-id \
--custom-role role-id-1 --custom-role role-id-2
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. |
--custom-role | No | string[] Custom role ID to assign. Repeat to assign multiple. When provided, replaces the existing custom role list. |
--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. |
--service-account-id | Yes | string The ID of the service account. |
update
Update a Temporal Cloud service account. Only flags that are explicitly provided are changed.
For account-scoped service accounts, use --account-role and/or --namespace-access. For namespace-scoped service accounts, use --namespace-permission.
Namespace access format: 'namespace=permission' where permission is one of: admin, write, read. Use 'namespace=' (empty permission) to remove access to a namespace.
Example:
temporal cloud service-account update --service-account-id my-sa-id --name new-name
temporal cloud service-account update --service-account-id my-sa-id --account-role admin
temporal cloud service-account update --service-account-id my-sa-id --namespace-permission write
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 |
|---|---|---|
--account-role | No | string The account-level role to assign. Valid values: owner, admin, developer, finance-admin, read, metrics-read. Only valid for account-scoped service accounts. |
--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. |
--custom-role | No | string[] Custom role ID to assign. Repeat to assign multiple. When provided, replaces the existing custom role list. |
--description | No | string New description for the service account. |
--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. |
--name | No | string New name for the service account. |
--namespace-access | No | string[] Namespace access to set, in the format 'namespace=permission'. Use 'namespace=' to remove access. Permission must be one of: admin, write, read. Can be repeated. Only valid for account-scoped service accounts. |
--namespace-permission | No | string The permission to grant on the scoped namespace. Valid values: admin, write, read. Only valid for namespace-scoped service accounts. |
--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. |
--service-account-id | Yes | string The ID of the service account to update. |
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 |