Metadata-Version: 2.5
Name: twf-cli
Version: 0.14.0
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.14.0/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 the sampler.

```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 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. The examples below launch it through `npx`, so Node.js and npm must be installed and `npx` must be available on `PATH`.

### Claude Desktop

Add the `twf` entry to the existing `mcpServers` object in the [Claude Desktop configuration file](https://modelcontextprotocol.io/docs/develop/connect-local-servers):

- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`

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

Restart Claude Desktop after saving the file.

### Cursor

Create `.cursor/mcp.json` in a project to enable `twf` for that project, or use `~/.cursor/mcp.json` to enable it globally. Both locations use the same [Cursor MCP configuration shape](https://cursor.com/docs/context/mcp):

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

### Continue

Create `.continue/mcpServers/twf.yaml` at the top level of the workspace. Continue's [standalone MCP blocks](https://docs.continue.dev/customize/deep-dives/mcp) require the `name`, `version`, and `schema` metadata fields:

```yaml
name: TWF MCP server
version: 0.0.1
schema: v1
mcpServers:
  - name: 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).
