temporal-export

A CLI tool to query and analyze Temporal workflow export data from AWS S3.

Overview

temporal-export helps you work with Temporal's export feature by:

• Pulling workflow history from your S3 export bucket
• Decoding protobuf format into a queryable local database (DuckDB)
• Providing simple commands to list, search, and analyze workflows

Perfect for debugging historical workflows, analyzing patterns, and creating reports without querying your live Temporal cluster.

Installation

# Using go install
go install github.com/ayushmudgal/temporal-export/cmd/temporal-export@latest

# From source
git clone https://github.com/ayushmudgal/temporal-export
cd temporal-export
go install ./cmd/temporal-export

Quick Start

# 1. Initialize configuration (interactive)
temporal-export init

# 2. Pull workflow data from S3
temporal-export pull

# 3. List workflows
temporal-export list

# 4. Search for specific workflows
temporal-export list --workflow-id "payment-123"

# 5. View workflow history (compact mode recommended)
temporal-export history --workflow-id "payment-123" --compact

# 6. View statistics
temporal-export stats

Common Commands

List Workflows

# List all workflows
temporal-export list

# Search by workflow ID (partial matching)
temporal-export list --workflow-id "ReservationPayment"

# Filter by status
temporal-export list --status FAILED
temporal-export list --status CONTINUED_AS_NEW

# Combine filters
temporal-export list --workflow-id "payment" --status FAILED --namespace production

# Pagination
temporal-export list --limit 50 --offset 50

View History

# View workflow history (compact mode hides WorkflowTask events)
temporal-export history --workflow-id "my-workflow" --compact

# View specific run (for CONTINUED_AS_NEW workflows)
temporal-export history --workflow-id "my-workflow" --run-id "abc123" --compact

Pull Data

# Pull last 7 days (default)
temporal-export pull

# Pull specific time range (simple date format)
temporal-export pull --from 2024-11-05 --to 2024-11-15

# Pull specific time range (RFC3339 format)
temporal-export pull --from "2025-11-20T00:00:00Z" --to "2025-11-21T00:00:00Z"

Statistics

# Overall stats
temporal-export stats

# Stats for date range
temporal-export stats --from "2025-11-22" --to "2025-11-23"

Key Features

• Workflow Search: Search by ID, status, type, or namespace with partial matching
• Rich History View:
  • Full timestamps with date and timezone
  • Workflow inputs, signal payloads, and activity retry information
  • Continue-as-new chain tracking
  • Color-coded events (signals, retries, completion states)
  • Clean, compact mode without task noise
• CONTINUED_AS_NEW Support: Track continuation chains with next run IDs
• Pagination: Handle large result sets efficiently
• Local Querying: Fast queries against local DuckDB database
• No Truncation: Full workflow IDs, run IDs, types, and payloads visible

Available Filters

Filter	Example
--workflow-id	--workflow-id "payment-123"
--status	--status FAILED
--type	--type OrderWorkflow
--namespace	--namespace production
--from / --to	--from "2025-11-20T00:00:00Z"
--limit / --offset	--limit 50 --offset 50

Status values: COMPLETED, FAILED, RUNNING, CONTINUED_AS_NEW, CANCELED, TERMINATED, TIMED_OUT

Configuration

Configuration is stored in ~/.temporal-export-config.yaml:

aws:
  region: us-west-2
  s3_bucket: my-temporal-exports
  namespaces:
    - production
    - staging
storage:
  duckdb_path: ./temporal_exports.duckdb
defaults:
  days_back: 7

AWS Authentication

Uses standard AWS credential resolution:

• Environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY)
• AWS credentials file (~/.aws/credentials)
• IAM roles (EC2/ECS)
• AWS SSO

Documentation

For detailed documentation, see:

• DOCS.md - Complete command reference, examples, and troubleshooting
• ARCHITECTURE.md - Core architecture, data flow, and design decisions

Topics covered:

• Command reference with all options
• Working with CONTINUED_AS_NEW workflows
• Advanced filtering examples
• System architecture and component design
• Data flow and performance characteristics
• Development and building

Contributing

Contributions welcome! Please open an issue or PR.

---

Built for the Temporal community 🚀