ddgl

Terminal-based GitLab CI client — browse pipelines, stream logs, and triage failures from your terminal.

Features

• Branch-aware — auto-detects your current git branch and resolves the latest pipeline with no arguments
• Interactive TUI (ddgl viz) — full pipeline browser with job list, status/stage filters, fuzzy or regex search, and matrix job grouping
• Blocking wait (ddgl attach) — block until a pipeline finishes, streaming progress; a live status line for humans, an append-only/JSONL event stream for scripts and coding agents
• Retry support — retry failed jobs with ddgl retry, auto-retry them while ddgl attach --retry polls, or press r in the TUI
• Job detail view — streaming log with collapsible sections, dependency graph (DAG), and keyboard navigation
• Smart log formatting — ANSI colors preserved, sections folded, optional timestamps, syntax highlighting
• Scripting-friendly — --json output on every command, pipe-friendly, --no-cache for force-refresh
• Local caching — finished pipelines and logs cached for one week; repeated queries are instant

Installation

Requires Python ≥ 3.12.

# Recommended — uv
uv tool install ddgl

# Or pip
pip install ddgl

To track main instead of the latest release, install from git:

uv tool install git+https://github.com/DataDog/ddgl-cli

Authentication & Configuration

Set GITLAB_TOKEN to a personal access token with read_api scope. Alternatively, configure token_file or token_command in the config file to resolve a token automatically.

The project is auto-detected from the origin git remote when run inside a repository. You can override any setting with environment variables:

Config file

For settings you don't want to repeat as environment variables, ddgl reads an optional TOML config file from the platform's standard config directory (e.g. ~/.config/ddgl/config.toml on Linux/macOS), or the path given by DDGL_CONFIG_FILE:

gitlab_url = "https://gitlab.example.com"
token_file = "/run/secrets/gitlab-token"
token_command = ["my-auth-tool", "print-token"]
github_fallback = false

• gitlab_url — same as GITLAB_URL; used when the env var is unset.
• token_file — path to a file containing the token (read and stripped). Checked before token_command.
• token_command — a command, as a TOML array (no shell involved), that prints a token to stdout.
• github_fallback — if true and no GitLab remote is found, assume the first GitHub remote's org/repo path is also the GitLab project path. Off by default.

Environment variables always take precedence over the config file.

Quick Start

# Latest pipeline for current branch
ddgl pipelines get

# Open interactive TUI
ddgl viz

# List failed jobs for the latest pipeline on the current branch
ddgl jobs list --failed

# Show the logs for a specific job
ddgl logs --job <id>

Common Workflows

Check pipeline status

ddgl pipelines get                  # latest pipeline on current branch
ddgl pipelines get --ref main       # specific branch
ddgl pipelines list -n 10           # last 10 pipelines
ddgl pipelines list --scope running # only running pipelines

Triage failed jobs

ddgl jobs list --failed
ddgl jobs list --failed --stage build
ddgl jobs list --name "lint.*"      # regex filter on job name
ddgl jobs get --failed              # full details for all failed jobs

Retry failed jobs

ddgl retry                          # retry every failed/canceled job in the latest pipeline
ddgl retry --stage build            # only failed/canceled jobs in the "build" stage
ddgl retry --job 12345 --job 12346  # specific jobs by ID
ddgl retry --job 12345 --force      # retry even if that job already succeeded or is still running
ddgl retry -y                       # skip the confirmation prompt

With no filter, ddgl retry calls GitLab's pipeline-level retry endpoint — the same button the web UI has, and GitLab picks the exact set. Any of --job/-f/--stage/--name narrows to matching jobs instead, each retried individually. Only failed or canceled jobs are retried unless --force widens that to whatever the filter matched. Always asks for confirmation first unless -y/--yes is given. Exit codes: 0 retried (or nothing to do), 1 GitLab rejected a retry, 2 usage/config/resolution error.

Read job logs

ddgl logs --failed                  # all failed logs in current pipeline
ddgl logs --job 12345               # single job by ID
ddgl logs --job 12345 --raw         # skip formatting
ddgl logs --job 12345 --timestamps  # include ISO timestamps
ddgl logs --job 12345 --strip       # strip ANSI codes (plain text)
ddgl logs --failed --stage test     # failed logs filtered to one stage

Save or pipe output

ddgl logs --job 12345 --output /tmp/build.log
ddgl logs --job 12345 --output /tmp/logs/      # one file per job (already-existing directory)
ddgl logs --failed --strip --output /tmp/logs/ # plain-text dump of all failed logs
ddgl jobs list --failed --json | jq '.[].name'
ddgl pipelines list --json | jq '.[] | select(.status == "failed") | .id'

Format a saved trace

ddgl format /path/to/trace.log
cat trace.log | ddgl format -

Force-refresh (bypass cache)

ddgl --no-cache pipelines get
ddgl --no-cache logs --failed

Walk back through commit history

By default ddgl searches the last 10 commits for a pipeline. Increase --depth when working on a branch with many commits since the last pipeline run:

ddgl pipelines get --depth 50
ddgl jobs list --failed --depth 50

Interactive TUI (ddgl viz)

ddgl viz                     # current branch
ddgl viz --ref feature/foo   # specific branch
ddgl viz --pipeline 98765    # specific pipeline ID

Layout: pipeline list sidebar (left) · job table (center) · filter bar and footer (bottom).

Search: fuzzy match by default. Toggle regex with the .* button. Use special tokens to combine filters:

status:failed stage:build lint    # failed jobs in "build" stage matching "lint"

Keybindings — main view

Keybindings — job detail (Enter)

Tabs: Log · Deps (dependency graph) · History (coming soon) · Tests (coming soon)

Blocking on a Pipeline (ddgl attach)

Blocks until a pipeline reaches a terminal state, streaming progress as it goes. Resolves a pipeline the same way as every other command (--ref / --pipeline / --depth), and by default waits for one to appear if you attach right after pushing.

ddgl attach                       # current branch — waits if no pipeline exists yet
ddgl attach --pipeline 98765      # pin a specific pipeline
ddgl attach --timeout 300         # give up after 5 minutes (exit 124) instead of blocking forever
ddgl attach --follow              # switch to a newer pipeline on the ref if one appears (e.g. a re-push)

Output auto-detects the audience, like every other command's console.is_terminal + --json behavior:

--detail {none,minimal,normal,full} controls how much shows up in Lines and Live modes; --json's JSONL always includes everything, regardless of --detail:

At every level above none, a changed poll tick prints its transitions first, then one [POLL] rollup line (job counts, failure count, current stage). This keeps transition lines concise while giving each completed poll a single summary. On a quiet tick, no line is printed unless --heartbeat is set; then it prints [BEAT] with the same rollup. --json always receives these events in full fidelity.

Exit codes follow the GNU timeout convention, so shell scripts and CI-babysitting agents can branch on them directly:

ddgl attach && ./deploy.sh                  # only deploy on success
ddgl attach --pipeline 98765 --timeout 300  # bounded wait; loop/re-invoke on exit 124

Auto-retry failed jobs

ddgl attach --retry                                # retry failures as they happen
ddgl attach --retry --retry-attempts 0             # unlimited retries per job name
ddgl attach --retry --retry-total 10               # cap the whole run at 10 retries total
ddgl attach --retry --retry-exclude 'flaky-e2e.*'  # never auto-retry matching job names (repeatable)

Off by default. With --retry, any job already failed when you attach — or that fails while polling — is retried automatically, up to --retry-attempts (default 2) per job name and --retry-total (default 50) across the whole run; either set to 0 for unlimited. Passing --retry-attempts, --retry-total, or --retry-exclude without --retry is a usage error (exit 2) rather than a silent no-op. Each accepted retry prints a [RETRY] line, and the final line reports the total count.

Global Options

These flags are available on all commands:

Every command and subcommand accepts --help for the full option list:

ddgl --help
ddgl logs --help
ddgl jobs list --help

Roadmap

• Job history tab — same job across recent pipelines for flakiness detection
• Test results — parsed test output in job detail view
• YAML-based dependency graph — replace N API calls with a single git show + parse

Development

uv sync
uv run pre-commit install --install-hooks   # once per clone
uv run pytest -v

The hooks format and lint on commit, and run the tests your change affects. The first commit after a clone runs the whole suite once (~35s) to build testmon's database; later commits take a second or two.

See DEVELOPER.md for the overall architecture and contributor guidelines.