Skip to main content

Install and configure the CLI

The Temporal CLI is a command-line tool for interacting with the Temporal Service. It helps you manage, monitor, and debug Temporal applications.

Install the CLI​

The CLI is available for macOS, Linux, and Windows, or as a Docker image.

Install with Homebrew:

brew install temporal

Or download from the CDN:

extract the archive and add the temporal binary to your PATH.

Run a local development server​

The CLI includes a local Temporal development service for fast feedback while building your application.

Start the server:

temporal server start-dev

This command automatically starts the Web UI, creates the default Namespace, and uses an in-memory SQLite database.

The Temporal Server will be available on localhost:7233 and the Temporal Web UI will be available at http://localhost:8233.

Persist state locally by specifying a database file:

temporal server start-dev --db-filename temporal.db
note

Local databases created with --db-filename may not be compatible with newer versions of the Temporal CLI. The temporal server start-dev command is intended for development environments.

For the full list of development server options, use the --help flag:

temporal server start-dev --help

Development server configuration​

Namespace registration​

Namespaces are pre-registered at startup for immediate use. Customize pre-registered Namespaces with the following command:

temporal server start-dev --namespace foo --namespace bar

Register Namespaces with namespace create:

temporal operator namespace create --namespace foo

Enable or turn off the Temporal Web UI​

By default, the Temporal Web UI is enabled when running the development server using the Temporal CLI. To turn off the UI, use the --headless modifier:

temporal server start-dev --headless

Dynamic configuration​

Advanced Temporal CLI configuration requires a dynamic configuration file.

To set values on the command line, use --dynamic-config-value KEY=JSON_VALUE. For example, enable the Search Attribute cache:

temporal server start-dev --dynamic-config-value system.forceSearchAttributesCacheRefreshOnRead=false

This setting makes created Search Attributes immediately available.

Configure the CLI​

Environment variables​

The following table describes the environment variables you can set for the Temporal CLI.

VariableDefinitionClient Option
TEMPORAL_ADDRESSHost and port (formatted as host:port) for the Temporal Frontend Service.--address
TEMPORAL_CODEC_AUTHAuthorization header for requests to Codec Server.--codec-auth
TEMPORAL_CODEC_ENDPOINTEndpoint for remote Codec Server.--codec-endpoint
TEMPORAL_NAMESPACENamespace in Temporal Workflow. Default: "default".--namespace
TEMPORAL_TLS_CAPath to server CA certificate.--tls-ca-path
TEMPORAL_TLS_CERTPath to x509 certificate.--tls-cert-path
TEMPORAL_TLS_DISABLE_HOST_VERIFICATIONTurns off TLS host name verification. Default: false.--tls-disable-host-verification
TEMPORAL_TLS_KEYPath to private certificate key.--tls-key-path
TEMPORAL_TLS_SERVER_NAMEOverride for target TLS server name.--tls-server-name
TEMPORAL_API_KEYAPI key used for authentication.--api-key
ENVIRONMENT VARIABLES

Do not confuse environment variables, set with your shell, with temporal env options.

Create and modify configuration files​

The Temporal CLI lets you create and modify TOML configuration files to store your environment variables and other settings. Refer to Environment Configuration for more information.

Configure proxy support​

The Temporal CLI provides support for users who are operating behind a proxy. This feature ensures seamless communication even in network-restricted environments.

Setting up proxy support​

If you are behind a proxy, you'll need to instruct the Temporal CLI to route its requests via that proxy. You can achieve this by setting the HTTPS_PROXY environment variable.

export HTTPS_PROXY=<host>:<port>

Replace <host> with the proxy's hostname or IP address, and <port> with the proxy's port number.

Once set, you can run the Temporal CLI commands as you normally would.

note

Temporal CLI uses the gRPC library which natively supports HTTP CONNECT proxies. The gRPC library checks for the HTTPS_PROXY (and its case-insensitive variants) environment variable to determine if it should route requests through a proxy.

In addition to HTTPS_PROXY, gRPC also respects the NO_PROXY environment variable. This can be useful if there are specific addresses or domains you wish to exclude from proxying.

For more information, see Proxy in the gRPC documentation.

Enable auto-completion​

Enable auto-completion using the following commands.

zsh auto-completion​

  1. Add the following line to your ~/.zshrc startup script:

    eval "$(temporal completion zsh)"

  2. Re-launch your shell or run:

    source ~/.zshrc

Bash auto-completion​

  1. Install bash-completion and add the software to your ~/.bashrc.

  2. Add the following line to your ~/.bashrc startup script:

    eval "$(temporal completion bash)"

  3. Re-launch your shell or run:

    source ~/.bashrc
note

If auto-completion fails with the error: bash: _get_comp_words_by_ref: command not found, you did not successfully install bash-completion. This package must be loaded into your shell for temporal auto-completion to work.

Fish auto-completion​

  1. Create the Fish custom completions directory if it does not already exist:

    mkdir -p ~/.config/fish/completions

  2. Configure the completions to load when needed. Note: the filename must be temporal.fish or the completions will not be found:

    echo 'eval "$(temporal completion fish)"' >~/.config/fish/completions/temporal.fish

  3. Re-launch your shell or run:

    source ~/.config/fish/completions/temporal.fish

Getting CLI help​

From the command line:

temporal <command> <subcommand> --help

For example:

  • temporal --help
  • temporal workflow --help
  • temporal workflow delete --help

For a full list of commands, see the Temporal CLI command reference.