Tempurview

A CLI and TUI for viewing and managing Temporal workflows.

Tempurview gives you two interfaces to your Temporal cluster:

• CLI — scriptable commands for listing, inspecting, and acting on workflows. Outputs JSON (for pipes) or tables (for humans).
• TUI — an interactive terminal UI with real-time navigation, filtering, sorting, and operational insights.

Both interfaces share the same configuration and connect to Temporal via gRPC.

Quick start

cargo install tempurview

Connect to your cluster:

export TEMPORAL_ADDRESS="your-namespace.tmprl.cloud:7233"
export TEMPORAL_NAMESPACE="your-namespace"
export TEMPORAL_API_KEY="your-api-key"

# Launch the TUI
tpv

# Or use the CLI
tpv workflow list
tpv workflow get <workflow-id>
tpv insight scan --since 24h

Try it with mock data (no Temporal connection needed):

tpv --mock

Installation

From crates.io

cargo install tempurview

This installs two binaries: tempurview and tpv (short alias).

From source

git clone https://github.com/Tatch-AI/tempurview.git
cd tempurview
cargo install --path .

Verify

tpv --version
tpv test-connection

Configuration

Tempurview reads configuration from CLI flags, connection profiles, environment variables, and an optional config file.

Resolution priority

Connection parameters are resolved in this order (first wins):

1. CLI flags --address / --namespace — always win
2. Profile via --profile <name> or TEMPURVIEW_PROFILE env var
3. Default profile from default_profile in config.toml
4. Environment variables TEMPORAL_ADDRESS / TEMPORAL_NAMESPACE / TEMPORAL_API_KEY
5. Hard-coded defaults (localhost:7233, default, no API key)

When a profile is active, bare env vars (TEMPORAL_ADDRESS, etc.) do not override it. Only explicit --address/--namespace CLI flags win over a profile.

Connection profiles

Profiles let you save named connection targets in ~/.tempurview/config.toml and switch between them:

# Add profiles
tpv config profile-add local --address localhost:7233 --namespace default
tpv config profile-add cloud --address us-west1.gcp.api.temporal.io:7233 --namespace my-ns --api-key tctl_xxx

# List profiles
tpv config profile-list

# Set a default
tpv config set-default cloud

# Use a specific profile
tpv -p local workflow list        # CLI with local profile
tpv -p cloud                      # TUI with cloud profile
TEMPURVIEW_PROFILE=local tpv      # env var selection

# Override a profile's address
tpv -p local --address custom:9999 config show

The first profile added is automatically set as the default.

Config file format

default_profile = "cloud"

[profiles.cloud]
address = "us-west1.gcp.api.temporal.io:7233"
namespace = "my-namespace.abc123"
api_key = "tctl_..."

[profiles.local]
address = "localhost:7233"
namespace = "default"
# no api_key needed for local

[insights]
allowlist = ["expected error"]
concurrency = 50

Environment variables

You can also place these in a .env file in your working directory.

CLI flags

These override environment variables and profiles when provided:

tpv --address my-cluster:7233 --namespace production --limit 100

Config file

Tempurview reads ~/.tempurview/config.toml for profiles and additional settings.

[insights]
# Allowlist of workflow types to include in insight scans.
# If empty, all workflow types are scanned.
allowlist = ["OrderWorkflow", "PaymentWorkflow"]
concurrency = 50

CLI Overview

Run tpv (or tempurview) with a subcommand to use the CLI. Without a subcommand, the interactive TUI launches instead.

tpv <command> [options]

Commands

Output format

By default, output is auto-detected:

• Table when writing to a terminal (TTY)
• JSON when piped to another command

Override with --output json or --output table.

# Table output (default in terminal)
tpv workflow list

# JSON for scripting
tpv workflow list --output json

# Or just pipe it
tpv workflow list | jq '.[] | .workflow_id'

Workflows

List workflows

tpv workflow list [--status <STATUS>] [--workflow-type <TYPE>] [--since <TIME>] [--before <TIME>]

Filters

# Running workflows from the last 24 hours
tpv workflow list --status Running --since 24h

# All failed workflows of a specific type
tpv workflow list --status Failed --workflow-type PaymentWorkflow

Get workflow details

tpv workflow get <workflow-id> [--run-id <RUN_ID>]

If --run-id is omitted, the latest run is returned.

Count workflows

tpv workflow count [--status <STATUS>] [--query <QUERY>]

The --query flag accepts raw Temporal visibility queries.

Cancel a workflow

tpv workflow cancel <workflow-id> [--run-id <RUN_ID>]

Terminate a workflow

tpv workflow terminate <workflow-id> [--run-id <RUN_ID>] [--reason <REASON>]

The default reason is "Terminated via CLI".

Activities & Events

List activities

tpv activity list <workflow-id> [--run-id <RUN_ID>]

Shows all activities for a workflow execution, including status, type, attempt count, and timing.

List history events

tpv event list <workflow-id> [--run-id <RUN_ID>]

Shows the full event history for a workflow execution. Each event includes its type, timestamp, and event ID.

Insights

The insight scan command analyzes workflows for operational patterns and potential issues.

tpv insight scan [--since <TIME>] [--before <TIME>]

What it scans for

Tempurview runs 7 finding algorithms across your workflows:

List-level findings

• High failure rate — workflow types with an unusually high proportion of failures
• Repeated failures — the same workflow type failing repeatedly in a short window
• Long-running workflows — executions that have been running significantly longer than peers

Activity-level findings

• Retry storms — activities with a high number of retry attempts
• Slow activities — activities taking significantly longer than expected
• Repeated activity failures — the same activity failing across multiple workflows
• Timeout patterns — activities consistently hitting timeout limits

Examples

# Scan the last 24 hours
tpv insight scan --since 24h

# Scan a specific date range
tpv insight scan --since 2024-01-15 --before 2024-01-16

TUI Overview

Launch the interactive TUI by running tpv without a subcommand:

tpv

The TUI provides a navigable, real-time interface to your Temporal cluster. It follows vim-style keybindings throughout.

Views

The TUI has several interconnected views:

• Workflow List — the main view. Lists workflows with status, type, ID, and timing. Supports filtering, sorting, and date range selection.
• Workflow Detail — detailed info for a single workflow including input/output payloads, failure messages, and metadata.
• Activity List — activities for a workflow, with status and timing.
• Activity Detail — full JSON detail of a single activity with syntax highlighting and search.
• Event Log — the complete history event table for a workflow.
• Event Detail — full JSON detail of a single event with syntax highlighting and search.
• Type List — workflow types with counts broken down by status.
• Insights — operational findings from scanning workflows.
• Insight Detail — full detail of a single finding with affected entities, trigger term highlighting, and drill-through to workflows.

Navigation model

Views are arranged as a stack. Enter pushes a detail view, Esc pops back. The typical flow:

Workflow List → Workflow Detail → Activity List → Activity Detail
                     │
                     ├──→ Event Log → Event Detail
                     │
Workflow List → Type List
                     │
Workflow List → Insights → Insight Detail → Workflow Detail

Navigation

Movement

All list views use the same movement keys:

View transitions

Filtering

From the Workflow List:

Date range

Sorting

Then in Workflow List: s (status), t (type), w (workflow ID), d (date).

In Type List: t (type), n (total count), 1-7 (status column).

Views

Workflow List

The main view. Shows workflows in a scrollable table with columns for status, type, workflow ID, and start time.

Key actions:

• T — switch to Type List view
• I — run an Insights scan
• r — refresh data
• d — date range filter
• s — sort mode
• F1-F4 — toggle column visibility (Status, Type, Workflow ID, Started)

Workflow Detail

Shows full details for a selected workflow: status, type, task queue, input/output payloads, failure info, timing, and metadata.

Key actions:

• a — view activities
• l — view event log
• x — copy workflow URL to clipboard
• gx — open workflow in browser
• c — cancel workflow
• t — terminate workflow

Activity List

Lists activities for a workflow with status, type, attempt count, and timing.

Key actions:

• Enter — expand to Activity Detail

Activity Detail

Full-screen scrollable JSON view of an activity with syntax highlighting.

Key actions:

• / — search within JSON
• n / N — next / previous search match

Event Log

History events for a workflow in a table view, showing event type, timestamp, and event ID.

Key actions:

• Enter — expand to Event Detail

Event Detail

Full-screen scrollable JSON view of a history event with syntax highlighting.

Key actions:

• / — search within JSON
• n / N — next / previous search match

Type List

Workflow types with execution counts broken down by status. Selecting a type filters the Workflow List.

Insights

Operational findings from scanning workflows. Shows a list of findings with severity and description.

Key actions:

• r — re-scan
• Enter — expand to Insight Detail

Insight Detail

Full detail of a finding. Shows description, affected entities with trigger term highlighting, and links to individual workflows.

Key actions:

• n / p — next / previous affected entity
• Enter — drill into workflow detail

Keybindings

Complete keybinding reference for all TUI views and modes.

Global

All list views

Workflow List

Workflow Detail

Detail views (Activity, Event, Insight)

Insight Detail (additional)

Input modes

Filter / Search input

Date range selection

Sort selection (Workflow List)

Sort selection (Type List)