twf-cli 0.10.1

Toolchain for designing and validating entire Temporal systems in .twf — CLI, language server, and MCP server.

twf-cli

Design, visualize, and implement entire Temporal systems — namespaces, workers, workflows, and Nexus — as a validated, visual source of truth.

Write your architecture in .twf and a real parser, language server, and visualizer give you (and your AI agent) compiler-grade feedback on the whole system before you write a line of SDK code — then generate the workers and provision the infra from the same design.

• Catch design errors before code. A real parser and language server validate the whole system — undefined activities, broken Nexus routing, misplaced determinism — while it's still a design, not a production incident.
• See the whole deployment. An interactive graph of namespaces → workers → workflows, plus a tree view that expands calls inline. Architecture you can actually look at.
• One parseable source of truth. .twf is a file every teammate and every tool reads and validates — not architecture prose buried in a prompt.
• Design → running system. Generate Temporal Go SDK code and provision control-plane infra from the same .twf — or recover a deployment graph straight from production history with twf graph --history.

activity ReserveFunds(amount: Money) -> (Hold):
    reserve(amount)

activity CaptureFunds(hold: Hold) -> (Receipt):
    capture(hold)

workflow ChargeOrder(order: Order) -> (Receipt):
    signal Cancel():
        close fail("cancelled")

    activity ReserveFunds(order.amount) -> hold
        options:
            start_to_close_timeout: 30s
    activity CaptureFunds(hold) -> receipt
    close complete(receipt)

worker billing:
    workflow ChargeOrder
    activity ReserveFunds
    activity CaptureFunds

namespace payments:
    worker billing
        options:
            task_queue: "billing"

Workflow logic, the worker that hosts it, and the namespace topology — one readable file.

twf-cli is a thin wrapper around the bundled platform binary — same tool, same flags, same output as the standalone twf distribution, installable via pip.

Install

pip install twf-cli
twf --help

The wheel for your platform ships the matching twf binary. Supported platforms (one wheel each): macosx_11_0_arm64, macosx_10_15_x86_64, manylinux2014_x86_64, manylinux2014_aarch64, win_amd64.

The twf CLI

A single Go binary: parser, validator, deployment-graph extractor, and a full LSP server. Every command and flag is discoverable via twf --help and twf <command> --help.

Command	Description
twf check <file...>	Parse and validate .twf files, reporting errors
twf parse <file...>	Output the AST as JSON (partial AST even with errors)
twf symbols <file...>	List workflows and activities with their signatures
twf graph <file...>	Emit the resolved deployment graph (nodes are deployments, edges are dispatches)
twf graph chunks <file...>	Decompose a design into independently-implementable chunks at contract boundaries
twf graph --history <dir>	Recover a deployment graph from sampled production histories — no .twf required
twf spec [--list | <slug>]	Print the embedded TWF language specification
twf mcp	Start the MCP server over stdio (agent entry point)
twf lsp	Start the language server over stdio

Common options: --json (structured output) and --lenient (continue past resolve errors). The language server adds real-time diagnostics, completions, hover, go-to-definition, references, rename, code actions, folding, inlay hints, semantic tokens, and signature help.

Use as an MCP server

twf mcp runs a Model Context Protocol server over stdio — the agent entry point. Point any MCP client (Claude Desktop, Cursor, Continue, Windsurf, Zed) at it:

{
  "mcpServers": {
    "twf": {
      "command": "npx",
      "args": ["-y", "@temporal-architect/twf", "mcp"]
    }
  }
}

The tools (twf_check, twf_parse, twf_symbols, twf_graph, twf_graph_chunks, twf_spec_list, twf_spec_get) are thin wrappers over the same parser pipeline as the CLI, so their JSON is identical. The embedded language specification is exposed as resources at twf://spec and twf://spec/<slug>.

Subprocess use from Python

import subprocess, json

result = subprocess.run(
    ["twf", "parse", "workflow.twf"],
    capture_output=True, text=True, check=True,
)
ast = json.loads(result.stdout)

Versioning

Versions track the upstream temporal-architect Git tag, so 0.3.x of this package corresponds to v0.3.x of the toolchain.

License

MIT. See LICENSE.