ManagerIdentity controls exclusive deployment modifications
ManagerIdentity is an optional field on a Worker Deployment that specifies the identity of the user with exclusive right to make changes to the Deployment. When ManagerIdentity is set, users whose identity does not match the ManagerIdentity will not be able to change the Deployment. This is especially useful in environments where multiple users (such as CLI users and automated controllers) may interact with the same Worker Deployment, allowing different users to communicate about who is expected to make changes.
versioning commit-build-id command deprecated
The temporal task-queue versioning commit-build-id command is deprecated by Worker Deployment. It completes a Build ID's rollout and cleans up unnecessary rules created during gradual rollout. It atomically: adds an unconditional assignment rule for the target Build ID at end of list, removes all previously added assignment rules to the given target Build ID, removes any unconditional assignment rules for other Build IDs. Rejects requests when there have been no recent pollers for this Build ID to prevent committing invalid IDs (use --force to override). Required flags: --task-queue (string), --build-id (string). Optional flags: --force (bool), --yes/-y (bool).
versioning delete-assignment-rule command deprecated
The temporal task-queue versioning delete-assignment-rule command is deprecated by Worker Deployment. It deletes a rule identified by its index in the Task Queue's list of assignment rules. By default, Task Queue must retain one unconditional rule (no hint filter or percentage); use --force to override. Required flags: --task-queue (string), --rule-index/-i (int). Optional flags: --force (bool), --yes/-y (bool).
versioning get-rules command deprecated
The temporal task-queue versioning get-rules command is deprecated by Worker Deployment. It retrieves all Worker Build ID assignments and redirect rules associated with a Task Queue. Task Queues support Assignment Rules (ordered list managing how new executions are assigned to specific Worker Build IDs, allowing gradual rollout via ramp percentage) and Redirect Rules (automatically assign work from source Build ID to target Build ID, maximum one per source Build ID, require full compatibility). Required flag: --task-queue (string).
versioning insert-assignment-rule command deprecated
The temporal task-queue versioning insert-assignment-rule command is deprecated by Worker Deployment. It inserts a new assignment rule for a Task Queue. Rules are evaluated in order starting from index 0; first applicable rule is applied. If no --rule-index is specified, inserts at index 0. Required flags: --task-queue (string), --build-id (string). Optional flags: --rule-index/-i (int, ranges 0 to count, any number greater than count is treated as append), --percentage (int, traffic percent to send to target Build ID), --yes/-y (bool).
versioning replace-assignment-rule command deprecated
The temporal task-queue versioning replace-assignment-rule command is deprecated by Worker Deployment. It changes an assignment rule for a Task Queue. By default enforces one unconditional rule (no hint filter or percentage); use --force to bypass validation. Can update percent between 0 and 100 (default). To assign multiple rules to single Build ID, use insert-assignment-rule. Required flags: --task-queue (string), --rule-index/-i (int), --build-id (string). Optional flags: --percentage (int), --force (bool), --yes/-y (bool).
versioning replace-redirect-rule command deprecated
The temporal task-queue versioning replace-redirect-rule command is deprecated by Worker Deployment. It updates a Build ID's redirect rule on a Task Queue by replacing its target Build ID. Required flags: --task-queue (string), --source-build-id (string), --target-build-id (string). Optional flag: --yes/-y (bool).
CLI global flags
Global flags for all task-queue subcommands: --address (string, Temporal Service gRPC endpoint, default: localhost:7233), --api-key (string, API key for request), --client-authority (string, Temporal gRPC client :authority pseudoheader), --client-connect-timeout (duration, client connection timeout, 0s means no timeout), --codec-auth (string, authorization header for Codec Server requests), --codec-endpoint (string, remote Codec Server endpoint), --codec-header (string[], HTTP headers for codec server as KEY=VALUE pairs, repeatable), --color (string-enum: always, never, auto; default: auto), --command-timeout (duration, command execution timeout, 0s means no timeout), --config-file (string, TOML config file path, defaults to $CONFIG_PATH/temporalio/temporal.toml), --disable-config-env (bool, disable loading environment config from environment variables), --disable-config-file (bool, disable loading environment config from config file), --env (string, active environment name, default: default), --env-file (string, path to environment settings file, defaults to $HOME/.config/temporalio/temporal.yaml), --grpc-meta (string[], HTTP headers as KEY=VALUE pairs, repeatable, also available via TEMPORAL_GRPC_META_[name] environment variable), --identity (string, identity of user/client submitting request, defaults to temporal-cli:$USER@$HOST), --log-format (string-enum: text, json; default: text), --log-level (string-enum: debug, info, warn, error, never; default: never for most commands, warn for server start-dev), --namespace/-n (string, Temporal Service Namespace, default: default), --no-json-shorthand-payloads (bool, raw payload output even if JSON option used), --output/-o (string-enum: text, json, jsonl, none; default: text), --profile (string, profile to use for config file), --time-format (string-enum: relative, iso, raw; default: relative), --tls (bool, enable base TLS encryption, defaulted to true if api-key or other TLS options present, use --tls=false to explicitly disable), --tls-ca-data (string, server CA certificate data, cannot be used with --tls-ca-path), --tls-ca-path (string, path to server CA certificate, cannot be used with --tls-ca-data), --tls-cert-data (string, x509 certificate data, cannot be used with --tls-cert-path), --tls-cert-path (string, path to x509 certificate, cannot be used with --tls-cert-data), --tls-disable-host-verification (bool, disable TLS hostname verification), --tls-key-data (string, private certificate key data, cannot be used with --tls-key-path), --tls-key-path (string, path to x509 private key, cannot be used with --tls-key-data), --tls-server-name (string, override target TLS server name).
task-queue config get command
The temporal task-queue config get command retrieves the current configuration for a Task Queue. It returns the queue rate limit (the overall rate limit of the task queue that overrides worker rate limit if set) and fairness key rate limit defaults (default rate limits for fairness keys, where each key is limited to this rate scaled by the key's weight). Required flags: --task-queue (string, task queue name), --task-queue-type (string-enum: workflow, activity, nexus).
task-queue config set command
The temporal task-queue config set command updates configuration for a Task Queue. It supports: queue rate limits (controls overall task queue rate limit), fairness key rate limit defaults (sets default rate limits for fairness keys), and fairness key weight overrides (custom weights for specific keys controlling relative capacity share). To unset a rate limit, pass 'default'. To unset a specific fairness weight, use key=default. To unset all fairness weights, use --fairness-key-weight-clear-all. Required flags: --task-queue (string), --task-queue-type (string-enum: workflow, activity, nexus). Optional flags: --queue-rps-limit (float|default), --queue-rps-limit-reason (string), --fairness-key-rps-limit-default (float|default), --fairness-key-rps-limit-reason (string), --fairness-key-weight (string[], format: key=weight or key=default, repeatable), --fairness-key-weight-clear-all (bool).
task-queue describe command overview
The temporal task-queue describe command displays active Workers that have recently polled a Task Queue. The Temporal Server records each poll request time. A LastAccessTime over one minute may indicate the Worker is at capacity or has shut down. Workers are removed if 5 minutes have passed since the last poll request.
task-queue describe statistics
The temporal task-queue describe command provides the following task queue statistics: ApproximateBacklogCount (approximate number of tasks backlogged in the queue, may count expired tasks but eventually converges), ApproximateBacklogAge (approximate age of oldest task in backlog in seconds, based on creation time), TasksAddRate (approximate rate tasks are added in tasks per second, averaged over 30 seconds, includes sync-matched tasks and backlog tasks), TasksDispatchRate (approximate rate tasks are dispatched in tasks per second, averaged over 30 seconds, includes sync-matched and backlog tasks), BacklogIncreaseRate (approximate rate backlog size increases or decreases in tasks per second, averaged over 30 seconds, roughly equivalent to TasksAddRate minus TasksDispatchRate). Note: TasksAddRate and TasksDispatchRate may differ from actual rates because eagerly dispatched or sticky tasks are not counted, but BacklogIncreaseRate is accurate for backlogs older than a few seconds.
task-queue describe flags
The temporal task-queue describe command has required flag --task-queue (string, task queue name). Optional flags: --task-queue-type (string-enum[]: workflow, activity, nexus; if not specified, all types reported), --task-queue-type-legacy (string-enum: workflow, activity; legacy mode only), --disable-stats (bool, disable task queue statistics), --legacy-mode (bool, enable legacy mode for servers not supporting rules-based worker versioning, provides pollers info only), --partitions-legacy (int, query partitions 1 through N, experimental/temporary feature for legacy mode), --report-config (bool, include task queue configuration in response), --report-reachability (bool, display task reachability information), --select-all-active (bool, include all active versions, a version is active if it had new tasks or polls recently), --select-build-id (string[], filter based on Build ID), --select-unversioned (bool, include unversioned queue).
task-queue describe reachability states
Task reachability states are reported per Build ID and may be one of: Reachable (using current versioning rules, Build ID may be used by new Workflow Executions or Activities, or there are currently open Workflow or backlogged Activity tasks assigned to the queue); ClosedWorkflowsOnly (Build ID has no open Workflow Executions and cannot be reached by new Workflow Executions, but may have closed Workflow Executions within namespace retention period); Unreachable (Build ID is not used for new Workflow Executions and is not used by any existing Workflow Execution within retention period). Task reachability is eventually consistent with possible delay until convergence, designed to act conservatively until then (Reachable is more conservative than ClosedWorkflowsOnly).
task-queue describe Build ID reachability deprecation
Task reachability status determined via the --report-reachability flag is deprecated in favor of Drainage Status (of a Drained or Draining Worker Deployment Version) and will be removed in a future release. Additionally, determining task reachability incurs a non-trivial computing cost.
get-build-id-reachability command deprecated
The temporal task-queue get-build-id-reachability command is deprecated and will be removed in a later release. It shows if a given Build ID can be used for new, existing, or closed Workflows in Namespaces that support Worker versioning. Flags: --build-id (string[], repeatable), --task-queue (string[], repeatable; if omitted, checks against all task queues), --reachability-type (string-enum: open, closed, existing; filters reachability).
get-build-ids command deprecated
The temporal task-queue get-build-ids command is deprecated and will be removed in a later release. It fetches sets of compatible Build IDs for specified Task Queues and displays their information. Limited to Namespaces that support Worker versioning. Required flag: --task-queue (string). Optional flag: --max-sets (int; use 1 for default major version, 0 for all sets).
task-queue list-partition command
The temporal task-queue list-partition command displays a Task Queue's partition list with assigned matching nodes. Required flag: --task-queue (string, task queue name).
update-build-ids promote-set command deprecated
The temporal task-queue update-build-ids promote-set command is deprecated and will be removed in a later release. It promotes a Build ID set to be the default on a Task Queue by identifying the set with a Build ID within it. If the set is already default, the command has no effect. Limited to Namespaces that support Worker versioning (experimental feature). Required flags: --task-queue (string), --build-id (string, Build ID within promoted set).
task-queue versioning deprecated
The temporal task-queue versioning command and all its subcommands are deprecated by Worker Deployment.
versioning add-redirect-rule command deprecated
The temporal task-queue versioning add-redirect-rule command is deprecated by Worker Deployment. It adds a new redirect rule for a given Task Queue. Maximum one redirect rule per distinct source Build ID. Required flags: --task-queue (string), --source-build-id (string), --target-build-id (string). Optional flag: --yes/-y (bool, skip confirmation).
Temporal CLI provides terminal access to Temporal Services
The Temporal CLI (temporal) provides direct access to a Temporal Service via the terminal. It is used to manage, monitor, and debug Temporal applications, and can run an embedded development service for fast local feedback during development.
Temporal CLI command reference documentation location
A complete list of Temporal CLI commands is available in the command reference documentation section.
Start local development server with temporal server start-dev
The Temporal CLI includes a local development service that can be started with the command 'temporal server start-dev'. This provides a fast feedback loop while building or testing applications locally.
Temporal CLI installation and configuration documentation location
Instructions for installing the CLI and cloud extension, running a local development server, and configuring the environment are found in the Install and configure the CLI documentation section.
Temporal CLI Cloud extension for managing Temporal Cloud resources
An official extension is available for the Temporal CLI that allows interaction with Temporal Cloud. The extension can manage Temporal Cloud control plane resources including Namespaces, Users, Service Accounts, API keys, and perform operational and administrative tasks.
CLI installation methods
The Temporal CLI can be installed on macOS, Linux, and Windows via Homebrew, downloaded from CDN, or run as a Docker image. For macOS and Linux, use: brew install temporal. For all platforms, download URLs are available from the CDN at temporal.download/cli/archive/latest with parameters ?platform=darwin|linux|windows and &arch=amd64|arm64. Extract the archive and add the temporal (or temporal.exe on Windows) binary to PATH. For Docker, the image temporalio/temporal is available on DockerHub.
Dynamic configuration for development server
Advanced CLI configuration uses a dynamic configuration file. To set values on the command line, use --dynamic-config-value KEY=JSON_VALUE. For example, to enable the Search Attribute cache: temporal server start-dev --dynamic-config-value system.forceSearchAttributesCacheRefreshOnRead=false. This makes created Search Attributes immediately available.
CLI auto-completion for zsh
To enable zsh auto-completion for the Temporal CLI, add the following line to ~/.zshrc: eval "$(temporal completion zsh)". Then re-launch the shell or run: source ~/.zshrc
Getting CLI help
Use the --help flag with any temporal command or subcommand to get help. For example: temporal --help, temporal workflow --help, temporal workflow delete --help. A full list of commands is available in the Temporal CLI command reference.
CLI environment variable vs temporal env command
Setting an environment variable configures the CLI process for the current session, while the temporal env command writes named key-value presets to a configuration file for reuse across sessions. For every variable the CLI reads, its equivalent flag, and its TOML configuration key, refer to Environment configuration documentation.
CLI auto-completion for Fish
To enable Fish auto-completion for the Temporal CLI, create the Fish custom completions directory if it doesn't exist: mkdir -p ~/.config/fish/completions. Then configure completions to load by running: echo 'eval "$(temporal completion fish)"' >~/.config/fish/completions/temporal.fish. The filename must be temporal.fish for completions to be found. Re-launch the shell or run: source ~/.config/fish/completions/temporal.fish
CLI auto-completion for Bash
To enable Bash auto-completion for the Temporal CLI, first install bash-completion and add it to ~/.bashrc. Then add the following line to ~/.bashrc: eval "$(temporal completion bash)". Re-launch the shell or run: source ~/.bashrc. If auto-completion fails with 'bash: _get_comp_words_by_ref: command not found', bash-completion was not successfully installed.
Disable Web UI in development server
To run the development server without the Web UI, use the --headless modifier: temporal server start-dev --headless
Proxy support configuration
To route Temporal CLI requests through a proxy, set the HTTPS_PROXY environment variable: export HTTPS_PROXY=<host>:<port>. Replace <host> with the proxy hostname or IP address and <port> with the proxy port number. The CLI uses gRPC which natively supports HTTP CONNECT proxies. Additionally, the NO_PROXY environment variable can be set to exclude specific addresses or domains from proxying.
Namespace pre-registration at startup
Pre-register Namespaces when starting the development server by specifying them on the command line. For example: temporal server start-dev --namespace foo --namespace bar. Namespaces can also be registered after startup with: temporal operator namespace create --namespace foo
Development server startup
Start the local Temporal development service with: temporal server start-dev. This command automatically starts the Web UI, creates the default Namespace, and uses an in-memory SQLite database. The Temporal Server is available on localhost:7233 and the Web UI at http://localhost:8233/. To persist state to a database file, use: temporal server start-dev --db-filename temporal.db
Temporal Cloud CLI extension
The Temporal Cloud extension for the CLI can be installed with: brew install temporalio/prerelease/temporal-cloud. The extension is currently in Pre-release stage and APIs and configuration may change before stable release.
Docker CLI container port configuration
When running Temporal CLI in Docker for development, configure the server to listen on external IP and forward ports so the service is accessible from the host system. Use: docker run --rm -p 7233:7233 -p 8233:8233 temporalio/temporal server start-dev --ip 0.0.0.0. The UI will be accessible at http://localhost:8233/
workflow list command
The `temporal workflow list` command lists Workflow Executions. Optional flags: --archived (bool, limit to archived executions, experimental), --limit (int, maximum number to display), --page-size (int, maximum number to fetch per server request), --query/-q (string, SQL-like QUERY List Filter).
global flag --env
The --env global flag sets the active environment name (ENV). Type: string. Default: default.
global flag --env-file
The --env-file global flag specifies the path to environment settings file. Defaults to $HOME/.config/temporalio/temporal.yaml. Type: string. Optional.
global flag --tls-cert-path
The --tls-cert-path global flag specifies the path to x509 certificate. Type: string. Cannot be used with --tls-cert-data. Optional.
global flag --tls-disable-host-verification
The --tls-disable-host-verification global flag disables TLS host-name verification. Type: bool. Optional.
workflow count command
The `temporal workflow count` command shows a count of Workflow Executions regardless of execution state (running, terminated, etc). It supports --query/-q flag (string, optional) to select a subset of Workflow Executions using SQL-like QUERY List Filters.
workflow delete flags
The `temporal workflow delete` command has the following flags: --headers (string[], optional), --query/-q (string, optional), --reason (string, optional), --rps (float, optional), --run-id/-r (string, optional), --workflow-id/-w (string, optional), --yes/-y (bool, optional). Either --workflow-id or --query must be set.
workflow describe flags
The `temporal workflow describe` command has the following flags: --raw (bool, optional), --reset-points (bool, optional), --run-id/-r (string, optional), --workflow-id/-w (string, required). The --workflow-id flag is required.
workflow execute command options
The `temporal workflow execute` command establishes a new Workflow Execution and blocks until completion. It requires --task-queue/-t (string) and --type (string). Optional flags include: --cron (string), --detailed (bool), --execution-timeout (duration), --fail-existing (bool), --fairness-key (string, max 64 bytes), --fairness-weight (float, 0.001-1000), --headers (string[]), --id-conflict-policy (Fail, UseExisting, TerminateExisting), --id-reuse-policy (AllowDuplicate, AllowDuplicateFailedOnly, RejectDuplicate, TerminateIfRunning), --input/-i (string[]), --input-base64 (bool), --input-file (string[]), --input-meta (string[]), --memo (string[]), --priority-key (int, 1-5, default 3), --run-timeout (duration), --search-attribute (string[]), --start-delay (duration), --static-details (string, experimental), --static-summary (string, experimental), --task-timeout (duration), --workflow-id/-w (string, optional).
workflow execute event details in JSON output
The --event-details flag relays updates to the command-line output in JSON format. When using JSON output (--output json), this includes the entire "history" JSON key for the run.
workflow execute-update-with-start flags
The `temporal workflow execute-update-with-start` command has the following flags: --cron, --execution-timeout, --fail-existing, --fairness-key, --fairness-weight, --headers, --id-conflict-policy, --id-reuse-policy, --input/-i, --input-base64, --input-file, --input-meta, --memo, --priority-key, --run-id/-r, --run-timeout, --search-attribute, --start-delay, --static-details, --static-summary, --task-queue/-t (required), --task-timeout, --type (required), --update-first-execution-run-id, --update-id, --update-input, --update-input-base64, --update-input-file, --update-input-meta, --update-name (required), --workflow-id/-w (optional).
workflow fix-history-json command
The `temporal workflow fix-history-json` command reserializes an Event History JSON file. Required flag: --source/-s (string, path to original file). Optional flag: --target/-t (string, path to results file; when omitted, output goes to stdout).
global flag --disable-config-file
The --disable-config-file global flag disables loading environment config from config file when set. Type: bool. Optional.
workflow metadata command
The `temporal workflow metadata` command issues a Query to display user-set metadata like summary and details for a specific Workflow Execution. Required flag: --workflow-id/-w (string). Optional flags: --headers (string[]), --reject-condition (not_open, not_completed_cleanly), --run-id/-r (string).
workflow query command for state inspection
The `temporal workflow query` command sends a Query to a Workflow Execution to retrieve its state. This synchronous operation exposes the internal state of a running Workflow Execution. You can query both running and completed Workflow Executions. Required flag: --name (string, Query Type/Name), --workflow-id/-w (string). Optional flags: --headers (string[]), --input/-i (string[]), --input-base64 (bool), --input-file (string[]), --input-meta (string[]), --reject-condition (not_open, not_completed_cleanly), --run-id/-r (string).
workflow reset command modes
The `temporal workflow reset` command resets a Workflow Execution so it can resume from a point in its Event History without losing progress up to that point. It can reset by event ID or by type (e.g., LastContinuedAsNew). For batch resets, limit resets to FirstWorkflowTask, LastWorkflowTask, or BuildId; do not use Workflow IDs, run IDs, or event IDs.
workflow reset with-workflow-update-options subcommand
The `temporal workflow reset with-workflow-update-options` subcommand runs Workflow Update Options atomically after the Workflow is reset. Workflows selected by the reset command are forwarded onto this subcommand. Required flag: --versioning-override-behavior (string-enum: pinned, auto_upgrade). Optional flags: --versioning-override-build-id (string), --versioning-override-deployment-name (string).
workflow result command
The `temporal workflow result` command waits for and prints the result of a Workflow Execution. Required flag: --workflow-id/-w (string). Optional flag: --run-id/-r (string).
workflow show event history
The `temporal workflow show` command displays a Workflow Execution's Event History. When using JSON output (--output json), results can be passed to an SDK to perform a replay. Required flag: --workflow-id/-w (string). Optional flags: --detailed (bool), --follow/-f (bool), --reverse (bool), --run-id/-r (string).
workflow signal asynchronous notification
The `temporal workflow signal` command sends an asynchronous notification (Signal) to a running Workflow Execution. The Signal is written to the History. When --input is included, that data is available for the Workflow Execution to consume. Required flag: --name (string, Signal name). Either --workflow-id or --query must be set. Optional flags: --headers (string[]), --input/-i (string[]), --input-base64 (bool), --input-file (string[]), --input-meta (string[]), --query/-q (string), --reason (string), --rps (float), --run-id/-r (string), --workflow-id/-w (string), --yes/-y (bool).
workflow signal-with-start command
The `temporal workflow signal-with-start` command sends an asynchronous notification (Signal) to a Workflow Execution. If the Workflow Execution is not running or not found, it starts the workflow then sends the signal. Required flags: --signal-name (string), --task-queue/-t (string), --type (string). Optional flags include workflow creation options (--cron, --execution-timeout, --fail-existing, --fairness-key, --fairness-weight, --headers, --id-conflict-policy, --id-reuse-policy, --input/-i, --input-base64, --input-file, --input-meta, --memo, --priority-key, --run-timeout, --search-attribute, --signal-input, --signal-input-base64, --signal-input-file, --signal-input-meta, --start-delay, --static-details, --static-summary, --task-timeout, --workflow-id/-w).