Temporal CLI

⚠️ Temporal CLI's API is still subject to change. ⚠️

Use the CLI to run a Temporal Server and interact with it.

• 📦 Install
  • cURL
  • Homebrew
  • Manual
• 🚀 Use
  • Start the Server
  • Interact with the Server
• ⚙️ Configure
  • Namespace registration
  • Persistence modes
  • Enable or disable Temporal UI
  • Dynamic configuration
  • Environment variables
• ⌨️ Auto-completion
  • zsh auto-completion
  • Bash auto-completion
    • macOS installation
    • Linux installation
• 🔧 Development
  • Compile and run CLI
  • Compile docs
  • Run tests
• ⚠️ Known Issues

📦 Install

You can install the CLI using one of the below methods.

cURL

curl -sSf https://temporal.download/cli.sh | sh

Homebrew

brew install temporal

Manual

1. Download the version for your OS and architecture:
   • Linux amd64
   • Linux arm64
   • macOS amd64
   • macOS arm64 (Apple silicon)
   • Windows amd64
   • Windows arm64
2. Extract the downloaded archive.
3. Add the temporal binary to your PATH. (temporal.exe for Windows)

You can also download older versions from GitHub releases.

🚀 Use

Start the Server

temporal server start-dev

This:

• Starts the Server on localhost:7233
• Runs the Web UI at http://localhost:8233
• Creates a default Namespace

You can create other namespaces, have the Server persist data to a file so you don't lose your Workflows between sessions, and make other customizations via command-line options. For a full list of options, run:

temporal server start-dev --help

Interact with the Server

You can also run commands to interact with the Server in a separate terminal:

temporal workflow list
temporal operator namespace list

For a full list of commands, see the CLI docs or run temporal help.

⚙️ Configure

Use the help flag to see a full list of CLI options:

temporal -h
temporal server start-dev -h

Configure the environment with env commands:

temporal env set [environment options]

Namespace registration

Namespaces are pre-registered at startup so they're available to use right away. To customize the pre-registered namespaces, start the server with:

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

You can also register Namespaces with the following command:

temporal operator namespace create foo

Persistence modes

By default, temporal server start-dev runs in an in-memory mode.

To persist the state to a file on disk, use --db-filename:

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

Enable or disable Temporal UI

By default, the Temporal UI is started with Temporal CLI. The UI can be disabled via a runtime flag:

temporal server start-dev --headless

To build without static UI assets, use the headless build tag when running go build.

Dynamic configuration

Advanced configuration of the Temporal CLI requires the use of a dynamic configuration file. This file is created outside of the Temporal CLI; it is usually located with the service's config files.

Dynamic configuration values can also be set via --dynamic-config-value KEY=JSON_VALUE. For example, to disable the search attribute cache, run:

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

This setting makes created search attributes immediately available for use.

Environment variables

See the CLI docs for a list of env vars.

⌨️ Auto-completion

The Temporal CLI has the capability to auto-complete commands.

Running temporal completion SHELL will output completion setup code for the given shell.

zsh auto-completion

Add the following code snippet to your ~/.zshrc file:

source <(temporal completion zsh)

If you're running auto-completion from the terminal, run the command below:

echo 'source <(temporal completion zsh)' >> ~/.zshrc

After editing the file, run:

source ~/.zshrc.

Bash auto-completion

Bash auto-completion relies on bash-completion.

Install the software with the steps provided here, or use your preferred package manager on your operating system.

macOS installation

Install bash-completion through Homebrew: brew install bash-completion@2

Follow the instruction printed in the "Caveats" section, which will say to add one of the following lines to your ~/.bashrc file:

[[ -r "/opt/homebrew/etc/profile.d/bash_completion.sh" ]] && . "/opt/homebrew/etc/profile.d/bash_completion.sh"

or:

[[ -r "/usr/local/etc/profile.d/bash_completion.sh" ]] && . "/usr/local/etc/profile.d/bash_completion.sh"

Verify that bash-completion is installed by running type _init_completion. It should say _init_completion is a function and print the function.

Enable completion for Temporal by adding the following code to your bash file:

source <(temporal completion bash)

In an existing terminal, you can do that by running:

echo 'source <(temporal completion bash)' >> ~/.bashrc
source ~/.bashrc

Now test by typing temporal, space, and then tab twice. You should see:

$ temporal
activity    completion  h           operator    server      workflow
batch       env         help        schedule    task-queue

Linux installation

Use any of the following package managers to install bash-completion: apt install bash-completion pacman -S bash-completion yum install bash-completion

Verify that bash-completion is installed by running type _init_completion.

To install the software on Alpine Linux, run:

apk update
apk add bash-completion
source /etc/profile.d/bash_completion.sh

Finally, enable completion for Temporal by adding the following code to your bash file:

echo 'source <(temporal completion bash)' >> ~/.bashrc
source ~/.bashrc

🔧 Development

Compile and run CLI

go build -o dist/temporal ./cmd/temporal
dist/temporal

Compile docs

go build -o dist/temporal-docgen ./cmd/temporal-docgen

Run tests

go test ./...

⚠️ Known Issues

• When consuming Temporal as a library in go mod, you may want to replace grpc-gateway with a fork to address URL escaping issue in UI. See temporalio/temporalite#118

• When running the executables from the Releases page in macOS you will need to click "Allow Anyway" in Security & Privacy settings: