Skip to main content
The Cadence CLI can be installed using multiple methods depending on your platform and use case.

​
Prerequisites

Before installing the Cadence CLI, ensure you have:
  • Access to a running Cadence server
  • Network connectivity to the Cadence frontend service (typically port 7933)
  • (For building from source) Go 1.19 or later

​
Installation Methods

​
Homebrew (macOS and Linux)

The easiest way to install the Cadence CLI on macOS and Linux is through Homebrew: 
brew install cadence-workflow
Verify the installation: 
cadence --version

​
Docker

Run the CLI directly from a Docker container without installation: 
docker run --rm ubercadence/cli:master --help

​
Using Docker with Local Server

To connect to a Cadence server running on your host machine: 
docker run --rm --network=host ubercadence/cli:master \
  --address localhost:7933 \
  --domain samples-domain \
  workflow list

​
Docker Compose Integration

If you’re running Cadence via Docker Compose, add the CLI service:
docker-compose.yml
services:
  cadence:
    image: ubercadence/server:master
    ports:
      - "7933:7933"
    # ... other configuration

  cadence-cli:
    image: ubercadence/cli:master
    depends_on:
      - cadence
    environment:
      - CADENCE_CLI_ADDRESS=cadence:7933
    entrypoint: ["/bin/bash"]
    stdin_open: true
    tty: true
Then run CLI commands: 
docker compose run cadence-cli cadence --domain samples-domain workflow list

​
Building from Source

For the latest development version or custom builds:

​
Clone the Repository

git clone https://github.com/uber/cadence.git
cd cadence

​
Checkout a Specific Version

It’s recommended to use a tagged release: 
git checkout v0.21.3
To see available versions: 
git tag -l

​
Build the CLI

make tools
This produces an executable called cadence in the current directory.

​
Test the Build

./cadence --help

​
Install System-Wide (Optional)

Move the binary to a directory in your PATH: 
sudo mv cadence /usr/local/bin/
Verify: 
cadence --version

​
Configuration

​
Environment Variables

Set up default configuration to avoid repeating flags:
.bashrc or .zshrc
# Cadence server address
export CADENCE_CLI_ADDRESS=localhost:7933

# Default domain
export CADENCE_CLI_DOMAIN=my-domain

# RPC timeout (seconds)
export CADENCE_CONTEXT_TIMEOUT=120

# Transport protocol (tchannel or grpc)
export CADENCE_CLI_TRANSPORT_PROTOCOL=tchannel
Reload your shell configuration: 
source ~/.bashrc  # or source ~/.zshrc

​
TLS Configuration

For production environments with TLS enabled: 
export CADENCE_CLI_TLS_CERT_PATH=/path/to/cert.pem
export CADENCE_CLI_ADDRESS=cadence.example.com:7933

​
JWT Authentication

For authenticated environments: 
# Using JWT token
export CADENCE_CLI_JWT="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

# Or using private key
export CADENCE_CLI_JWT_PRIVATE_KEY=/path/to/private-key.pem

​
Verify Installation

Test your CLI installation by connecting to a Cadence server: 
cadence --address localhost:7933 cluster describe
Expected output: 
Cluster Information:
  Name: cadence-cluster
  ...

​
Common Connection Issues

Problem: connection refused error when connecting to Cadence.Solutions:
  • Verify Cadence server is running: docker ps or netstat -an | grep 7933
  • Check the address and port: --address localhost:7933
  • For Docker, use host networking: docker run --network=host
Problem: Domain does not exist error.Solution: Register the domain first:
cadence --domain my-domain domain register
Problem: TLS connection errors.Solutions:
  • Verify certificate path: --tls-cert-path /correct/path/to/cert.pem
  • Check certificate validity: openssl x509 -in cert.pem -text -noout
  • Ensure server uses same TLS version
Problem: RPC calls timing out.Solutions:
  • Increase timeout: --context-timeout 300
  • Check network connectivity to server
  • Verify server health and load

​
Upgrading

​
Homebrew

brew upgrade cadence-workflow

​
Docker

Pull the latest image: 
docker pull ubercadence/cli:master
Or use a specific version: 
docker pull ubercadence/cli:v0.21.3

​
From Source

cd cadence
git fetch --tags
git checkout v0.21.3
make tools

​
Compatibility

The CLI is designed to be backward compatible with older Cadence server versions. However:
  • CLI Version: Should match or be older than server version
  • Feature Parity: Server supports CLI feature version checks
  • Breaking Changes: Major version updates may require CLI updates
Check compatibility: 
cadence --version
Output includes:
  • CLI feature version: For compatibility checking
  • Release version: Actual CLI version
  • Build commit: Git commit hash

​
Next Steps

CLI Overview

Learn about CLI architecture and usage patterns

Workflow Commands

Start managing workflow executions

Domain Commands

Configure your first domain

Quick Start

Get started with Cadence

Build docs developers (and LLMs) love

Get started for freeTalk to us