No history yet

Temporal CLI Basics

Meet the Temporal CLI

While the Web UI is great for a visual overview, many developers prefer working in the terminal. The Temporal Command Line Interface, or CLI, is a tool that lets you interact with your Temporal Cluster directly from your command line. It's fast, scriptable, and gives you powerful control over your workflows and other resources.

Installation

Installing the temporal CLI is straightforward. If you're on macOS or Linux, the easiest way is with the package manager Homebrew.

brew install temporal

For Windows users or those who prefer not to use Homebrew, you can download the binary directly from the official Temporal releases page on GitHub.

Once installed, you can verify that everything is working by checking the version.

temporal version

# Example Output:
# temporal version 1.22.2

Configuration

Before you can use the CLI, you need to tell it where your Temporal Cluster is running. The most common way to do this is by setting an environment variable. For a locally running Temporal service, the default address is 127.0.0.1:7233.

# Tell the CLI where to find the Temporal service
export TEMPORAL_CLI_ADDRESS=127.0.0.1:7233

You can add this line to your shell's startup file (like .bashrc, .zshrc, or your PowerShell profile) so it's set automatically in every new terminal session. While you can also specify the address with a flag for every command (--address 127.0.0.1:7233), using the environment variable is much more convenient.

Core Commands

Temporal CLI commands follow a simple temporal <noun> <verb> pattern. The noun is the thing you want to interact with (like workflow or cluster), and the verb is the action you want to take (like list or describe).

Let's start by checking the health and details of our cluster.

# Get information about the cluster the CLI is connected to
temporal cluster describe

This command returns details like the cluster ID, server version, and persistence store. It's a great way to confirm you're connected to the right place.

The most common noun you'll interact with is workflow. You can list running workflows, view their history, and even start new ones.

Lesson image

Here are a few essential workflow commands. To use them, you'll need to specify a namespace using the --namespace flag (or -n). We'll use the default namespace for now.

# List all workflows in the 'default' namespace
temporal workflow list -n default

# Get detailed information for a specific workflow
temporal workflow describe -n default --workflow-id <your-workflow-id>

# Start a new workflow execution
temporal workflow start -n default --type <WorkflowType> --task-queue <your-task-queue> --workflow-id <your-workflow-id>

The --workflow-id is a unique business-level identifier for a workflow execution. You define this when you start a workflow.

These are just a few examples. The CLI also has commands for managing namespaces, task queues, and schedules. You can explore all the available nouns and verbs by running temporal --help.

Ready to test your knowledge?

Quiz Questions 1/5

What is the recommended way to install the temporal CLI on macOS or Linux?

Quiz Questions 2/5

What is the most convenient way to configure the CLI with your Temporal Cluster's address for all future terminal sessions?

Now you have the tools to install, configure, and run basic commands with the Temporal CLI, opening up a faster way to manage your applications.