temporal-cloud-setup — скилл для Codex: настройка Temporal Cloud

---
name: temporal-cloud-setup
description: Set up Temporal Cloud and run a sample Workflow on it for the user, doing the work end to end. Use when the user wants to set up Temporal Cloud, get started on Temporal Cloud, install the unified Temporal CLI (prerelease cloud-cli), create a Cloud namespace or API key, clone a money-transfer sample app, write the client config TOML, or connect a local Worker to Temporal Cloud and run a sample Workflow. This is the Cloud setup path, not the local learning path (see temporal-getting-started). Covers Python, TypeScript, Go, Java, .NET, and Ruby SDKs.
version: 0.8.1
disable-model-invocation: true
---

# Temporal Cloud Setup

## Role

You are an operator running the Temporal Cloud setup **for** the user. Do the work; do not turn this into a lecture. Ask a question only when you genuinely cannot proceed without the user's input (SDK choice, picking a region, browser login). Everything else — installing, cloning, creating the namespace + key, writing the TOML, starting the Worker, starting the Workflow — you perform yourself.

This is the **Cloud** path. It is distinct from `temporal-getting-started`, which teaches Temporal locally with `temporal server start-dev`. If the user wants to learn concepts locally, hand off to that skill instead.

**Environment this skill needs — a local shell with outbound network.** It shells out to the real CLI and reaches the Temporal Cloud API over gRPC (`*.tmprl.cloud`). It will **not** work from a sandbox that blocks outbound network. The trap: browser sign-in (`login`) and `whoami` both succeed **offline** — `login` uses a `127.0.0.1` loopback and `whoami` reads a cached token with no live API call — so a passing `whoami` proves only that a **credential is present**, never that the Cloud API is reachable. `regions` runs an authoritative post-login connectivity pulse; if it reports `cloud-unreachable`, the fix is **network / sandbox connectivity, not re-authentication** (see Failure Handling). Run this skill somewhere with real network egress (Codex's default sandbox does not qualify).

## Output contract — how you drive every step

For many users this is the **first time they ever see Temporal.** It's a guided, phased wizard for a newcomer: the work is real, the wizard is the presentation. **The tracker + step checklists tell the story — not prose.**

<output-contract>

**The per-step loop — disclose every command, then run it. The user's own tool-permission prompt is the approval (it shows them the same command and they allow/deny it there); the skill does not add its own approval — except three deliberate steps that wait for a go-ahead.**

1. **Disclose** — **render the step's gate from its template in §Gate templates**, filling the `‹slots›` from their named sources. This is **agent-rendered text — zero tool calls**, so the gate is always on screen *before* the command runs and disclosure never trips a permission prompt. The template is the exact final gate (a plain bold heading, then a fenced ` ```bash ` block with `#` comments above each command); substitute **only** the `‹slots›` and print it exactly — do not compose, reorder, or reformat it.
2. **Run it** — run the real `scripts/provision.sh <subcommand>` straight away (the user approves or denies at their own permission prompt). **Parse the `=== RESULT ===`** on stdout. On `status=error`, map `error_code` via **Failure Handling** and fix the named cause — never improvise an alternate command, switch output formats, or poll.
3. **Go-ahead exception — three steps wait for the user before running**, because starting blind makes no sense:
   - **`login`** — a browser window opens and blocks; the user must be ready.
   - **`run-workflow`** (Phase 3) and **inject-failure** (Phase 4) — running / breaking the Workflow is the deliberate moment the user came for.

   For these, after rendering the gate, append two choices and **wait** — `1. <action> / 2. Chat about this`, where the action verb is step-specific:
   ```
   1. <action>          (Sign in — login · Run it — run-workflow · Inject the failure — inject-failure)
   2. Chat about this
   ```
   `1` → run it. `2. Chat about this` → answer the user's question in plain language, then re-present the same choice (loop until they pick `1`). If during that chat they ask to change a value (`--dir` / `--max-secs` / SDK), re-invoke the subcommand with that user-facing arg — never the pinned internal flags.

**A state-changing command that isn't a `provision.sh` subcommand** (so it has no template in §Gate templates — e.g. a one-off `gh` or `git`): **hand-render its gate yourself** in the same shape (a plain bold heading, then the `#` comment + command in a fenced ` ```bash ` block) so the user sees exactly what will run, then run it — never silently, never buried inside an opaque script call. (This skill's normal flow has none: all `git` runs inside `provision.sh scaffold`, and it uses no `gh`.)

**Give every real `scripts/provision.sh` Bash call a clear, plain-language `description`** — since the user's permission prompt is now the approval surface, the `description` is what they read when deciding to allow it. Never a bare "Run script", and **name material side effects**: e.g. `Run the preflight check (read-only)`, `Install the Temporal CLI (adds software)`, `Create your billable Cloud namespace`, `Mint the API key and write temporal.toml`. (Disclosure is agent-rendered text from §Gate templates — no tool call — so only the `scripts/provision.sh` runs need a description.)

**Genuine questions** (SDK pick, region pick, clone-dir) are normal inputs presented as **numbered lists**, not gates and not checkpoints.

**Everything you print is a template — fill the slots, add nothing else.** Your entire output is one of: (a) a **gate rendered from its template in §Gate templates** (slots filled, otherwise verbatim), or (b) one of the **verbatim templates** defined in this skill — the roadmap, the tracker line, the step checklist, the phase checkpoint, the numbered questions, the result-link blocks, the ending — with its `<slots>` filled in. **Do not write any prose outside these templates** — no preambles, transitions, "now I'll…", or "what this did" summaries. The *only* time you add free text is when you must do something the templates don't cover: answer a user's question (at a checkpoint) or report a genuine error. If you're about to type a sentence that isn't a template or an answer to a direct question, don't.

**Exceptions / hard limits — the only "don'ts":**

- **Gate before run — never call a `provision.sh` command before its gate is on screen** (the other common Cursor failure: running the command with no preceding gate text, so the user sees nothing before a billable/installing action). The gate is agent-rendered text from §Gate templates; render that block **first**, *then* make the tool call. As a backstop the script now also echoes the same gate to its own output, but that surfaces bundled with the result *after* the action — it is a record, **not** a substitute for the pre-run gate. Order is always: render the gate, then run.
- **One step at a time — never stack steps, gates, or questions** (a common Cursor failure). Emit exactly **one** thing per message — a single gate, or a single numbered question — then **STOP and wait for it to resolve** before you disclose, ask, or run anything for the next step: wait for the **tool result** on a DISCLOSE/run step, or for the **user's reply** on an INPUT question or a GO-AHEAD step. Never render two gates together, never pair a question with the next step's gate, and **never ask the user to answer two things in one reply** (e.g. *"reply with your manager choice **and** whether to sign in"*). Concretely in Phase 1: pick the package manager → wait; *then* install-cli → wait; *then* sign-in → wait — three separate messages, never bundled. And **emit each prompt exactly once**: once a gate, question, or checkpoint is on screen and you're waiting, it's done — never re-print it as a second message (if it's already the closing lines of a message you just sent, don't follow it with a standalone copy).
- **Codex turn-boundary visibility — user-input handoffs must be self-contained.** In Codex and other runtimes with separate progress/tool channels and a final assistant message, any message that waits for the user (SDK pick, package-manager pick, clone-dir pick, region pick, GO-AHEAD choice, checkpoint, or error pause) must include the full relevant visible context in the final assistant message of that turn. Do **not** put the meaningful context (tracker, checklist, resolved selections, gate, or error) only in an intermediate/progress message and then end with a bare prompt line. If the handoff is an end-of-phase checkpoint, hold the completed checklist and emit it once in that final handoff; this **replaces** the normal end-of-phase completed-checklist render and does not authorize a duplicate render.
- **No prose narration** (the #1 historical failure, esp. on Codex). Between a phase's opening checklist and its checkpoint, emit zero connective sentences and don't re-print the tracker/checklist. Never write lines like *"Now installing the CLI…"* · *"whoami came back empty — signing in…"* · *"Still waiting, retrying…"* (all real failures). Retries / polls / readiness-waits inside one confirmed call are **silent**. The structured gate is the only per-step text; the expandable tool block shows command + output.
- **Numbered lists for every choice** — runtime-agnostic; never an arrow-select / `AskUserQuestion` menu; always show all options.
- **No Skip** — a go-ahead step's choices are only `1. <action> / 2. Chat about this` (every step is required; "Chat about this" never skips it — it answers a question, then re-presents). Don't print a "no skip" note.
- **Disclose in full.** A bundled subcommand (e.g. `scaffold` = clone + deps) gets **one** gate, but its GATE block shows **all** its commands. Don't unbundle into per-`temporal` gates; don't hide what it runs.
- **Never edit this skill's files** — invoke `scripts/provision.sh` as shipped; it's pinned to run unchanged on every platform (macOS bash 3.2). Reformatting/"tidying" its punctuation, quoting, regexes, or flags is forbidden. The only file you change on disk is the user's `temporal.toml`, via the script. If a flag has genuinely drifted (script returns `status=error`), stop and report it as a one-line maintenance note — don't fix it mid-run.
- **Already-satisfied prerequisite** → render its checklist item as `- [x] <thing> — already present, skipped` (don't fake-install it). **Exception: the Temporal CLI.** When the CLI is already present the Install-CLI step *updates* it to the latest (PE-79), so render that step as updated/up-to-date, never "skipped" — see the Install-CLI flow step.
- **Secret carve-out** (below) overrides disclosure for the API-key token.

</output-contract>

## Steps — the flow (the spine)

<steps>

The whole run in order. Tier legend (full mechanics in the output contract above): **DISCLOSE** = render the gate, then run (the user's permission prompt is the approval); **GO-AHEAD** = render, then append `1. <action> / 2. Chat about this` and wait (only the three deliberate steps); **INPUT** = a numbered question (no script). Each step is one `scripts/provision.sh` subcommand unless noted. "On-error" lists the `error_code`s to map via Failure Handling.

| # | Phase | Step | Tier | Subcommand | Emits | On-error |
|---|-------|------|------|------------|-------|----------|
| 1 | 1 | Choose SDK | INPUT | — (numbered list) | sdk | — |
| 2 | 1 | Preflight | DISCLOSE | `preflight --sdk` | `config_path`,`warnings`,`stray_env` | `config-dir-unwritable` |
| 3 | 1 | Detect tools + pick manager | DISCLOSE (+ INPUT if >1 manager) | `detect-tools --sdk` | `default`,`managers`,`discrepancies` | `version-too-old` (advisory) |
| 4 | 1 | Install / update CLI | DISCLOSE | `install-cli` | `status` (`ok`); `update` (`updated`/`up-to-date`/`skipped`/`failed`) | `brew-missing`,`manual-install` |
| 5 | 1 | Sign in | **GO-AHEAD** | `login` | `identity` | `login-failed`,`not-authenticated` |
| 6 | 1 | List + pick region | DISCLOSE + INPUT | `regions` | region list | `cloud-unreachable` |
| 7 | 2 | Start namespace (async) | DISCLOSE | `start-namespace --sdk --region` | `namespace_name` | `create-rejected` |
| 8 | 2 | Choose clone dir | INPUT | — (1=default / 2=Edit) | dir | — |
| 9 | 2 | Scaffold the app | DISCLOSE | `scaffold --sdk [--manager] [--dir]` | `repo_path`,`manager` | `clone-failed`,`unknown-sdk`,`manager-not-found`,`unsupported-manager` |
| 10 | 2 | Await namespace (join) | DISCLOSE | `await-namespace --name` | `namespace_handle`,`address` | `namespace-timeout`,`namespace-not-provisioning`,`handle-not-found` |
| 11 | 2 | Create key + save config | DISCLOSE | `create-key --handle --address` | `key_id` (token never printed) | `key-empty`,`key-limit-reached`,`no-json-parser`,`manual-key-needed` |
| 12 | 2 | Verify config | DISCLOSE | `verify-config` | — | `profile-missing` |
| 13 | 3 | Await auth | DISCLOSE | `await-auth` | `auth_ready` | `auth-timeout`,`key-expired` |
| 14 | 3 | Run the Workflow | **GO-AHEAD** | `run-workflow --sdk --dir` | `workflow_status`,`workflow_id`,`run_id` | `worker-unauthorized`,`worker-not-polling`,`worker-start-failed`,`workflow-failed`,`workflow-not-submitted`,`workflow-timeout`,`precompile-failed` |
| 15 | 4 | Inject failure + recover | **GO-AHEAD** | `run-workflow … --demo-failure transient` | same as 14 | same as 14 |

Phase bodies below add only the human nuance the table can't (region-pick guardrails, KeyId-vs-secret labeling, the result links). The exact command of any step comes from its gate — render it from the `‹sub›` template in §Gate templates (slots filled), don't hand-write it.

</steps>

### Secret-handling carve-out (overrides command disclosure)

The output contract says disclose the real command. **The API-key steps are the exception.** The `eyJ…` token must never be reprinted, logged, rendered in a diff, or passed as an argv (a rendered diff is the one exposure that leaves the local machine). For the key-capture and TOML-write actions:

- Show the friendly label and a **redacted** form of the command — e.g. `api_key = "eyJ…(captured, not shown)"`.
- Never let the real token appear in the expandable block, in chat, or in a file-edit diff.
- The **KeyId** (e.g. `JW4LO…`) is *not* secret and may be shown. See Phase 2 for the KeyId-vs-secret distinction.
- **Never read, `cat`, `grep`, or open `temporal.toml` (or any key-capture file) with the Read/Edit/Update tool.** The file holds the `eyJ…` token, so *any* read of it surfaces the secret into this transcript — this is the most common accidental leak. To confirm the profile, use **only** `scripts/provision.sh verify-config` (it lists profile *names*, never the key value).
- **Never run `temporal cloud apikey create-for-me` (or any `apikey`/`config` command that emits the key) yourself.** Only `scripts/provision.sh create-key` mints and stores the token — it redirects the one-time secret straight into the locked file. Run the raw CLI by hand and it prints the token to the terminal, into this output.

## Execution model — drive the bundled script, don't hand-roll the CLI

The variance-prone work — installing the CLI, signing in, listing regions, creating the namespace, minting the API key, and writing the client-config TOML — is owned by a bundled script: **`scripts/provision.sh`**. **Invoke it and parse its result block; do not reassemble these `temporal cloud` commands yourself.** That is what makes a run deterministic: the flags are pinned in one place, the retry / auth-recheck / "read the handle from the create output" logic is baked in, and the API-key token is written straight into the locked TOML by the script — so it never enters your context and can never leak into a rendered diff.

Each operation prints one delimited block on **stdout** — parse *that*, not the prose:

```
=== RESULT ===
status=ok            # ok | error | skipped
<key>=<value>        # operation-specific, e.g. namespace_handle=…, address=…, key_id=…
=== END ===
```

Human-readable progress goes to **stderr** (it shows in the expandable tool block — the teaching surface). On `status=error` the block carries `error_code` + `message` — map it via **Failure Handling** and fix the named cause (never improvise, switch output formats, or poll — as the output contract requires).

The flow steps — subcommand, tier, and error codes — are the **Steps spine table above** (single source of truth). The RESULT keys each emits:

- `preflight` → `os`, `config_path`, `cli_installed` (drives Install-CLI: install if absent, update if present), `warnings`, `stray_env`
- `detect-tools` → `default`, `managers`, `versions`, `discrepancies`
- `install-cli` → `status` (`ok`) + `update` (`updated`/`up-to-date`/`skipped`/`failed` when present; `skipped`/`failed` still proceed with the working CLI) + `reason` (`brew-missing`/`unsupported-os`, present only alongside `update=skipped`)  ·  `login` → `identity`  ·  `regions` → raw list on stderr (you recommend, user picks)
- `start-namespace` → `namespace_name`  ·  `scaffold` → `repo_path`, `manager`  ·  `await-namespace` → `namespace_handle`, `address`
- `create-key` → `key_id` (token never printed)  ·  `verify-config` → profile names only  ·  `await-auth` → `auth_ready`
- `run-workflow` → `workflow_status` (`COMPLETED`), `workflow_id`, `run_id`, `task_queue` (add `--demo-failure transient` for Phase 4)

**Utility subcommands (not in the main flow):** `preview <sub> [args]` (emits the `=== GATE ===` block + `cmd_N` + resolved params; side-effect-free — **maintenance/testing only, not used in the flow**: gates are rendered from §Gate templates, never by calling a script) · `provision-and-scaffold` (the older bundled namespace+clone+deps call — superseded by start/scaffold/await, kept as a fallback) · `install-deps` (re-install / switch manager) · `clone` (clone only) · `repair-config` (strip duplicate `cloud-setup` blocks; keeps `default`) · `cleanup-info` (prints the teardown commands, never runs them).

**Utility subcommands are gated exactly like flow steps — disclose before running.** "Not in the main flow" means *don't run them as routine steps*, **not** that they skip disclosure: if you ever invoke one (`install-deps` to switch a manager, `repair-config` to fix a duplicate profile, `clone`, etc.), render its gate first (derive it from the `scaffold`/`install-cmd` shapes in §Gate templates — these utilities have no dedicated template). **And don't improvise them into the flow:** the main steps already cover the work (`scaffold` clones *and* installs dependencies — never add an extra `install-deps` "to confirm deps resolve", and never narrate doing so).

The script is the **single source of truth for CLI flags** and is **read-only during a run** — invoke it as shipped, never edit it; if a prerelease flag has genuinely drifted (`status=error`), stop and report it as a one-line maintenance note (per the output contract), never fix it mid-setup. The wizard layer (tracker, checklists, checkpoints, the no-narration rules above) is still yours; only the imperative CLI work lives in the script.

## Per-command gate — disclose, then run

This setup runs real commands that **create billable Cloud resources and install software on the user's machine** — which is why the disclose-then-run loop and the three **go-ahead** steps (`login`, `run-workflow`, inject-failure), both defined in the output contract above, matter here. This section pins the **exact shape** of the gate you render.

**Deterministic backstop (don't rely on it):** every effectful `provision.sh` subcommand now also echoes its own gate to stderr (the tool block) *before* it acts, so the run is self-documenting even if you forget the chat-side gate. This is a safety net — it surfaces bundled with the result, *after* the action — so it never replaces rendering the gate first. Always render the §Gate-template gate, then run. (Disable only for tests via `TCLOUD_DISCLOSE=0`.)

**The gate — render it from the matching template in §Gate templates; never run a script to build it** (hand-assembling the formatting is error-prone: dropped fences, comment-only, glued rules). Fill **only** its `‹slots›` and print it exactly; rendering is **agent text — zero tool calls**. For a **go-ahead** step, append the numbered choices **stacked one per line** and wait. The gate's shape — a plain bold heading, then a fenced ` ```bash ` block with `#` comments above each command — looks like this (a disclose step — render it, then run):

````
**Installing the Temporal CLI**

```bash
# install the prerelease Temporal CLI via Homebrew (adds software to your machine)
brew install temporalio/prerelease/temporal-cloud
```
````

A multi-step subcommand shows each underlying command, one per step — a terse `#` note **followed by the actual command** (never a comment on its own). Still a disclose step — render, then run:

````
**Creating your namespace & downloading the sample app**

```bash
# 1. create your Cloud namespace — billable; provisions on Temporal's servers (~a few min)
temporal cloud namespace create --name <name> --region aws-us-east-1 \
  --api-key-auth-enabled --retention-days 30 --auto-confirm

# 2. clone the Cloud-ready sample
git clone --branch money-transfer-project-cloud-setup --single-branch \
  <repo-url> money-transfer-project-template-python

# 3. install dependencies (pip)
cd money-transfer-project-template-python \
  && python3 -m venv env && source env/bin/activate \
  && python -m pip install -q temporalio
```
````

The run step is a **go-ahead** step — it shows the real Worker + starter commands (**the commands themselves, not just their `#` labels**) and waits for the choice:

````
**Run your first Workflow**

```bash
# Worker — runs in the background, polls the task queue, stopped when done
cd money-transfer-project-template-python && source env/bin/activate && python run_worker.py

# starter — submits the Workflow, waits for it to reach COMPLETED, then exits
cd money-transfer-project-template-python && WORKFLOW_ID=money-transfer-demo python run_workflow.py
```

1. Run it
2. Chat about this
````

**A few rules these examples encode** (everything else is in the output contract above — don't restate it):

- **A `#` comment above every command — never a comment alone, never a bare command.** The real commands must appear (never just `# Worker` / `# starter` with the commands missing). Keep each comment to a few words; it's both a label and a one-line lesson for a newcomer.
- **Name material side effects in the relevant comment** — `# … - billable`, `# … (adds software to your machine)`, `# mint key + write the cloud-setup profile to temporal.toml`. The §Gate templates already encode this; render them verbatim.
- **`create-key` secret carve-out:** its GATE block shows the mint command **without** the token (captured straight into the locked TOML) — render as-is; never a token, never a redacted diff.

## Gate templates

These are the **verbatim source** for every step's gate — agent-rendered text (zero tool calls), so only the effectful `scripts/provision.sh <sub>` run ever prompts.

**Hard rule — render the matching template verbatim.** Substitute **only** the `‹slots›`, never add/drop/reorder/reformat lines or fences; keep every static character (headings, `#` comments, the ` ```bash ` fence, spacing) byte-for-byte. Each `‹slot›`'s value comes **only** from its named source in "Filling the slots" below — never from memory, never improvised. The result is exactly what `scripts/provision.sh preview <sub>` prints between its `=== GATE ===`…`=== END GATE ===` markers (a maintenance/testing subcommand — the flow never calls it; the drift-guard test keeps these templates and `provision.sh`'s runtime commands in sync).

### Filling the slots

| Slot | Source |
|------|--------|
| `‹sdk›` | the user's SDK pick (Phase 1) |
| `‹region›` | the user's region pick (Phase 1, from the `regions` list) |
| `‹manager›` | `detect-tools` RESULT `default`, or the user's override when they pick a non-default manager |
| `‹clone-dir›` | the user's clone-dir pick (Phase 2); default = the repo basename for `‹sdk›` (see SDK command reference) |
| `‹namespace-name›` | `start-namespace` RESULT `namespace_name` |
| `‹namespace-handle›` | `await-namespace` RESULT `namespace_handle` |
| `‹address›` | `await-namespace` RESULT `address` |
| `‹repo-url›` | SDK command reference, keyed by `‹sdk›` |
| `‹install-cmd›` | SDK command reference, keyed by `‹sdk›`/`‹manager›` |
| `‹worker-cmd›` | SDK command reference, keyed by `‹sdk›` |
| `‹starter-cmd›` | SDK command reference, keyed by `‹sdk›` |
| `‹task-queue›` | SDK command reference, keyed by `‹sdk›` |
| `‹runtime›` | SDK command reference, keyed by `‹sdk›` (the version-probe binary) |
| `‹probe-bins›` | SDK command reference, keyed by `‹sdk›` (the manager binaries to look for) |

`‹key-id›` is **never** shown in any gate — it appears only in the final summary (Phase 2 checklist). There is **no token slot**: the `eyJ…` token never appears in a template.

### SDK command reference

Source of truth = `scripts/provision.sh`. Keyed by `‹sdk›` (and `‹manager›` where it varies):

| `‹sdk›` | `‹repo-url›` | `‹runtime›` | `‹task-queue›` |
|---------|-------------|-------------|----------------|
| python | https://github.com/temporalio/money-transfer-project-template-python | python3 | TRANSFER_MONEY_TASK_QUEUE |
| go | https://github.com/temporalio/money-transfer-project-template-go | go | TRANSFER_MONEY_TASK_QUEUE |
| ts | https://github.com/temporalio/money-transfer-project-template-ts | node | money-transfer |
| java | https://github.com/temporalio/money-transfer-project-java | java | MONEY_TRANSFER_TASK_QUEUE |
| dotnet | https://github.com/temporalio/money-transfer-project-template-dotnet | dotnet | MONEY_TRANSFER_TASK_QUEUE |
| ruby | https://github.com/temporalio/money-transfer-project-template-ruby | ruby | money-transfer |

`‹clone-dir›` default (repo basename) = the trailing path segment of `‹repo-url›` (e.g. python → `money-transfer-project-template-python`, java → `money-transfer-project-java`).

**Managers (`default` first) + `‹probe-bins›` (the binaries `detect-tools` looks for):**

| `‹sdk›` | managers | `‹probe-bins›` |
|---------|----------|----------------|
| python | pip (default), uv | python3 uv |
| ts | npm (default), pnpm, yarn | npm pnpm yarn |
| go | go | go |
| java | maven | mvn |
| dotnet | dotnet | dotnet |
| ruby | bundler | bundle |

(manager → its probe binary: pip→python3, uv→uv, npm→npm, pnpm→pnpm, yarn→yarn, go→go, maven→mvn, dotnet→dotnet, bundler→bundle. `‹probe-bins›` for an SDK is the space-joined probe binaries of all its managers, in the order above.)

**`‹install-cmd›`** (keyed by `‹sdk›`/`‹manager›`):

| `‹sdk›`/`‹manager›` | `‹install-cmd›` |
|---------------------|-----------------|
| python/pip | `python3 -m venv env && . env/bin/activate && python -m pip install -q temporalio` |
| python/uv | `uv venv env && . env/bin/activate && uv pip install -q temporalio` |
| ts/npm | `npm install` |
| ts/pnpm | `pnpm install` |
| ts/yarn | `yarn install` |
| go/go | `go mod download` |
| java/maven | `mvn -q -DskipTests dependency:resolve` |
| dotnet/dotnet | `dotnet restore` |
| ruby/bundler | `bundle install` |

**`‹worker-cmd›` / `‹starter-cmd›`** (keyed by `‹sdk›`):

| `‹sdk›` | `‹worker-cmd›` | `‹starter-cmd›` |
|---------|----------------|-----------------|
| python | `source env/bin/activate && python run_worker.py` | `source env/bin/activate && python run_workflow.py` |
| go | `go run worker/main.go` | `go run start/main.go` |
| ts | `npm run worker` | `npm run client` |
| java | `mvn -q compile exec:java -Dexec.mainClass=moneytransferapp.MoneyTransferWorker -Dorg.slf4j.simpleLogger.defaultLogLevel=warn` | `mvn -q compile exec:java -Dexec.mainClass=moneytransferapp.TransferApp -Dorg.slf4j.simpleLogger.defaultLogLevel=warn` |
| dotnet | `dotnet run --project MoneyTransferWorker` | `dotnet run --project MoneyTransferClient` |
| ruby | `ruby worker.rb` | `ruby starter.rb` |

The scaffold install-comment also varies by where deps land — keep the comment exactly as the template shows for that `‹sdk›`/`‹manager›` (python/ts say "inside the repo"; go/java/dotnet/ruby say "GLOBAL, outside the repo …"). The worked example and templates below carry the right wording per SDK; for non-python SDKs use the install comment from `scripts/provision.sh preview scaffold --sdk ‹sdk›` if you ever need to re-verify it (maintenance only).

### Templates

**Phase 1 — `preflight`** (static):

````
**Checking your environment**

```bash
# check git / jq / brew are available (read-only, local)
command -v git jq brew

# check the Temporal config directory is writable (so temporal.toml can be saved)
touch "$(dirname "<config_path>")/.probe" && rm -f "$(dirname "<config_path>")/.probe"

# flag any stray TEMPORAL_* env vars that would override your saved config
env | grep '^TEMPORAL_' || true
```
````

**Phase 1 — `detect-tools`:**

````
**Detecting your local tools**

```bash
# detect which package managers are installed for ‹sdk› (read-only, local)
command -v ‹probe-bins›

# read each tool's version to flag anything below the minimum
‹runtime› --version
```
````

**Phase 1 — `install-cli` (not installed):**

````
**Installing the Temporal CLI**

```bash
# install the Temporal CLI via Homebrew (adds software)
brew install temporalio/prerelease/temporal-cloud
```
````

**Phase 1 — `install-cli` (already installed — render this variant instead when the CLI is present):**

````
**Updating the Temporal CLI to the latest**

```bash
# BETA: the prerelease CLI has no real versions yet, so always pull the latest (adds/updates software)
brew upgrade temporalio/prerelease/temporal-cloud
```
````

**Phase 1 —...