tctl activity fail command
The tctl activity fail command fails an Activity Execution. Syntax: tctl activity fail [<modifiers>]
cli
564 notes in this subject, read out of this brain and free to use. This is page 8 of 10.
tctl activity fail --workflow_id modifier
The --workflow_id modifier (alias: -w) specifies the Workflow Id of an Activity Execution to fail. Example: tctl activity fail --workflow_id <id>
tctl activity fail --run_id modifier
The --run_id modifier (alias: -r) specifies the Run Id of an Activity Execution to fail. Example: tctl activity fail --run_id <id>
tctl activity fail --activity_id modifier
The --activity_id modifier specifies the Activity Id of an Activity Execution to fail. Example: tctl activity fail --activity_id <id>
tctl activity fail --reason modifier
The --reason modifier specifies the reason for failing an Activity Execution. Example: tctl activity fail --reason <value>
tctl activity fail --detail modifier
The --detail modifier specifies details of the reason for failing an Activity Execution. Example: tctl activity fail --detail <value>
tctl activity fail --identity modifier
The --identity modifier specifies the identity of the operator when using tctl to fail an Activity Execution. Example: tctl activity fail --identity <value>
tctl batch command overview
The tctl batch command enables you to affect multiple existing Workflow Executions with a single command. A batch job runs in the background and affects Workflow Executions one at a time. There are three types of batch jobs: Signal (send a signal to workflow executions), Cancel (cancel workflow executions), and Terminate (terminate workflow executions). When starting a batch job, you must provide a List Filter and the type of batch job. The tctl batch start command shows how many Workflow Executions will be affected and asks for confirmation before proceeding. A successfully started batch job returns a Job ID.
tctl batch start command syntax and modifiers
The tctl batch start command syntax is: tctl batch start --query <value> <modifiers>. Modifiers include: --query (required, SQL-like query of Search Attributes, alias -q), --reason (optional, reason for batch job), --batch_type (specify operation: signal, cancel, or terminate), --signal_name (required when batch_type is signal), --input (pass signal input in JSON format, alias -i), --rps (specify RPS of processing, default 50), --yes (disable confirmation prompt, alias y).
tctl batch list command
The tctl batch list command lists all batch jobs. Syntax: tctl batch list <modifiers>. The --pagesize modifier specifies the maximum number of batch jobs to list on a page, with default value 30.
tctl batch describe command
The tctl batch describe command describes the progress of a batch job. Syntax: tctl batch describe --job_id <id>. The --job_id modifier is required and specifies the job ID of the batch job.
tctl batch terminate command
The tctl batch terminate command terminates a batch job. Syntax: tctl batch terminate --job_id <id> <modifiers>. Modifiers include: --job_id (required, the job ID of the batch job), --reason (optional, reason for terminating the batch job). Terminating a batch job does not roll back the operations already performed by the batch job.
tctl cluster get-search-attributes lists search attributes
The `tctl cluster get-search-attributes` command lists all Search Attributes that can be used in the `--query` modifier of the `tctl workflow list` command and the `--search_attr_key` and `--search_attr_value` modifiers of the `tctl workflow run` and `tctl workflow start` commands. The command has no modifiers.
tctl cluster health checks Frontend Service
The `tctl cluster health` command checks the health of the Frontend Service. The command has no modifiers.
Example tctl cluster get-search-attributes output
When run without arguments, `tctl cluster get-search-attributes` returns a table of search attributes including BinaryChecksums (Keyword), CloseTime (Int), CustomBoolField (Bool), CustomDatetimeField (Datetime), CustomDoubleField (Double), CustomIntField (Int), CustomKeywordField (Keyword), CustomNamespace (Keyword), CustomStringField (String), ExecutionStatus (Int), ExecutionTime (Int), Operator (Keyword), RunId (Keyword), StartTime (Int), TaskQueue (Keyword), TemporalChangeVersion (Keyword), WorkflowId (Keyword), and WorkflowType (Keyword).
tctl admin cluster add-search-attributes command
The tctl admin cluster add-search-attributes command adds custom Search Attributes to a Cluster. Usage: tctl admin cluster add-search-attributes --name <SearchAttributeName> --type <SearchAttributeValueType>. Modifiers: --name (required, case-sensitive), --type (values: Text, Keyword, Int, Double, Bool, Datetime), --skip_schema_update (skips Elasticsearch index schema update, registers only in metadata). Due to Elasticsearch limitations, existing Search Attributes cannot be renamed or removed. If adding to a cluster running docker-compose-es.yml, increase Docker memory to more than 6 GB.
tctl admin cluster remove-search-attributes command
The tctl admin cluster remove-search-attributes command removes custom Search Attribute metadata from a Cluster. Usage: tctl admin cluster remove-search-attributes --name <SearchAttributeKey>. Only custom Search Attributes can be removed; default Search Attributes cannot be removed. Removing a Search Attribute removes it from the Cluster's metadata but does not remove it from the Elasticsearch index. Once a Search Attribute is added to the Elasticsearch index, it cannot be changed but can be added back later as the same type.
tctl admin cluster get_search_attributes command
The tctl admin cluster get_search_attributes command retrieves existing Search Attributes for a given Cluster. Modifier: --print_json (prints results in JSON format).
tctl admin cluster describe command
The tctl admin cluster describe command provides information for the current Cluster. Modifier: --cluster_value (optional, specifies the name of the remote Cluster within the current Cluster; defaults to current Cluster information).
tctl admin cluster list command
The tctl admin cluster list command lists Cluster information on the given Cluster. Modifier: --pagesize (the size of the page that the list is printed on; default: 100).
tctl admin cluster upsert_remote_cluster command
The tctl admin cluster upsert_remote_cluster command adds or updates remote Cluster information in the current Cluster. Modifiers: --frontend_address (the remote Cluster frontend address), --enable_connection (enables remote Cluster connection).
tctl admin cluster remove_remote_cluster command
The tctl admin cluster remove_remote_cluster command removes remote Cluster information on the given Cluster. Modifier: --cluster (the name of the remote Cluster to remove).
tctl admin db clean command modifiers
The tctl admin db clean command cleans corrupted Workflow Executions from the targeted database. Modifiers: --db_engine (type of DB engine: cassandra, mysql, postgres; default: cassandra), --db_address (persistence address; default: 127.0.0.1), --db_port (persistence port; default: 9042), --username (database username), --password (database password), --keyspace (database keyspace; default: temporal), --input_directory (directory containing corrupted Workflow Execution files from scan), --lower_shard_bound (minimum inclusive corrupt shards; default: 0), --upper_shard_bound (maximum exclusive corrupt shards; default: 16384), --starting_rps (starting rps of database queries; default: 100), --rps (target rps of database queries; default: 7000), --concurrency (number of threads to handle scan; default: 1000), --report_rate (shards handled between progress reports; default: 10), --tls (enable TLS; required before using TLS modifiers), --tls_cert_path (TLS client cert location), --tls_key_path (TLS key location), --tls_ca_path (TLS CA location), --tls_server_name (DB TLS server name), --tls_disable_host_verification (disable DB TLS hostname and server cert verification).
tctl admin decode proto command
The tctl admin decode proto command decodes Payloads to proto format. Modifiers: --type (full name of the proto type to decode to), --hex_data (decode data to hex format), --hex_file (create file with decoded hex data), --binary_file (create file with decoded binary data).
tctl admin decode base64 command
The tctl admin decode base64 command decodes base64 Payloads. Modifiers: --base64_data (decoded data in base64 format), --base64_file (create file with data in base64 format).
tctl admin dlq read command
The tctl admin dlq read command reads messages from the dead-letter queue (DLQ). Modifiers: --dlq_type (type of DLQ: namespace, history), --cluster (source cluster for DLQ), --shard_id (ShardId provided for command), --max_message_count (maximum number of messages to fetch; default: 0), --last_message_id (identifies last read message; default: 0), --output_filename (file to write output to; default is stdout).
tctl admin dlq purge command
The tctl admin dlq purge command deletes DLQ messages that have a Task Id equal to or less than the provided Task Id. Modifiers: --dlq_type (type of DLQ: namespace, history), --cluster (source cluster for DLQ), --shard_id (ShardId provided for command), --last_message_id (identifies last read message; default: 0).
tctl admin dlq merge command
The tctl admin dlq merge command merges dead-letter queue (DLQ) messages. Messages must have TaskIds with an equal or lesser value than the given TaskId. Modifiers: --dlq_type (type of DLQ: namespace, history), --cluster (source cluster for DLQ), --shard_id (ShardId provided for command), --last_message_id (identifies last read message; default: 0).
tctl admin history_host describe command
The tctl admin history_host describe command describes internal information of a history host. Modifiers: --workflow_id/-w (WorkflowId of Workflow whose history host is to be described), --history_address (history address of the history host), --shard_id (Id of shard belonging to history host), --print_full (print full and detailed summary).
tctl admin history_host get_shardid command
The tctl admin history_host get_shardid command gets the shardId for a given namespaceId and workflowId. Modifiers: --namespace_id (namespaceId of history host), --workflow_id/-w (WorkflowId of history host), --number_of_shards (total amount of shards for Temporal Cluster; default: 0).
tctl admin membership list_gossip command
The tctl admin membership list_gossip command lists the ringpop membership items on the targeted membership. Modifier: --role (filters results by membership role: all, frontend, history, matching, worker; default: all).
tctl admin membership list_db command
The tctl admin membership list_db command lists Cluster items in a targeted membership. Modifiers: --heartbeated_within (filters list by last Heartbeat time), --role (filters results by membership role: all, frontend, history, matching, worker; default: all).
tctl admin shard describe command
The tctl admin shard describe command shows the Id for a specified shard. Modifier: --shard_id (the Id of the shard to describe; default: 0).
tctl admin shard describe_task command modifiers
The tctl admin shard describe_task command describes a specified Task's Task Id, Task type, shard Id, and task visibility timestamp. Modifiers: --db_engine (cassandra, mysql, postgres; default: cassandra), --db_address (persistence address; default: 127.0.0.1), --db_port (persistence port; default: 9042), --username (database username), --password (database password), --keyspace (keyspace; default: temporal), --tls (enable TLS; required before other TLS modifiers), --tls_cert_path (DB TLS client cert path), --tls_server_name (DB TLS server name), --tls_disable_host_verification (DB TLS verify hostname and server cert), --shard_id (identifies specified shard; default: 0), --task_id (describes task; default: 0), --task_type (transfer, timer, replication; default: transfer), --task_timestamp (task visibility timestamp in nanoseconds; default: 0), --target_cluster (Temporal cluster; default: active).
tctl admin shard list_tasks command modifiers
The tctl admin shard list_tasks command lists Tasks available for a given shard Id and Task type. Modifiers: --more (lists more pages; default lists one page of 10), --pagesize (result page size; default: 10), --target_cluster (Temporal cluster; default: active), --shard_id (ID of shard; default: 0), --task_type (transfer, timer, replication, visibility; default: transfer), --min_visibility_ts (minimum Task Visibility timestamp; supported formats: 2006-01-02T15:04:05+07:00, Raw UnixNano, Time range N-duration where 0<N<1000000 and duration: second/s, minute/m, week/w, month/m, year/y), --max_visibility_ts (maximum Task Visibility timestamp; same formats as min_visibility_ts).
tctl admin shard remove_task command modifiers
The tctl admin shard remove_task command removes a Task from a shard. The Task removed must have values matching those given in the command line. Modifiers: --shard_id (shardId for Task to be removed; default: 0), --task_id (taskId for Task to be removed; default: 0), --task_type (transfer, timer, replication; default: transfer), --task_timestamp (task visibility timestamp in nanoseconds; default: 0).
tctl admin shard close_shard command
The tctl admin shard close_shard command closes a shard with an Id corresponding to the value given in the command. Modifier: --shard_id (ShardId managed by Temporal Cluster).
tctl admin workflow describe command
The tctl admin workflow describe command describes internal information of a Workflow Execution. Modifiers: --workflow_id/-w (Id of the Workflow), --run_id/-r (Id of the run).
tctl admin workflow refresh_tasks command
The tctl admin workflow refresh_tasks command updates all Tasks in a Workflow, provided the command can fetch new information for Tasks. Modifiers: --workflow_id/-w (Id of the Workflow), --run_id/-r (Id of the run).
tctl admin workflow show command modifiers
The tctl admin workflow show command displays Event history from the database. Modifiers: --workflow_id/-w (current Workflow), --run_id/-r (current RunId), --min_event_id (minimum Event Id to include in history; default: 0), --max_event_id (maximum Event Id to include in history; default: 0), --min_event_version (start Event version to include in history; default: 0), --max_event_version (end Event version to include in history; default: 0), --output_filename (file where output is sent).
tctl admin workflow delete command modifiers
The tctl admin workflow delete command deletes the current Workflow Execution and the mutableState record. Modifiers: --db_engine (cassandra, mysql, postgres; default: cassandra), --db_address (persistence address; default: 127.0.0.1), --db_port (persistence port; default: 9042), --username (database username), --password (database password), --keyspace (database keyspace; default: temporal), --url (URL of Elasticsearch cluster; default: http://127.0.0.1:9200), --es-username (Elasticsearch username), --es-password (Elasticsearch password), --version (Elasticsearch version: v6, v7; default: v7), --index (Elasticsearch index name), --workflow_id/-w (Id of Workflow), --run_id/-r (Id of run), --skip_errors (skip errors during Workflow Execution), --tls (enable TLS; required before TLS modifiers), --tls_cert_path (DB TLS client cert path), --tls_key_path (DB TLS client key path), --tls_ca_path (DB TLS client CA path), --tls_server_name (DB TLS server name), --tls_disable_host_verification (DB TLS verify hostname and server cert).
Run tctl with Docker Compose
tctl can be run locally together with Temporal Server in Docker Compose using: docker exec temporal-admin-tools tctl YOUR COMMANDS HERE. To invoke tctl as though it is installed locally, set an alias: alias tctl="docker exec temporal-admin-tools tctl"
tctl is a command-line tool for Temporal Cluster interaction
The Temporal CLI (tctl) is a command-line tool used to interact with a Temporal Cluster. It can perform Namespace operations (register, update, describe) and Workflow operations (start Workflow, show Event History, Signal Workflow).
tctl command categories
tctl supports the following command categories: activity, admin, batch, cluster, dataconverter, namespace, taskqueue, and workflow.
Install tctl via Homebrew
tctl can be installed locally using Homebrew with the command: brew install tctl
Run tctl with temporal-admin-tools Docker image on Linux
On Linux, run the temporal-admin-tools Docker image with: docker run --rm -it --entrypoint tctl --network host --env TEMPORAL_CLI_ADDRESS=localhost:7233 temporalio/admin-tools:1.14.0
Run tctl with temporal-admin-tools Docker image on macOS or Windows
On macOS or Windows, run the temporal-admin-tools Docker image with: docker run --rm -it --entrypoint tctl --env TEMPORAL_CLI_ADDRESS=host.docker.internal:7233 temporalio/admin-tools:1.14.0
Install tctl via Go
tctl can be installed using Go by running: go install github.com/temporalio/tctl/cmd/tctl@latest
tctl help commands
Help for tctl is available via: tctl -h (top-level commands and global options), tctl namespace -h (Namespace operations), tctl workflow -h (Workflow operations), and tctl taskqueue -h (Task Queue operations).
tctl --address global modifier
The --address modifier specifies a host and port for the Frontend Service. The default is 127.0.0.1:7233.
tctl --auto_confirm global modifier
The --auto_confirm global modifier automatically confirms all prompts.
tctl --context_timeout global modifier
The --context_timeout modifier specifies a timeout for the context of an RPC call in seconds. The default value is 5.
tctl --data_converter_plugin global modifier
The --data_converter_plugin modifier specifies the name of the executable for a custom Data Converter plugin.
tctl --headers_provider_plugin global modifier
The --headers_provider_plugin modifier specifies the name of the executable for a headers provider plugin.
tctl --namespace global modifier
The --namespace modifier (alias --n) specifies a Namespace. By using this modifier, you don't need to specify a --namespace modifier for a sub-command. The default Namespace is 'default'.
tctl --tls_ca_path global modifier
The --tls_ca_path modifier specifies the path to a server Certificate Authority (CA) certificate file.
tctl --tls_disable_host_verification global modifier
The --tls_disable_host_verification modifier disables verification of the server certificate and thus host verification.
tctl --tls_key_path global modifier
The --tls_key_path modifier specifies the path to a private key file for mutual TLS authentication. If you use this modifier, you must also use the --tls_cert_path modifier.
tctl --tls_server_name global modifier
The --tls_server_name modifier specifies an override for the name of the target server that is used for TLS host verification. The name must be one of the DNS names listed in the server TLS certificate. Specifying this modifier also enables host verification.
tctl --codec_endpoint global modifier
The --codec_endpoint modifier specifies the URL and port number for a Codec Server.