TemPurview is both an executable binary that can be run, and a library that can be used in Rust programs.

Installing `tempurview` `tpv` executables

Assuming you have Rust/Cargo installed, run this command in a terminal:

cargo install tempurview

It will make tempurview tpv commands available in your PATH if you've allowed the PATH to be modified when installing Rust. cargo uninstall tempurview uninstalls.

Adding `tempurview` library as a dependency

Run this command in a terminal, in your project's directory:

cargo add tempurview

To add it manually, edit your project's Cargo.toml file and add to the [dependencies] section:

tempurview = "0.16.0"

The tempurview library will be automatically available globally. Read the tempurview library documentation.

Back to the crate overview.

Readme

TemPurview

Your purview into what your Temporal workflows are doing.

TemPurview TUI demo

Why TemPurview?

Temporal's web UI shows you individual workflows. TemPurview gives you fleet-level visibility -- scan hundreds of workflows for retry storms, failure hotspots, and stuck executions in seconds. Everything is keyboard-driven, pipe-friendly, and designed to slot into the same terminal where you already live.

Feature Highlights

	Feature	Description
Fleet Insights	11 finding algorithms	Detect retry storms, failure hotspots, stuck workflows, queue latency, long-running activities, child workflow issues, and more
CLI Pipelines	JSON-as-API	Output auto-detects TTY vs pipe; compose with `jq`, shell scripts, and AI agents
TUI Navigation	9 views, keyboard-driven	Status filters, date ranges, column toggles, sort modes, full-text search
Web UI	`tpv serve`	Browser-based dashboard backed by the same gRPC client

Install

cargo install tempurview

The binary is available as both tempurview and tpv.

Quick Start

Connect to Temporal Cloud

# Option 1: Use connection profiles (recommended)
tpv config profile-add cloud \
  --address your-namespace.tmprl.cloud:7233 \
  --namespace your-namespace \
  --api-key your-api-key

tpv                              # TUI with default profile
tpv -p cloud workflow list       # CLI with named profile

# Option 2: Use environment variables
export TEMPORAL_ADDRESS="your-namespace.tmprl.cloud:7233"
export TEMPORAL_NAMESPACE="your-namespace"
export TEMPORAL_API_KEY="your-api-key"

tpv workflow list
tpv insight scan --since 24h

Multiple environments

tpv config profile-add cloud --address cloud.temporal.io:7233 --namespace prod
tpv config profile-add local --address localhost:7233 --namespace default

tpv -p local                     # TUI against local
tpv -p cloud workflow list       # CLI against cloud
tpv config set-default cloud     # set cloud as default

Try it without a connection

tpv --mock

Use a config file

Create ~/.tempurview/config.toml:

default_profile = "cloud"

[profiles.cloud]
address = "your-namespace.tmprl.cloud:7233"
namespace = "your-namespace"
api_key = "your-api-key"

[profiles.local]
address = "localhost:7233"
namespace = "default"

[insights]
allowlist = ["PaymentWorkflow", "OrderProcessing"]

Command Showcase

CLI output is table in a terminal, JSON when piped. Force a format with --output json or --output table.

# Find your noisiest failing workflow types
tpv workflow list --status failed -o json \
  | jq '.[] | .workflow_type' | sort | uniq -c | sort -rn

# Surface critical findings from the last 2 hours
tpv insight scan --since 2h -o json \
  | jq '.findings[] | select(.severity == "critical")'

# Quick count of running workflows
tpv workflow count --status running

# View activities for a specific execution
tpv activity list <workflow-id>

# Test your connection
tpv test-connection

Shell Completions

# Bash
tpv completions bash > ~/.local/share/bash-completion/completions/tpv

# Zsh
tpv completions zsh > ~/.zfunc/_tpv

# Fish
tpv completions fish > ~/.config/fish/completions/tpv.fish

Configuration

Configuration is resolved in priority order: CLI flags > profile > env vars > defaults.

Variable	Default	Description
`TEMPORAL_ADDRESS`	`localhost:7233`	Temporal server address
`TEMPORAL_NAMESPACE`	`default`	Temporal namespace
`TEMPORAL_API_KEY`	--	API key for Temporal Cloud
`TEMPURVIEW_PROFILE`	--	Connection profile name
`TEMPORAL_TUI_REFRESH_INTERVAL`	`30`	Auto-refresh interval in seconds
`TEMPORAL_TUI_DEFAULT_LIMIT`	`50`	Max workflows to fetch per page
`TEMPORAL_TUI_TICK_RATE`	`250`	TUI tick rate in milliseconds

Connection profiles (tpv config profile-add) let you save and switch between environments. Use -p <name> or TEMPURVIEW_PROFILE to select a profile. Run tpv config show to see the resolved configuration.

TUI Keybindings

Key	Action	Context
`j` / `k`	Move down / up	All list views
`g` / `G`	Go to top / bottom	All views
`Ctrl+D` / `Ctrl+U`	Half-page down / up	All views
`PgUp` / `PgDn`	Page up / down	All views
`Enter`	Select / view details	List views
`Esc`	Go back	All views

Filtering

Key	Action	Context
`/`	Open filter/search input	WorkflowList, TypeList, detail views
`1`-`7`	Filter by status (Running, Completed, Failed, Canceled, Terminated, TimedOut, ContinuedAsNew)	WorkflowList
`0`	Clear all filters	WorkflowList
`]` / `[`	Next / previous status filter	WorkflowList
`d`	Enter date range mode	WorkflowList, TypeList
`n` / `N`	Next / previous search match	Detail views

Date Range (after pressing `d`)

Key	Action
`1`-`6`	Preset: 1h / 6h / 24h / 3d / 7d / 30d
`0`	Clear date range
`c`	Custom input (e.g. `2h`, `3d`, `1w`)

Views

Key	Action	Context
`T`	Workflow Types view	WorkflowList
`I`	Health Insights scan	WorkflowList
`a`	Activities	WorkflowDetail
`l`	Event log	WorkflowDetail
`s`	Enter sort mode	WorkflowList, TypeList

Column Visibility

Key	Action
`F1`	Toggle Status column
`F2`	Toggle Type column
`F3`	Toggle Workflow ID column
`F4`	Toggle Started column

Actions

Key	Action	Context
`r`	Refresh data / re-scan	All views
`x`	Copy workflow URL	WorkflowDetail
`gx`	Open workflow in browser	WorkflowDetail
`c`	Cancel workflow	WorkflowDetail
`t`	Terminate workflow	WorkflowDetail
`?`	Toggle help overlay	All views
`q`	Quit (press twice)	Global

Insight Detail

Key	Action
`n` / `p`	Next / previous affected entity
`Enter`	Drill into workflow detail

Architecture

TemPurview follows The Elm Architecture (TEA): every keypress produces an Action, the update function returns Effects, and side effects run asynchronously through a CLI worker. The same gRPC client powers the TUI, CLI, and web server.

See the design docs for slide decks on philosophy, architecture, and CLI design.

Contributing

See CONTRIBUTING.md for setup, development workflow, and project structure.

git clone https://github.com/Tatch-AI/tempurview.git
cd tempurview
git config core.hooksPath hooks
cargo install --path . --force --quiet

Documentation

mdBook docs -- configuration, CLI reference, TUI guide
Design docs -- Marp slide decks on philosophy, architecture, and CLI design

Built With

Crate	Role
tokio	Async runtime
ratatui	Terminal UI framework
tonic	gRPC client
axum	Web server
clap	CLI argument parsing
comfy-table	Table output formatting
serde	Serialization

License

MIT

Installing tempurview tpv executables

Adding tempurview library as a dependency

Installing `tempurview` `tpv` executables

Adding `tempurview` library as a dependency