GitHub - Elpulgo/azdo: A TUI for working with Azure DevOps in ze terminal.
Pangram verdict · v3.3
We believe that this document is a mix of AI-generated, AI-assisted, and human-written content
AI likelihood · overall
MixedArticle text · 1,574 words · 6 segments analyzed
A Terminal User Interface (TUI) for Azure DevOps - manage pull requests, work items, and pipelines directly from your terminal.
Table of Contents
Installation Features Demo Mode CLI Usage Configuration Keyboard Shortcuts Technology Stack Development FAQ Contributing License
Installation Quick Install (Recommended) Linux / macOS: curl -fsSL https://raw.githubusercontent.com/Elpulgo/azdo/main/install.sh | sh Windows (PowerShell): irm https://raw.githubusercontent.com/Elpulgo/azdo/main/install.ps1 | iex The install scripts will automatically:
Detect your OS and architecture Download the latest release from GitHub Install the binary to the appropriate location Create a config file with placeholder values Verify the download checksum
Install options: # Install a specific version curl -fsSL https://raw.githubusercontent.com/Elpulgo/azdo/main/install.sh | sh -s -- --version v0.1.0
# Install to a custom directory ./install.sh --install-dir ~/bin Manual Download Download the latest release for your platform from the Releases page.
Platform Architecture File
Linux x86_64 azdo_*_Linux_x86_64.tar.gz
Linux ARM64 azdo_*_Linux_arm64.tar.gz
macOS x86_64 azdo_*_Darwin_x86_64.tar.gz
macOS ARM64 (M1+) azdo_*_Darwin_arm64.tar.gz
Windows x86_64 azdo_*_Windows_x86_64.zip
Windows ARM64 azdo_*_Windows_arm64.zip
Extract the archive and move the binary to a directory in your PATH.
From Source git clone https://github.com/Elpulgo/azdo.git cd azdo go build -o azdo-tui ./cmd/azdo-tui Using Go Install go install github.com/Elpulgo/azdo/cmd/azdo-tui@latest Features Multi-Tab Interface
Pull Requests (Tab 1): View and track pull requests Work Items (Tab 2): Browse and manage work items Pipelines (Tab 3): Monitor and drill into pipeline runs Switch between tabs using 1, 2, 3 keys or ←/→ arrow keys
Pull Requests
List view of pull requests with status indicators Filter to show only your created PRs (m key) or PRs where you're a reviewer (A key) Detailed view showing PR information and metadata Vote on PRs directly from the detail view (approve, reject, suggestions, wait, reset) Code review: Diff viewer with file-by-file navigation Inline commenting, thread replies, and thread resolution General (non-file-specific) comments
Work Items
List view of work items with status and type information Detailed view showing work item details View the Discussion (comments) below the description, newest first Add comments from the detail view (c key, multi-line form) Change work item state directly from the detail view (dynamically fetches available states) Filter to show only your assigned items Filter by tag (T key) Filter by state (s key)
Pipeline Dashboard
View recent pipeline runs in a sortable table Color-coded status indicators (✓ Success, ✗ Failed, ● Running, ○ Queued) Filter by status (S key) Live auto-refresh with configurable polling interval Connection status indicator in footer Hierarchical detail view with stages, jobs, and tasks Duration tracking for each step Full log viewer with scrollable viewport
Metrics Dashboard (opt-in) A management view for team leads, disabled by default. Enable it via metrics.enabled: true in config.yaml and a fourth tab appears. Two sub-views, toggled with v:
Live — current-state dwell per work item, per-user roll-up (WIP, in-flight, oldest Active / Ready for Test, points closed in the configured interval), and a worst-first "stuck items" pane.
Sourced from the live work-item fetch — no local state, on-demand refresh only. Trends — sprint-on-sprint comparison from a local 90-day snapshot file. Pick any combination of sprint tags with T (multi-select; space toggles, enter confirms) and see per-user points closed, average WIP, stuck count, and cycle time side-by-side. Values are colored: green for closed points, yellow when overloaded, red for stuck items.
The snapshot file lives at ~/.config/azdo-tui/metrics.jsonl. One row per work item per day is appended on first metrics-tab launch each day, then pruned to a 90-day window. No database — append-only JSONL. One-shot backfill (optional). A fresh install starts with an empty snapshot file, so the Trends view shows "Insufficient snapshot history" for the first ~2 sprints. To seed the file from your team's actual recent history, set: metrics: run_one_shot_backfill: true On the next launch the tab walks every in-flight or recently-closed work item across all configured projects, reads each item's revision history via /updates, and synthesizes daily snapshot rows back 90 days. The footer reports progress and the result. A marker file (~/.config/azdo-tui/.metrics-backfill-done) prevents re-running — delete it if you want to re-seed. Flip the flag back to false once it's done so the footer hint stops appearing. User Experience
Setup wizard on first run guides you through configuration Help modal with all keyboard shortcuts (press ?) Secure PAT storage using system keyring Context-aware keybinding hints Graceful error handling with automatic retry Eight built-in themes with true color support Theme switcher modal (press t) to change themes on the fly Multi-project support with display name customization State persistence — remembers the last active tab and the last opened PR / work item detail across sessions, so you can pick up where you left off
Demo Mode Want to try azdo without an Azure DevOps account? Run the demo — no configuration, no PAT, no setup required: azdo demo This launches the full TUI with realistic mock data (two fictional projects, pull requests with diffs, work items, pipeline runs with logs).
All features work — you can navigate, view details, switch themes, and explore the UI. Perfect for evaluating the tool or taking screenshots.
See more screenshots in the screenshots folder. CLI Usage # Start the TUI azdo
# Try it out with mock data (no setup needed) azdo demo
# Set or update your Personal Access Token azdo auth
# Show version azdo --version
# Show help azdo --help Configuration 1. Create Configuration File When running azdo for the first time, a wizard setup will help you setup this. Otherwise follow these instructions. Create a configuration file at the following location:
Linux/macOS: ~/.config/azdo-tui/config.yaml Windows: C:\Users\<username>\.config\azdo-tui\config.yaml
# Azure DevOps organization name (required) organization: your-org-name
# Azure DevOps project name(s) (required) # Simple format: projects: - your-project-name
# With display names (friendly name shown in UI): # projects: # - name: ugly-api-project-name # display_name: My Project # - name: ugly-api-project-name-2 # display_name: My Project 2
# Polling interval in seconds (optional, default: 60) polling_interval: 60
# Theme (optional, default: dark) # Available themes: dark, gruvbox, nord, dracula, catppuccin, github, retro, monokai theme: dark
# Disable specific panes (optional, comma-separated) # Valid values: pipelines, workitems # disabled_panes: pipelines,workitems
# Metrics dashboard (opt-in, management feature). Hidden unless enabled. # See "Metrics Configuration" below for the full reference.
# metrics: # enabled: false # interval_days: 14 # window for the Live "closed pts" column # active_stale_days: 3 # dwell in Active above this flags the item # rft_stale_days: 2 # dwell in Ready for Test above this flags the item # wip_limit: 4 # in-flight strictly above this marks a user overloaded # run_one_shot_backfill: false # one-time /updates seed (see Features → Metrics) # states: # your board's actual state names (case-insensitive) # active: Active # ready_for_test: Ready for Test # closed: Closed # state_labels: # optional column-header overrides (auto-derived if omitted) # active: active # ready_for_test: rft # closed: closed Configuration Options:
organization: Your Azure DevOps organization name (required) projects: List of Azure DevOps project names (required). Each entry can be a plain string or an object with name and display_name fields. The display_name is shown in the TUI while the name is used for API calls. polling_interval: How often to refresh data in seconds (optional, default: 60) theme: Color theme for the UI (optional, default: dark) disabled_panes: Comma-separated list of panes to hide (optional). Valid values: pipelines, workitems. When a pane is disabled, its tab, keyboard shortcuts, and all related UI are removed. Pull Requests cannot be disabled. metrics: Opt-in management dashboard. See Metrics Configuration below for the full reference, and Features → Metrics Dashboard for what it does.
Available Themes:
dark - Dark theme with blue and cyan accents gruvbox - Retro groove color scheme nord - Arctic, north-bluish color palette dracula - Default dark theme with purple and pink accents catppuccin - Soothing pastel theme (Mocha variant) github - GitHub Dark theme retro - Matrix-inspired green phosphor on black monokai - Classic Monokai color scheme
Metrics Configuration The metrics dashboard is opt-in and hidden entirely unless metrics.enabled: true.
All keys live under the top-level metrics: block and are optional — the defaults below apply when a key is omitted. The validation rules only apply when enabled is true.
Key Type Default Description
metrics.enabled bool false Master switch. The whole tab is hidden when false.
metrics.interval_days int 14 Look-back window (days) for points-closed / velocity. Must be > 0.
metrics.active_stale_days int 3 Dwell in Active longer than this flags the item as stuck. Must be >= 0.
metrics.rft_stale_days int 2 Dwell in Ready-for-Test longer than this flags the item as stuck. Must be >= 0.
metrics.wip_limit int 4 In-flight items strictly above this marks a user overloaded (⚠). Must be > 0.
metrics.run_one_shot_backfill bool false One-time 90-day /updates seed of history on next launch. A marker file prevents it re-running.
State names — metrics.states These map your board's actual workflow-state strings onto the three buckets the metrics engine tracks. Matching is case-insensitive and whitespace-trimmed, but each takes a single name (no comma-separated aliases). If your board doesn't literally use "Active" / "Ready for Test" / "Closed", set these or the metrics tab will bucket nothing.
Key Default
metrics.states.active Active
metrics.states.ready_for_test Ready for Test
metrics.states.closed Closed
Each name must be non-empty, distinct from the other two, and contain no single quote (') — single quotes are rejected for WIQL-injection safety. Column labels — metrics.state_labels (optional) Display-only overrides for the metrics table column headers. When omitted, labels are auto-derived from the configured state name: multi-word names become lowercased initials (Ready for Test → rft, In Progress → ip), single-word names are lowercased as-is (Done → done).