Skip to main content
The admin command group provides advanced administrative operations for managing Cadence clusters, debugging workflows, and performing maintenance tasks.
Admin commands require elevated privileges and direct database access in some cases. Use with caution in production environments.

​
Command Overview

cadence admin [command] [subcommand] [flags]
Short alias: adm 
cadence adm workflow describe  # Same as: cadence admin workflow describe

​
Admin Workflow Commands

​
admin workflow show

Show workflow history directly from database. 
cadence admin workflow show \
  --db_type cassandra \
  --db_address 127.0.0.1 \
  --keyspace cadence \
  --shard_id 0 \
  --tree_id abc123 \
  --branch_id def456
​
--tree_id
string
required
TreeID for history tree
​
--branch_id
string
required
BranchID for history branch
​
--shard_id
int
required
Shard ID containing the workflow
​
--min_event_id
int
default:"1"
Minimum event ID to read
​
--max_event_id
int
default:"10000"
Maximum event ID to read

​
admin workflow describe

Show internal workflow execution information. 
cadence admin workflow describe -w workflow-id

# With run ID
cadence admin workflow describe -w workflow-id -r run-id
​
--workflow_id
string
required
Workflow ID
​
--run_id
string
Run ID (defaults to current)

​
admin workflow refresh-tasks

Refresh all tasks for a workflow. 
cadence admin workflow refresh-tasks -w workflow-id
Useful for recovering stuck workflows.

​
admin workflow delete

Delete workflow execution and mutable state from database. 
cadence admin workflow delete \
  --db_type cassandra \
  --db_address 127.0.0.1 \
  --keyspace cadence \
  -w workflow-id \
  -r run-id
This is a destructive operation that permanently deletes workflow data.
​
--skip_errors
bool
Continue on errors when deleting history
​
--remote
bool
Execute deletion on server side (recommended)

​
admin workflow fix_corruption

Check and clean up corrupted workflow records. 
cadence admin workflow fix_corruption \
  -w workflow-id \
  -r run-id
​
--skip_errors
bool
Skip errors and delete as much as possible

​
Shard Management Commands

​
admin shard describe

Describe shard information. 
cadence admin shard describe \
  --db_type cassandra \
  --db_address 127.0.0.1 \
  --keyspace cadence \
  --shard_id 0
​
--shard_id
int
required
Shard ID to describe

​
admin shard list

List shard distribution across history hosts. 
cadence admin shard list --pagesize 100
​
--pagesize
int
default:"100"
Number of results per page
​
--page_id
int
default:"0"
Page offset for pagination

​
admin shard closeShard

Close a shard to force rebalancing. 
cadence admin shard closeShard --shard_id 5

​
admin shard removeTask

Remove a specific task from a shard. 
cadence admin shard removeTask \
  --shard_id 0 \
  --task_id 12345 \
  --task_type 2
​
--task_type
int
required
Task type: 2 (transfer), 3 (timer), 4 (replication), 6 (cross-cluster)
​
--task_timestamp
int64
Task visibility timestamp (required for timer tasks)
​
--cluster
string
Target cluster (required for cross-cluster tasks)

​
admin shard timers

Get scheduled timers for a time range. 
cadence admin shard timers \
  --db_type cassandra \
  --db_address 127.0.0.1 \
  --keyspace cadence \
  --shard_id 0 \
  --start_date 2024-01-15T00:00:00Z \
  --end_date 2024-01-16T00:00:00Z
​
--start_date
string
required
Start date in RFC3339 format
​
--end_date
string
required
End date in RFC3339 format
​
--timer_type
int[]
Filter by timer types (0-6)
​
--print_json
bool
Print raw JSON instead of histogram

​
Domain Admin Commands

​
admin domain getdomainidorname

Get domain ID from name or name from ID. 
cadence admin domain getdomainidorname \
  --db_type cassandra \
  --db_address 127.0.0.1 \
  --keyspace cadence \
  --domain_id uuid-string

​
admin domain list

List all domains in cluster. 
cadence admin domain list --pagesize 20
​
--all
bool
List all domains regardless of status
​
--deprecated
bool
List only deprecated domains
​
--prefix
string
Filter by domain name prefix

​
ElasticSearch Admin Commands

​
admin elasticsearch catIndex

Show ElasticSearch indices. 
cadence admin elasticsearch catIndex --url http://localhost:9200

​
admin elasticsearch index

Index documents to ElasticSearch. 
cadence admin elasticsearch index \
  --url http://localhost:9200 \
  --index cadence-visibility-prod \
  --input_file messages.json \
  --batch_size 1000

​
admin elasticsearch delete

Delete documents from ElasticSearch. 
cadence admin elasticsearch delete \
  --url http://localhost:9200 \
  --index cadence-visibility-prod \
  --input_file workflows-to-delete.txt

​
Task List Admin Commands

​
admin tasklist describe

Show detailed task list information. 
cadence admin tasklist describe \
  --tasklist my-tasklist \
  --tasklisttype decision

​
admin tasklist list

List all active task lists in a domain. 
cadence admin tasklist list

​
admin tasklist update-partition

Update task list partition configuration. 
cadence admin tasklist update-partition \
  --tasklist high-throughput \
  --tasklisttype decision \
  --num_read_partitions 8 \
  --num_write_partitions 8
​
--num_read_partitions
int
required
Number of read partitions
​
--num_write_partitions
int
required
Number of write partitions
​
--force
bool
Force potentially unsafe update
Changing partitions on active task lists can cause temporary disruption.

​
Cluster Admin Commands

​
admin cluster describe

Show cluster information. 
cadence admin cluster describe

​
admin cluster add-search-attr

Whitelist a custom search attribute. 
cadence admin cluster add-search-attr \
  --search_attr_key CustomerId \
  --search_attr_type 1
​
--search_attr_key
string
required
Search attribute key name
​
--search_attr_type
int
required
Type: 0 (String), 1 (Keyword), 2 (Int), 3 (Double), 4 (Bool), 5 (Datetime)

​
DLQ (Dead Letter Queue) Commands

​
admin dlq count

Count DLQ messages. 
cadence admin dlq count --dlq_type history
​
--dlq_type
string
default:"history"
DLQ type: domain or history
​
--force
bool
Force fetch latest counts (additional DB load)

​
admin dlq read

Read DLQ messages. 
cadence admin dlq read \
  --shards 0,1,2 \
  --dlq_type history \
  --source_cluster source-cluster-name \
  --max_message_count 100
​
--shards
string
required
Comma-separated shard IDs or ranges (e.g., “2,5-6,10”)
​
--source_cluster
string
required
Source cluster name
​
--max_message_count
int
Maximum messages to read

​
admin dlq purge

Delete DLQ messages. 
cadence admin dlq purge \
  --shards 0,1,2 \
  --dlq_type history \
  --source_cluster source-cluster-name \
  --last_message_id 1000
Purging DLQ messages is irreversible. Ensure proper backups exist.

​
admin dlq merge

Merge DLQ messages back into main queue. 
cadence admin dlq merge \
  --shards 0,1,2 \
  --dlq_type history \
  --source_cluster source-cluster-name \
  --last_message_id 1000

​
Database Commands

​
admin database scan

Scan database for corrupted workflows. 
cadence admin database scan \
  --db_type cassandra \
  --db_address 127.0.0.1 \
  --keyspace cadence \
  --number_of_shards 16384 \
  --scan_type ConcreteExecutionType
​
--scan_type
string
required
Scan type: ConcreteExecutionType, CurrentExecutionType, etc.
​
--invariant_collection
string[]
Collections to check during scan

​
admin database clean

Clean up corrupted workflows found by scan. 
cadence admin database clean \
  --db_type cassandra \
  --db_address 127.0.0.1 \
  --keyspace cadence \
  --scan_type ConcreteExecutionType \
  --input_file corrupted-workflows.json

​
admin database decode_thrift

Decode Thrift-encoded data. 
cadence admin database decode_thrift \
  --input "hex_encoded_data" \
  --encoding hex
​
--encoding
string
default:"hex"
Input encoding: hex or base64

​
Dynamic Config Commands

​
admin config get

Get dynamic config value. 
cadence admin config get --name matching.numTasklistWritePartitions

# With filters
cadence admin config get \
  --name frontend.rps \
  --filter '{"domainName":"my-domain"}'

​
admin config update

Update dynamic config value. 
cadence admin config update \
  --name matching.numTasklistWritePartitions \
  --value '[{"Value":8,"Filters":[]}]'

​
admin config restore

Restore config to default value. 
cadence admin config restore --name matching.numTasklistWritePartitions

​
admin config list

List all configured dynamic config values. 
cadence admin config list

​
admin config listall

List all available dynamic config keys. 
cadence admin config listall --format json

​
Database Connection Flags

Many admin commands require database connection:
​
--db_type
string
Database type: cassandra, mysql, postgres
​
--db_address
string
Database host address
​
--db_port
int
Database port
​
--keyspace
string
Keyspace/database name
​
--username
string
Database username
​
--password
string
Database password

​
Best Practices

  1. Database Access: Use read-only credentials when possible
  2. Backups: Always backup before destructive operations
  3. Testing: Test admin commands in non-production first
  4. Monitoring: Watch metrics during and after admin operations
  5. Documentation: Document all admin operations performed
  6. Permissions: Restrict admin command access appropriately

​
Next Steps

Workflow Commands

Standard workflow operations

Domain Commands

Domain management

Operations Guide

Learn about Cadence operations

Disaster Recovery

Recovery and troubleshooting

Build docs developers (and LLMs) love

Get started for freeTalk to us