Domain Commands

The domain command group provides operations for creating, configuring, and managing Cadence domains.

Command Overview

cadence domain [command] [flags]

Short alias: d

cadence d describe  # Same as: cadence domain describe

What is a Domain?

A domain is a logical namespace for workflow executions. Domains provide:

Isolation: Separate workflow executions and task lists
Multi-tenancy: Support multiple applications in one Cadence cluster
Configuration: Domain-level settings for retention, archival, and clusters
Security: Access control boundaries

Domain Registration

register

Create a new domain.

cadence domain register --domain my-domain

# Production domain with full configuration
cadence domain register \
  --domain production-workflows \
  --description "Production workflow domain" \
  --owner_email [email protected] \
  --retention 7 \
  --active_cluster cluster-west \
  --clusters cluster-west,cluster-east \
  --global_domain true

--domain

string

required

Domain name (must be unique)

--description

string

Domain description

--owner_email

string

Owner email for contact information

--retention

int

default:"3"

Workflow execution retention in days

--active_cluster

string

Active cluster name for global domains

--clusters

string

Comma-separated list of cluster names for replication

--global_domain

bool

default:"true"

Enable global domain (active-passive replication)

--history_archival_status

string

History archival status: Enabled or Disabled

--history_uri

string

URI for history archival storage

--visibility_archival_status

string

Visibility archival status: Enabled or Disabled

--visibility_uri

string

URI for visibility archival storage

--domain_data

key=value

Custom domain metadata as key-value pairs

Example: Register with Archival

cadence domain register \
  --domain archived-workflows \
  --retention 30 \
  --history_archival_status Enabled \
  --history_uri "s3://my-bucket/cadence-history" \
  --visibility_archival_status Enabled \
  --visibility_uri "s3://my-bucket/cadence-visibility"

Domain Updates

update

Modify an existing domain’s configuration.

cadence domain update --domain my-domain --retention 14

# Update multiple settings
cadence domain update \
  --domain my-domain \
  --description "Updated description" \
  --owner_email [email protected] \
  --retention 30

--domain

string

required

Domain name to update

--description

string

Update domain description

--owner_email

string

Update owner email

--retention

int

Update retention period in days

--active_cluster

string

Update active cluster

--add_bad_binary

string

Add bad binary checksum to blocklist

--remove_bad_binary

string

Remove binary checksum from blocklist

Example: Update Archival Settings

cadence domain update \
  --domain my-domain \
  --history_archival_status Enabled \
  --history_uri "s3://backup-bucket/history"

Domain Information

describe

Show detailed domain configuration.

cadence domain describe --domain my-domain

Example Output:

{
  "domainInfo": {
    "name": "my-domain",
    "status": "REGISTERED",
    "description": "Production workflows",
    "ownerEmail": "[email protected]",
    "data": {},
    "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  },
  "configuration": {
    "workflowExecutionRetentionPeriodInDays": 7,
    "historyArchivalStatus": "ENABLED",
    "historyArchivalURI": "s3://bucket/history",
    "visibilityArchivalStatus": "DISABLED",
    "badBinaries": {
      "binaries": {}
    }
  },
  "replicationConfiguration": {
    "activeClusterName": "cluster-west",
    "clusters": [
      {"clusterName": "cluster-west"},
      {"clusterName": "cluster-east"}
    ]
  }
}

--domain

string

required

Domain name to describe

Domain Lifecycle

deprecate

Mark a domain as deprecated (prevents new workflows).

cadence domain deprecate --domain old-domain

Deprecating a domain prevents starting new workflows but allows existing workflows to complete.

--domain

string

required

Domain name to deprecate

delete

Delete a domain (admin operation).

cadence domain delete --domain unused-domain

Domain deletion is a destructive operation. Ensure the domain has no active workflows and all data has been archived if needed.

--domain

string

required

Domain name to delete

Cross-Cluster Operations

failover

Failover a global domain to a different active cluster.

cadence domain failover \
  --domain my-domain \
  --active_cluster cluster-east

--domain

string

required

Global domain name

--active_cluster

string

required

Target cluster for failover

list-failover-history

Show domain failover history.

cadence domain list-failover-history --domain my-domain

Example Output:

Failover History:
  Time: 2024-01-15 10:30:00 UTC
  From: cluster-west
  To: cluster-east
  Reason: Planned maintenance

  Time: 2024-01-10 08:00:00 UTC
  From: cluster-east
  To: cluster-west
  Reason: End of maintenance window

migration

Validate domain migration settings (does not perform actual migration).

cadence domain migration \
  --domain source-domain \
  --destination_domain target-domain

This command only validates migration compatibility. Actual data migration must be performed separately.

--domain

string

required

Source domain name

--destination_domain

string

required

Target domain name

Common Usage Patterns

Development Domain

Simple local development domain:

cadence domain register \
  --domain dev-local \
  --retention 1 \
  --global_domain false

Multi-Region Production Domain

Global domain with replication:

cadence domain register \
  --domain prod-global \
  --description "Global production workflows" \
  --owner_email [email protected] \
  --retention 30 \
  --global_domain true \
  --active_cluster us-west-2 \
  --clusters us-west-2,us-east-1,eu-west-1

Enable Archival for Compliance

cadence domain update \
  --domain compliance-workflows \
  --retention 90 \
  --history_archival_status Enabled \
  --history_uri "s3://compliance-archive/history" \
  --visibility_archival_status Enabled \
  --visibility_uri "s3://compliance-archive/visibility"

Block Bad Binary

Prevent workflows from using a problematic deployment:

cadence domain update \
  --domain my-domain \
  --add_bad_binary abc123checksum \
  --reason "Deployment v1.2.3 causes workflow failures"

Unblock Binary

cadence domain update \
  --domain my-domain \
  --remove_bad_binary abc123checksum

Domain Data

Custom metadata can be attached to domains:

cadence domain register \
  --domain my-domain \
  --domain_data "team=platform,env=production,cost_center=eng-123"

Access domain data:

cadence domain describe --domain my-domain | grep data

Troubleshooting

Domain already exists

Error: Domain already registeredSolution: Use domain update instead or choose a different name:

cadence domain update --domain existing-domain --retention 14

Cannot create global domain

Error: Invalid cluster configurationSolution: Verify cluster names match server configuration:

cadence cluster describe

Failover fails

Error: Domain not replicated to target clusterSolution: Check replication status:

cadence domain describe --domain my-domain

Ensure target cluster is in the clusters list.

Archival not working

Problem: History not being archived despite enabled status.Checks:

Verify archival URI is valid and accessible
Check server archival configuration
Ensure retention period has passed
Review server logs for archival errors

Best Practices

Naming: Use descriptive domain names (e.g., payments-prod, orders-staging)
Retention: Set based on compliance and debugging needs (typically 7-30 days)
Archival: Enable for production domains requiring audit trails
Global Domains: Use for multi-region high availability
Owner Email: Set to team distribution list for production domains
Bad Binaries: Proactively block problematic deployments

Next Steps

Workflow Commands

Start managing workflows in your domain

Task List Commands

Monitor domain task lists

Admin Commands

Advanced domain administration

Domain Concepts

Learn more about domains

Overview

Commands

​Command Overview

​What is a Domain?

​Domain Registration

​register

​Example: Register with Archival

​Domain Updates

​update

​Example: Update Archival Settings

​Domain Information

​describe

​Domain Lifecycle

​deprecate

​delete

​Cross-Cluster Operations

​failover

​list-failover-history

​migration

​Common Usage Patterns

​Development Domain

​Multi-Region Production Domain

​Enable Archival for Compliance

​Block Bad Binary

​Unblock Binary

​Domain Data

​Troubleshooting

​Best Practices

​Next Steps

Workflow Commands

Task List Commands

Admin Commands

Domain Concepts

Build docs developers (and LLMs) love

Command Overview

What is a Domain?

Domain Registration

register

Example: Register with Archival

Domain Updates

update

Example: Update Archival Settings

Domain Information

describe

Domain Lifecycle

deprecate

delete

Cross-Cluster Operations

failover

list-failover-history

migration

Common Usage Patterns

Development Domain

Multi-Region Production Domain

Enable Archival for Compliance

Block Bad Binary

Unblock Binary

Domain Data

Troubleshooting

Best Practices

Next Steps