From 64349fcde3e68cc5e5c1f10eb2e4d854e2992703 Mon Sep 17 00:00:00 2001 From: starfleeth <128422269+starfleeth@users.noreply.github.com> Date: Wed, 20 May 2026 17:35:54 -0700 Subject: [PATCH 1/3] Absorb CLI skill content: workflow commands, dev server, and CLI gotchas Migrate developer-facing content from skill-temporal-cli as part of the CLI skill consolidation. Adds cli-workflow-commands.md (start, execute, signal, query, update reference), expands dev-management.md with full dev server flags and dev-to-prod recipe, appends CLI gotchas, and enriches install_cli.md. Updates SKILL.md triggers and routing. Co-Authored-By: Claude Opus 4.6 --- SKILL.md | 10 +- references/core/cli-workflow-commands.md | 266 +++++++++++++++++++++++ references/core/dev-management.md | 89 ++++++++ references/core/gotchas.md | 27 +++ references/core/install_cli.md | 45 +++- 5 files changed, 431 insertions(+), 6 deletions(-) create mode 100644 references/core/cli-workflow-commands.md diff --git a/SKILL.md b/SKILL.md index 6194c90..310ccb2 100644 --- a/SKILL.md +++ b/SKILL.md @@ -1,6 +1,6 @@ --- name: temporal-developer -description: Develop, debug, and manage Temporal applications across Python, TypeScript, Go, Java and .NET. Use when the user is building workflows, activities, or workers with a Temporal SDK, debugging issues like non-determinism errors, stuck workflows, or activity retries, using Temporal CLI, Temporal Server, or Temporal Cloud, or working with durable execution concepts like signals, queries, heartbeats, versioning, continue-as-new, child workflows, or saga patterns. +description: Develop, debug, and manage Temporal applications across Python, TypeScript, Go, Java and .NET. Use when the user is building workflows, activities, or workers with a Temporal SDK, debugging issues like non-determinism errors, stuck workflows, or activity retries, using Temporal CLI, Temporal Server, or Temporal Cloud, or working with durable execution concepts like signals, queries, heartbeats, versioning, continue-as-new, child workflows, or saga patterns. Also use when the user mentions "run a Temporal workflow from the CLI", "start a dev server", "run temporal server start-dev", "temporal workflow start", "temporal workflow execute", "temporal workflow signal", "temporal workflow query", "temporal workflow update". version: 0.4.0 --- @@ -74,6 +74,7 @@ Check if `temporal` CLI is installed. If not, follow the instructions at `refere - **`references/core/error-reference.md`** - Common error types, workflow status reference - **`references/core/interactive-workflows.md`** - Testing signals, updates, queries - **`references/core/dev-management.md`** - Dev cycle & management of server and workers +- **`references/core/cli-workflow-commands.md`** - Developer-facing CLI commands for workflow interaction (start, execute, signal, query, update) - **`references/core/ai-patterns.md`** - AI/LLM pattern concepts - Language-specific info at `references/{your_language}/ai-patterns.md`, if available. Currently Python only. @@ -94,6 +95,13 @@ Priority and Fairness also apply to tiered workloads (batch vs. real-time), weig For Temporal plugins and integrations with third-party frameworks and SDKs (Spring Boot, Spring AI, OpenAI Agents SDK, Google ADK, etc.), see **`references/integrations.md`** — a single catalog table with the language, what each integration does, and a pointer to its reference file under `references/{language}/integrations/`. +## Out of scope + +- **Operational CLI commands** (batch operations, health queries, Cloud admin, tcld, scripting) → `skill-temporal-ops`. +- **Worker performance tuning, sizing, capacity planning** → `skill-temporal-workertuning`. + +If the conversation drifts into one of these areas, hand off to the relevant sibling skill rather than improvising. + ## Feedback ### Reporting Issues in This Skill diff --git a/references/core/cli-workflow-commands.md b/references/core/cli-workflow-commands.md new file mode 100644 index 0000000..373101f --- /dev/null +++ b/references/core/cli-workflow-commands.md @@ -0,0 +1,266 @@ +# CLI Workflow Commands for Developers + +Developer-facing CLI commands for interacting with workflows during development and testing. These commands work identically against a dev server, a self-hosted cluster, or Temporal Cloud -- only the connection descriptor changes. + +All facts in this file are transcribed from the upstream CLI docs. Each section ends with a `` footer. + +## Table of contents + +- [Workflow start](#workflow-start) +- [Workflow execute](#workflow-execute) +- [Workflow signal](#workflow-signal) +- [Workflow query](#workflow-query) +- [Workflow update](#workflow-update) +- [Workflow signal-with-start](#workflow-signal-with-start) +- [Workflow result](#workflow-result) +- [Workflow metadata](#workflow-metadata) + +## Workflow start + +Start a new Workflow Execution asynchronously. Returns the Workflow ID and Run ID. + +```bash +temporal workflow start \ + --workflow-id YourWorkflowId \ + --type YourWorkflow \ + --task-queue YourTaskQueue \ + --input '{"some-key": "some-value"}' +``` + +Required flags: `--type`, `--task-queue`. Optional `--workflow-id` -- the Service generates a UUID if omitted. + +| Flag | Accepted values / format | Purpose | +|---|---|---| +| `--type` | string | Workflow Type name. Required. | +| `--task-queue`, `-t` | string | Workflow Task queue. Required. | +| `--workflow-id`, `-w` | string | Workflow ID. Service generates a UUID if omitted. | +| `--input`, `-i` | JSON string | Input value. Repeatable for multiple args. Mutually exclusive with `--input-file`. | +| `--input-file` | path | Read input from file(s). Repeatable. Mutually exclusive with `--input`. | +| `--input-base64` | bool | Decode `--input` as base64 before sending. | +| `--input-meta` | `KEY=VALUE` | Override payload metadata (e.g., `encoding=json/protobuf`). Repeatable. | +| `--id-reuse-policy` | `AllowDuplicate`, `AllowDuplicateFailedOnly`, `RejectDuplicate`, `TerminateIfRunning` | How to reuse a previously-seen Workflow ID. | +| `--id-conflict-policy` | `Fail`, `UseExisting`, `TerminateExisting` | How to resolve conflicts with a currently-running execution sharing the same Workflow ID. | +| `--execution-timeout` | duration | Fail a Workflow Execution if it lasts longer than this. Includes retries and ContinueAsNew. | +| `--run-timeout` | duration | Fail a single Workflow Run if it lasts longer than this. | +| `--task-timeout` | duration | Start-to-close timeout for a Workflow Task. | +| `--search-attribute` | `KEY=VALUE` (JSON values) | Set a search attribute at start time. Repeatable. | +| `--memo` | `KEY="VALUE"` (JSON values) | Attach unindexed metadata. Repeatable. | +| `--start-delay` | duration | Delay before starting. Cannot combine with `--cron`. If the Workflow receives a signal or update before this time, it starts immediately. | +| `--cron` | cron string | Legacy cron schedule (prefer `temporal schedule create`). | +| `--priority-key` | `1`-`5` (default `3`) | Lower numbers = higher priority. | +| `--fairness-key` | string (max 64 bytes) | Proportional task dispatch grouping key. | +| `--fairness-weight` | `0.001`-`1000` | Weight for this fairness key. Keys dispatched proportionally to their weights. | +| `--static-summary` | Markdown string | Human-readable summary for UIs. Single line. _(Experimental)_ | +| `--static-details` | Markdown string | Human-readable details for UIs. May be multiple lines. _(Experimental)_ | +| `--fail-existing` | bool | Fail if the Workflow already exists. | +| `--headers` | `KEY=VALUE` (JSON values) | Temporal workflow headers (not gRPC). Repeatable. | + + + +## Workflow execute + +Start a Workflow Execution and block until it completes, streaming progress to stdout. + +```bash +temporal workflow execute \ + --workflow-id YourWorkflowId \ + --type YourWorkflow \ + --task-queue YourTaskQueue \ + --input '{"some-key": "some-value"}' +``` + +Accepts the same start-time flags as `workflow start`, plus `--detailed` (display events as sections rather than a table; not applied to JSON output). With `--output json`, the emitted blob includes the full `history` key for the run. + +A non-zero exit code means the Workflow failed, was cancelled, terminated, or timed out. Useful for one-shot scripts and smoke tests during development. + + + +## Workflow signal + +Send an asynchronous signal to a running Workflow Execution. + +```bash +temporal workflow signal \ + --workflow-id YourWorkflowId \ + --name YourSignal \ + --input '{"YourInputKey": "YourInputValue"}' +``` + +| Flag | Required | Purpose | +|---|---|---| +| `--workflow-id`, `-w` | Yes (or `--query`) | Workflow ID. | +| `--name` | Yes | Signal name. | +| `--input`, `-i` | No | Input value (JSON). Repeatable. | +| `--run-id`, `-r` | No | Pin to a specific run. Only with `--workflow-id`. | + +For bulk signaling with `--query` (runs as a batch job), see skill-temporal-ops. + + + +## Workflow query + +Invoke a read-only query handler. Queries do not mutate workflow state and can run on both running and completed workflows. + +```bash +temporal workflow query \ + --workflow-id YourWorkflowId \ + --name YourQueryType \ + --input '{"YourInputKey": "YourInputValue"}' +``` + +| Flag | Required | Purpose | +|---|---|---| +| `--workflow-id`, `-w` | Yes | Workflow ID. | +| `--name` | Yes | Query Type/Name. | +| `--input`, `-i` | No | Input value (JSON). Repeatable. | +| `--run-id`, `-r` | No | Run ID. | +| `--reject-condition` | No | Reject queries based on Workflow state. Accepted values: `not_open`, `not_completed_cleanly`. | + + + +## Workflow update + +Update is a command **group**, not a single command. It has four subcommands: `describe`, `execute`, `result`, `start`. + +### `temporal workflow update start` + +Initiate an update and wait for the validator to accept or reject it. + +```bash +temporal workflow update start \ + --workflow-id YourWorkflowId \ + --name YourUpdate \ + --input '{"some-key": "some-value"}' \ + --wait-for-stage accepted +``` + +| Flag | Required | Purpose | +|---|---|---| +| `--workflow-id`, `-w` | Yes | Workflow ID. | +| `--name` | Yes | Handler method name. | +| `--wait-for-stage` | Yes | Update stage to wait for. The **only** accepted value is `accepted`. Required to allow a future CLI version to choose a default. | +| `--input`, `-i` | No | Input value (JSON). Repeatable. | +| `--update-id` | No | Idempotency key. Defaults to a UUID. | +| `--run-id`, `-r` | No | Run ID. If unset, targets the currently-running execution. | +| `--first-execution-run-id` | No | Pin the update to the last execution in the chain started with this Run ID. | + + + +### `temporal workflow update execute` + +Start an update and wait for it to complete or fail. Can also wait on an existing in-flight update by reusing its Update ID. + +```bash +temporal workflow update execute \ + --workflow-id YourWorkflowId \ + --name YourUpdate \ + --input '{"some-key": "some-value"}' +``` + +| Flag | Required | Purpose | +|---|---|---| +| `--workflow-id`, `-w` | Yes | Workflow ID. | +| `--name` | Yes | Handler method name. | +| `--input`, `-i` | No | Input value (JSON). Repeatable. | +| `--update-id` | No | Idempotency key. Defaults to a UUID. | +| `--run-id`, `-r` | No | Run ID. If unset, targets the currently-running execution. | +| `--first-execution-run-id` | No | Pin the update to the last execution in the chain started with this Run ID. | + + + +### `temporal workflow update result` + +Wait for a previously started update to complete or fail, then print the result. + +```bash +temporal workflow update result \ + --workflow-id YourWorkflowId \ + --update-id YourUpdateId +``` + +| Flag | Required | Purpose | +|---|---|---| +| `--workflow-id`, `-w` | Yes | Workflow ID. | +| `--update-id` | Yes | Update ID. Must be unique per Workflow Execution. | +| `--run-id`, `-r` | No | Run ID. | + + + +### `temporal workflow update describe` + +Inspect the current status of an update, including a result if it has finished. + +```bash +temporal workflow update describe \ + --workflow-id YourWorkflowId \ + --update-id YourUpdateId +``` + +| Flag | Required | Purpose | +|---|---|---| +| `--workflow-id`, `-w` | Yes | Workflow ID. | +| `--update-id` | Yes | Update ID. Must be unique per Workflow Execution. | +| `--run-id`, `-r` | No | Run ID. | + + + +## Workflow signal-with-start + +Atomically signal a Workflow Execution -- if the target run does not exist, a new Workflow Execution is created first, then the signal is delivered. + +```bash +temporal workflow signal-with-start \ + --signal-name YourSignal \ + --signal-input '{"some-key": "some-value"}' \ + --workflow-id YourWorkflowId \ + --type YourWorkflowType \ + --task-queue YourTaskQueue \ + --input '{"some-key": "some-value"}' +``` + +Takes `--signal-name` (required), `--signal-input`, plus all start-time flags from `workflow start`. + +| Flag | Required | Purpose | +|---|---|---| +| `--signal-name` | Yes | Signal name. | +| `--signal-input` | No | Signal input value (JSON). Repeatable. | +| `--type` | Yes | Workflow Type name. | +| `--task-queue`, `-t` | Yes | Workflow Task queue. | +| `--workflow-id`, `-w` | No | Workflow ID. Service generates a UUID if omitted. | + +All other start-time flags (`--input`, `--id-reuse-policy`, `--id-conflict-policy`, timeouts, `--search-attribute`, `--memo`, etc.) are accepted. See [Workflow start](#workflow-start) for the full flag table. + + + +## Workflow result + +Block until a running Workflow Execution completes, then print the result. + +```bash +temporal workflow result \ + --workflow-id YourWorkflowId +``` + +| Flag | Required | Purpose | +|---|---|---| +| `--workflow-id`, `-w` | Yes | Workflow ID. | +| `--run-id`, `-r` | No | Run ID. | + + + +## Workflow metadata + +Issue a query to read user-set summary and details metadata for a Workflow Execution. + +```bash +temporal workflow metadata \ + --workflow-id YourWorkflowId +``` + +| Flag | Required | Purpose | +|---|---|---| +| `--workflow-id`, `-w` | Yes | Workflow ID. | +| `--run-id`, `-r` | No | Run ID. | +| `--reject-condition` | No | Reject queries based on Workflow state. Accepted values: `not_open`, `not_completed_cleanly`. | + + diff --git a/references/core/dev-management.md b/references/core/dev-management.md index 45385d3..3eb01ba 100644 --- a/references/core/dev-management.md +++ b/references/core/dev-management.md @@ -10,6 +10,38 @@ temporal server start-dev # Start this in the background. It is perfectly OK for this process to be shared across multiple projects / left running as you develop your Temporal code. +The dev server is in-memory by default -- all workflows, schedules, and history are lost on restart. Use `--db-filename temporal.db` to persist across restarts. + +The dev server is for local development only, not production. + +### `temporal server start-dev` flags + +| Flag | Default | Purpose | +|---|---|---| +| `--db-filename`, `-f` | in-memory | Persistent SQLite file. Without it, state is in-memory and lost on exit. | +| `--namespace`, `-n` | `default` only | Namespaces to create at launch. Repeatable. The `default` namespace is always created. | +| `--search-attribute` | — | Register search attributes as `KEY=TYPE` pairs. TYPE is one of: `Text`, `Keyword`, `Int`, `Double`, `Bool`, `Datetime`, `KeywordList`. Repeatable. | +| `--port`, `-p` | `7233` | Front-end gRPC port. | +| `--ui-port` | `--port` + 1000 | Web UI port. | +| `--ip` | `127.0.0.1` | IP address bound to the front-end service. Use `0.0.0.0` for Docker/LAN access. | +| `--dynamic-config-value` | — | Dynamic config in `KEY=JSON_VALUE` form. Repeatable. | +| `--log-level` | `warn` | Log level. Accepted values: `debug`, `info`, `warn`, `error`, `never`. | +| `--log-format` | `text` | Log format. Accepted values: `text`, `json`. | +| `--headless` | — | Disable the Web UI. | +| `--http-port` | random free port | HTTP API port. | +| `--metrics-port` | random free port | Prometheus `/metrics` port. | + +Example with persistence, extra namespaces, and a search attribute: + +```bash +temporal server start-dev \ + --db-filename /tmp/temporal.db \ + --namespace dev \ + --search-attribute OrderId=Keyword +``` + + + ## Worker Management Details ### Starting Workers @@ -23,3 +55,60 @@ When you need a new worker, you should start it in the background (and preferrab ### Cleanup **Always kill workers when done.** Don't leave workers running. + +## Dev to Prod + +Steps to promote a workflow from a local dev server to a production backend. The workflow and worker code do not change between environments; only the connection descriptor does. + +### 1. Start a local dev server with persistence + +```bash +temporal server start-dev --db-filename dev.db +``` + + + +### 2. Run the workflow against dev + +Start your worker, then execute the workflow: + +```bash +temporal workflow execute \ + --type MyWorkflow \ + --task-queue my-queue \ + --input '{"key": "value"}' +``` + +`workflow execute` blocks until the run terminates; a non-zero exit means the run failed, was cancelled, terminated, or timed out. + +### 3. Create a prod stored environment + +```bash +temporal env set prod.address "your-ns.your-acct.tmprl.cloud:7233" +temporal env set prod.namespace "your-ns.your-acct" +temporal env set prod.api-key "your-key" +``` + +The environment-selecting flag is `--env ` (env var `TEMPORAL_ENV`). + +### 4. Smoke-test prod + +```bash +temporal workflow list --env prod --limit 1 +``` + +If this returns (even an empty list), the connection descriptor is correct. + +### 5. Run in prod + +```bash +temporal workflow start \ + --env prod \ + --type MyWorkflow \ + --task-queue my-queue \ + --input '{"key": "value"}' +``` + +`workflow start` is asynchronous (returns a Workflow/Run ID); use `workflow execute` instead if you want the CLI to block. + +For stored environment details, see skill-temporal-ops `cli-scripting.md`. diff --git a/references/core/gotchas.md b/references/core/gotchas.md index 677362f..0d86670 100644 --- a/references/core/gotchas.md +++ b/references/core/gotchas.md @@ -195,6 +195,33 @@ See language-specific gotchas for details. **The Fix**: Heartbeat regularly and check for cancellation. See language-specific gotchas for implementation patterns. +## CLI Gotchas for Developers + +### Dev Server Is In-Memory by Default + +All workflows, schedules, and history vanish on restart. Use `--db-filename temporal.db` for persistence. Do not rely on dev server state across restarts. + +### Dev Server Is Not for Production + +The dev server runs all services in a single process with no replication. Use Temporal Cloud or a self-hosted cluster for production. + +### `workflow update` Is a Command Group, Not a Single Command + +Running `temporal workflow update` alone will not work. Use the correct subcommand: + +- `temporal workflow update execute` -- start an update and wait for completion. +- `temporal workflow update start` -- fire an update and wait for acceptance. Requires `--wait-for-stage accepted`. +- `temporal workflow update result` -- get the result of a previously started update. +- `temporal workflow update describe` -- check an update's current status. + +### `--wait-for-stage` Only Accepts `accepted` + +Despite looking like an enum, the only valid value for `--wait-for-stage` on `temporal workflow update start` is `accepted`. Passing `completed` or other values will fail. The flag is required to allow a future CLI version to choose a default. + +### `--reapply-type` Only Accepts `Signal` or `None` + +When resetting a workflow with `temporal workflow reset`, `--reapply-type` controls which events get reapplied after the reset point. Only `Signal` and `None` are valid values. + ## Payload Size Limits **The Problem**: Temporal has built-in limits on payload sizes. Exceeding them causes workflows to fail. diff --git a/references/core/install_cli.md b/references/core/install_cli.md index 4421172..8694fd1 100644 --- a/references/core/install_cli.md +++ b/references/core/install_cli.md @@ -1,25 +1,60 @@ # How to install Temporal CLI + + ## macOS -``` +Homebrew or CDN tarball: + +```bash brew install temporal ``` +- [Darwin amd64](https://temporal.download/cli/archive/latest?platform=darwin&arch=amd64) +- [Darwin arm64](https://temporal.download/cli/archive/latest?platform=darwin&arch=arm64) + +Extract any downloaded archive and add the `temporal` binary to your `PATH`. + ## Linux -Check your machine's architecture and download the appropriate archive: +Homebrew (if available), Snap, or CDN tarball: + +```bash +brew install temporal +# or +snap install temporal +``` - [Linux amd64](https://temporal.download/cli/archive/latest?platform=linux&arch=amd64) - [Linux arm64](https://temporal.download/cli/archive/latest?platform=linux&arch=arm64) -Once you've downloaded the file, extract the downloaded archive and add the temporal binary to your PATH by copying it to a directory like /usr/local/bin +Extract any downloaded archive and add the `temporal` binary to your `PATH`. ## Windows -Check your machine's architecture and download the appropriate archive: +Download from the CDN: - [Windows amd64](https://temporal.download/cli/archive/latest?platform=windows&arch=amd64) - [Windows arm64](https://temporal.download/cli/archive/latest?platform=windows&arch=arm64) -Once you've downloaded the file, extract the downloaded archive and add the temporal.exe binary to your PATH. \ No newline at end of file +Extract the archive and add the `temporal.exe` binary to your `PATH`. + +## Docker + +```bash +docker run --rm temporalio/temporal --help +``` + + + +## `tcld` (Temporal Cloud CLI) + +Needed for Cloud-connected development (managing Cloud namespaces, API keys, etc.). + +Homebrew: + +```bash +brew install temporalio/brew/tcld +``` + + \ No newline at end of file From 937b8668ec3412dea813ec31eb95b9b837f747c8 Mon Sep 17 00:00:00 2001 From: starfleeth <128422269+starfleeth@users.noreply.github.com> Date: Thu, 21 May 2026 15:12:29 -0700 Subject: [PATCH 2/3] Address review feedback: flag table consistency, global flag annotations, dedup gotchas Standardize cli-workflow-commands.md flag tables to use Required column throughout. Annotate --log-level and --log-format as global flags in dev-management.md. Collapse redundant dev server gotchas into a cross-reference to dev-management.md. Co-Authored-By: Claude Opus 4.6 --- references/core/cli-workflow-commands.md | 48 ++++++++++++------------ references/core/dev-management.md | 4 +- references/core/gotchas.md | 8 +--- 3 files changed, 28 insertions(+), 32 deletions(-) diff --git a/references/core/cli-workflow-commands.md b/references/core/cli-workflow-commands.md index 373101f..482a587 100644 --- a/references/core/cli-workflow-commands.md +++ b/references/core/cli-workflow-commands.md @@ -29,31 +29,31 @@ temporal workflow start \ Required flags: `--type`, `--task-queue`. Optional `--workflow-id` -- the Service generates a UUID if omitted. -| Flag | Accepted values / format | Purpose | +| Flag | Required | Purpose | |---|---|---| -| `--type` | string | Workflow Type name. Required. | -| `--task-queue`, `-t` | string | Workflow Task queue. Required. | -| `--workflow-id`, `-w` | string | Workflow ID. Service generates a UUID if omitted. | -| `--input`, `-i` | JSON string | Input value. Repeatable for multiple args. Mutually exclusive with `--input-file`. | -| `--input-file` | path | Read input from file(s). Repeatable. Mutually exclusive with `--input`. | -| `--input-base64` | bool | Decode `--input` as base64 before sending. | -| `--input-meta` | `KEY=VALUE` | Override payload metadata (e.g., `encoding=json/protobuf`). Repeatable. | -| `--id-reuse-policy` | `AllowDuplicate`, `AllowDuplicateFailedOnly`, `RejectDuplicate`, `TerminateIfRunning` | How to reuse a previously-seen Workflow ID. | -| `--id-conflict-policy` | `Fail`, `UseExisting`, `TerminateExisting` | How to resolve conflicts with a currently-running execution sharing the same Workflow ID. | -| `--execution-timeout` | duration | Fail a Workflow Execution if it lasts longer than this. Includes retries and ContinueAsNew. | -| `--run-timeout` | duration | Fail a single Workflow Run if it lasts longer than this. | -| `--task-timeout` | duration | Start-to-close timeout for a Workflow Task. | -| `--search-attribute` | `KEY=VALUE` (JSON values) | Set a search attribute at start time. Repeatable. | -| `--memo` | `KEY="VALUE"` (JSON values) | Attach unindexed metadata. Repeatable. | -| `--start-delay` | duration | Delay before starting. Cannot combine with `--cron`. If the Workflow receives a signal or update before this time, it starts immediately. | -| `--cron` | cron string | Legacy cron schedule (prefer `temporal schedule create`). | -| `--priority-key` | `1`-`5` (default `3`) | Lower numbers = higher priority. | -| `--fairness-key` | string (max 64 bytes) | Proportional task dispatch grouping key. | -| `--fairness-weight` | `0.001`-`1000` | Weight for this fairness key. Keys dispatched proportionally to their weights. | -| `--static-summary` | Markdown string | Human-readable summary for UIs. Single line. _(Experimental)_ | -| `--static-details` | Markdown string | Human-readable details for UIs. May be multiple lines. _(Experimental)_ | -| `--fail-existing` | bool | Fail if the Workflow already exists. | -| `--headers` | `KEY=VALUE` (JSON values) | Temporal workflow headers (not gRPC). Repeatable. | +| `--type` | Yes | Workflow Type name. | +| `--task-queue`, `-t` | Yes | Workflow Task queue. | +| `--workflow-id`, `-w` | No | Workflow ID. Service generates a UUID if omitted. | +| `--input`, `-i` | No | Input value (JSON). Repeatable. Mutually exclusive with `--input-file`. | +| `--input-file` | No | Read input from file(s). Repeatable. Mutually exclusive with `--input`. | +| `--input-base64` | No | Decode `--input` as base64 before sending. | +| `--input-meta` | No | Override payload metadata as `KEY=VALUE` (e.g., `encoding=json/protobuf`). Repeatable. | +| `--id-reuse-policy` | No | How to reuse a previously-seen Workflow ID. Values: `AllowDuplicate`, `AllowDuplicateFailedOnly`, `RejectDuplicate`, `TerminateIfRunning`. | +| `--id-conflict-policy` | No | How to resolve conflicts with a running execution sharing the same ID. Values: `Fail`, `UseExisting`, `TerminateExisting`. | +| `--execution-timeout` | No | Fail a Workflow Execution if it lasts longer than this (duration). Includes retries and ContinueAsNew. | +| `--run-timeout` | No | Fail a single Workflow Run if it lasts longer than this (duration). | +| `--task-timeout` | No | Start-to-close timeout for a Workflow Task (duration). | +| `--search-attribute` | No | Set a search attribute as `KEY=VALUE` (JSON values). Repeatable. | +| `--memo` | No | Attach unindexed metadata as `KEY="VALUE"` (JSON values). Repeatable. | +| `--start-delay` | No | Delay before starting (duration). Cannot combine with `--cron`. | +| `--cron` | No | Legacy cron schedule (prefer `temporal schedule create`). | +| `--priority-key` | No | Priority 1-5 (default 3). Lower = higher priority. | +| `--fairness-key` | No | Proportional task dispatch grouping key (string, max 64 bytes). | +| `--fairness-weight` | No | Weight for this fairness key (0.001-1000). Keys dispatched proportionally. | +| `--static-summary` | No | Human-readable summary for UIs. Single line. _(Experimental)_ | +| `--static-details` | No | Human-readable details for UIs. May be multi-line. _(Experimental)_ | +| `--fail-existing` | No | Fail if the Workflow already exists. | +| `--headers` | No | Temporal workflow headers as `KEY=VALUE` (JSON). Not gRPC headers. Repeatable. | diff --git a/references/core/dev-management.md b/references/core/dev-management.md index 3eb01ba..4515ae1 100644 --- a/references/core/dev-management.md +++ b/references/core/dev-management.md @@ -25,8 +25,8 @@ The dev server is for local development only, not production. | | `--ip` | `127.0.0.1` | IP address bound to the front-end service. Use `0.0.0.0` for Docker/LAN access. | | `--dynamic-config-value` | — | Dynamic config in `KEY=JSON_VALUE` form. Repeatable. | -| `--log-level` | `warn` | Log level. Accepted values: `debug`, `info`, `warn`, `error`, `never`. | -| `--log-format` | `text` | Log format. Accepted values: `text`, `json`. | +| `--log-level` | `warn` | (Global flag) Log level. Accepted values: `debug`, `info`, `warn`, `error`, `never`. Default is `warn` for `start-dev`. | +| `--log-format` | `text` | (Global flag) Log format. Accepted values: `text`, `json`. | | `--headless` | — | Disable the Web UI. | | `--http-port` | random free port | HTTP API port. | | `--metrics-port` | random free port | Prometheus `/metrics` port. | diff --git a/references/core/gotchas.md b/references/core/gotchas.md index 0d86670..3b37d0d 100644 --- a/references/core/gotchas.md +++ b/references/core/gotchas.md @@ -197,13 +197,9 @@ See language-specific gotchas for details. ## CLI Gotchas for Developers -### Dev Server Is In-Memory by Default +### Dev Server Is In-Memory and Not for Production -All workflows, schedules, and history vanish on restart. Use `--db-filename temporal.db` for persistence. Do not rely on dev server state across restarts. - -### Dev Server Is Not for Production - -The dev server runs all services in a single process with no replication. Use Temporal Cloud or a self-hosted cluster for production. +The dev server loses all state on restart (use `--db-filename` to persist) and runs everything in a single process. See `dev-management.md` for the full flag table and persistence guidance. ### `workflow update` Is a Command Group, Not a Single Command From 1c50cfce0fc213f6edb9c6d13df770952a91cfd4 Mon Sep 17 00:00:00 2001 From: starfleeth <128422269+starfleeth@users.noreply.github.com> Date: Thu, 21 May 2026 15:19:48 -0700 Subject: [PATCH 3/3] Clarify that a local dev server is not required for development Workers can target a local dev server, self-hosted cluster, or Temporal Cloud. The previous wording implied a local server was mandatory. Co-Authored-By: Claude Opus 4.6 --- references/core/dev-management.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/references/core/dev-management.md b/references/core/dev-management.md index 4515ae1..02f8708 100644 --- a/references/core/dev-management.md +++ b/references/core/dev-management.md @@ -2,13 +2,13 @@ ## Server Management -Before starting workers or workflows, you MUST start a local dev server, using the Temporal CLI: +Workers and workflows need a running Temporal Server. You can develop against a local dev server, a self-hosted cluster, or Temporal Cloud — the choice depends on your setup. If you need a local server, start one with the Temporal CLI: ```bash temporal server start-dev # Start this in the background. ``` -It is perfectly OK for this process to be shared across multiple projects / left running as you develop your Temporal code. +The dev server can be shared across projects and left running as you develop. The dev server is in-memory by default -- all workflows, schedules, and history are lost on restart. Use `--db-filename temporal.db` to persist across restarts.