Metadata-Version: 2.4
Name: twf-cli
Version: 0.10.2
Summary: Toolchain for designing and validating entire Temporal systems in .twf — CLI, language server, and MCP server.
Project-URL: Homepage, https://github.com/jmbarzee/temporal-architect
Project-URL: Source, https://github.com/jmbarzee/temporal-architect-dist
Project-URL: Issues, https://github.com/jmbarzee/temporal-architect-dist/issues
Author: Jamie Barzee
License: MIT
Keywords: architecture,cli,lsp,mcp,system design,temporal,twf,workflow
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# 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.

![Graph View — the whole system as a force-directed graph of namespaces, workers, and workflows with dependency edges](https://raw.githubusercontent.com/jmbarzee/temporal-architect/v0.10.2/docs/images/graph-view-system.png)

- **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`.

```twf
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

```bash
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](https://modelcontextprotocol.io) server over stdio — the agent entry point. Point any MCP client (Claude Desktop, Cursor, Continue, Windsurf, Zed) at it:

```json
{
  "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

```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](https://github.com/jmbarzee/temporal-architect/blob/main/LICENSE).
