README.md

TermStack Documentation

Complete documentation for building config-driven Terminal User Interfaces with TermStack.

---

📚 Quick Navigation

Getting Started

• Main README - Project overview and quick start
• Installation - Download and install TermStack
• Your First TUI - 30-second tutorial

Guides

• ⭐ Authentication Guide - HTTP APIs & CLI authentication
• ⭐ Templates & Context - Template syntax, variables, navigation
• Configuration - YAML configuration overview

Cookbook (Real Examples)

• ⭐ GitHub API Browser - Complete GitHub integration
• ⭐ AWS CLI Integration - S3, EC2, Lambda dashboards
• Kubernetes Dashboard - k9s-style interface
• Dog API Browser - REST API example

Reference

• Configuration Schema - Complete YAML reference
• Keybindings - All keyboard shortcuts
• Template Filters - Built-in filters
• Technical Specification - Architecture details

---

🔑 Authentication Quick Reference

HTTP APIs (Bearer Token)

globals:
  api_token: "{{ env.GITHUB_TOKEN }}"

pages:
  repos:
    data:
      adapter: http
      url: "https://api.github.com/user/repos"
      headers:
        Authorization: "Bearer {{ api_token }}"

export GITHUB_TOKEN="ghp_your_token"
termstack config.yaml

HTTP APIs (API Key)

headers:
  X-API-Key: "{{ env.API_KEY }}"

CLI Tools (Automatic)

# kubectl inherits ~/.kube/config automatically
data:
  adapter: cli
  command: "kubectl"
  args: ["get", "pods", "-o", "json"]

CLI Tools (Custom Env)

data:
  adapter: cli
  command: "aws"
  args: ["s3", "ls"]
  env:
    AWS_PROFILE: "production"
    AWS_REGION: "us-west-2"

→ See Full Authentication Guide

---

🚀 Quick Start

Installation

# Download binary or build from source
cargo build --release

# Run example
termstack examples/dog-api.yaml

Hello World

version: v1

app:
  name: "My First TUI"

start: main

pages:
  main:
    title: "Hello, TermStack!"
    data:
      adapter: cli
      command: "echo"
      args: ['[{"message": "Welcome!", "status": "awesome"}]']
      items: "$[*]"
    view:
      type: table
      columns:
        - path: "$.message"
          display: "Message"
        - path: "$.status"
          display: "Status"

---

📖 Documentation Structure

For Beginners

1. Start here: Main README
2. Try examples: examples/dog-api.yaml, examples/kubernetes-cli.yaml
3. Learn auth: Authentication Guide
4. Build real apps: GitHub Example

For Advanced Users

1. Architecture: Technical Specification
2. Performance: Optimization Docs
3. Memory: Deep navigation with LRU cache (auto-enabled)

---

🔥 Popular Examples

GitHub API Browser

Browse repositories, issues, and pull requests with the GitHub REST API.

Features: Bearer token auth, multi-page navigation, conditional styling

→ Complete Example

AWS CLI Integration

Browse S3 buckets, EC2 instances, and Lambda functions using AWS CLI.

Features: Profile/region support, credential files, status indicators

→ Complete Example

Kubernetes Dashboard

k9s-style interface for Kubernetes resources.

Features: Auto-auth via kubectl, logs streaming, resource actions

→ See YAML

---

📝 Configuration Overview

Basic Structure

version: v1

app:
  name: "App Name"

globals:
  api_key: "{{ env.API_KEY }}"

start: main_page

pages:
  main_page:
    title: "Page Title"
    data:
      adapter: http  # or cli, stream, script
      url: "https://api.example.com/data"
      headers:
        Authorization: "Bearer {{ api_key }}"
      items: "$.data[*]"
    view:
      type: table
      columns:
        - path: "$.name"
          display: "Name"

Data Adapters

Adapter	Use Case	Auth Method
http	REST APIs	Headers (Bearer, API Key, Basic)
cli	Command-line tools	Environment vars, credential files
stream	Real-time logs	Same as CLI
script	Custom scripts	Environment vars

Views

View	Use Case	Features
table	List data	Columns, sorting, filtering, styling
text	Details	Syntax highlighting (YAML, JSON, etc.)
logs	Streaming	Follow mode, wrapping, ANSI colors

---

🆘 Getting Help

Common Issues

"401 Unauthorized" → Check your API token
"Command not found" → Install CLI tool (kubectl, aws, gh)
"Template error" → Verify environment variable is set
"Empty results" → Check JSONPath expression in items:

Resources

• Examples: Browse examples/ directory for working configs
• GitHub Issues: Report bugs at github.com/pa/termstack
• Authentication: Complete Auth Guide

---

⚡ Quick Tips

Security

✅ Use {{ env.VAR }} for secrets
✅ Add *.secrets.yaml to .gitignore
✅ Use read-only credentials
❌ Never commit tokens to git

Performance

• Auto-refresh: refresh_interval: "5m"
• Timeouts: timeout: "30s"
• Memory: LRU cache auto-manages deep navigation

Debugging

# Validate config
termstack --validate config.yaml

# Verbose output
termstack --verbose config.yaml

---

📊 Feature Matrix

Feature	Status	Example
HTTP APIs	✅	GitHub
CLI Tools	✅	AWS, kubectl
Environment Variables	✅	{{ env.VAR }}
Template Engine	✅	Tera templates
Multi-page Navigation	✅	Context passing
Conditional Routing	✅	Based on data
Actions	✅	Commands, HTTP, navigation
Styling	✅	Colors, conditions
Streaming Logs	✅	Follow mode
Auto-refresh	✅	Configurable intervals

---

🎯 What's Next?

Build Your First Integration

1. Pick a data source:

   • REST API? → Authentication Guide
   • CLI tool? → AWS Example

2. Start with a template:

   • GitHub API? → Copy this
   • AWS? → Copy this
   • Custom? → See README

3. Test and iterate:

   termstack --validate config.yaml
   termstack config.yaml

Learn More

• Authentication: Complete guide with all methods
• GitHub Integration: Step-by-step with token setup
• AWS Integration: Multiple services with profiles

---

Made with ❤️ by the TermStack community
_{Build terminal UIs without writing code}