Job Management

Interactive TUI#

Launch the interactive TUI with glci (no subcommand):

• Browse Pipeline – view your CI config as a navigable graph
• Run Pipeline – start execution with live status updates
• Pipeline history – drill into previous runs, view job logs

Navigation: arrow keys/hjkl to move, Enter to drill in, Esc to go back, ? for help.

Searching the pipeline graph#

Press / in the pipeline view to search jobs by name, then Enter to apply. Matching jobs stay bright, the rest are dimmed, and the bar under the graph keeps showing the term and how many jobs it matched. The search is a case-insensitive substring match, not a regex.

/ always starts a fresh search: it drops any term already applied. Esc while you are typing abandons the search, Esc with a term applied clears the filter, and a further Esc goes back.

Log view keys#

Pressing Enter on a job in the pipeline view opens its log (the same viewer the live glci run TUI uses). The bar under the pane shows the scroll position, whether follow mode is on, and the search term:

Search is a case-insensitive substring match over log lines, and it ignores the color codes runners emit, so a word split by an escape sequence is still found. Applying a term scrolls the first match at or after your current position to the top of the pane — wrapping to the top of the log if there is none below — and pauses follow mode so streaming output does not scroll it away.

The bar reports where you are in the match list (/needle [2/7]), or [no match] when nothing matched. On a live log the list is only rescanned when you press n/N, so a count that new output may have grown is shown with a + ([2/7+]).

Lines wider than the pane are clipped, not lost. Press w to reflow them onto as many rows as they need — the line you were reading stays at the top of the pane, and search matches still land on the right row — or pan sideways with ←→ to read the tail in place. With wrap off, the bar shows a ↔ scroll percentage whenever some line is wider than the pane, and the hints below it offer ←→ pan in the same situation; with wrap on it shows wrap instead. On a narrow terminal whole hints are dropped rather than cut mid-word.

Esc follows the same ladder as the graph: it cancels an open prompt, then clears an applied term, then leaves the log view. Opening a different job’s log clears the search as well.

Viewing logs#

glci log                    # all logs from latest pipeline
glci log 5                  # all logs from pipeline #5
glci log 5 build-job        # log for a specific job

When a job is still running, glci log streams from the daemon in real time. Once the job completes, it reads from the stored log on disk. Press Ctrl+C to stop streaming.

Either form catches you up on output produced before you attached, from different sources. Naming a job (glci log 5 build-job) replays that job’s complete trace from disk, then continues live. Without a job name, the replay comes from the daemon’s in-memory event buffer, which is capped (10 MB of log events by default) — on a very verbose pipeline its oldest output has already been evicted.

Nothing is lost at the switchover from replay to live, but a line written at that exact moment can be printed twice; a duplicate there is expected, not a bug.

Stopping pipelines#

glci stop                    # stop active pipeline for current project
glci stop 5                  # stop pipeline #5
glci stop 5 --job build      # stop specific job in pipeline #5

If the daemon no longer tracks the pipeline (e.g., after a daemon restart), glci stop <id> automatically falls back to force-removing leftover Docker containers and the pipeline network, then marks the pipeline as canceled in history.

When stopping a pipeline that has active child pipelines (from trigger: include:), all child jobs are automatically canceled first, ensuring clean shutdown across the entire pipeline hierarchy.

Retrying failed jobs#

Retry creates a new pipeline that re-runs only the failed jobs, reusing artifacts from the original run:

glci retry                  # retry all failed jobs from latest
glci retry 5                # retry all failed from pipeline #5
glci retry --job build      # retry only the "build" job

The retry command verifies that the specified job actually failed before starting.

Listing jobs#

glci jobs parses the CI config and lists all jobs that would run after rules evaluation:

glci jobs                   # list all jobs with stage, when, and needs
glci jobs --stage build     # filter by stage
glci jobs --json            # machine-readable JSON output
glci jobs --context tag=v1  # see jobs for a tag context
glci jobs -p quick          # see jobs for a pipeline preset

Active pipelines#

glci ps                  # show active pipelines and containers
glci ps --containers     # show only glci-managed containers (alias: -c)

Pipeline history#

glci history                 # list recent pipelines
glci history --limit 5
glci history show 3          # show pipeline details with job list
glci history clean           # delete all
glci history clean --keep 5  # keep last 5

Linting#

Validate CI configuration without running it:

glci lint                   # report job/stage count on success
glci lint --quiet           # exit code only, no output on success (alias: -q)
glci lint -f custom.yml     # lint a specific file

Exit codes: 0 for valid, non-zero for parse errors or structural issues (e.g., undefined stages, circular needs).

Named runner dispatch#

When named runners are configured, jobs are automatically dispatched to the matching runner based on their CI tags:

# ~/.glci/config.toml
[runners.gpu]
config_template = """
[[runners]]
  [runners.docker]
    gpus = "all"
"""

gpus is a privilege grant, so this template belongs in the global config — a template in a project .glciconfig.toml may not set it. See Restricted keys in a project config template.

# .gitlab-ci.yml
train-model:
  tags: [gpu]
  script: python train.py

The train-model job routes to the gpu runner. Jobs without matching tags run on the default shared runner. First tag match wins when a job has multiple tags.

Health checks#

glci doctor                 # check container engine, daemon, token, CI config, git

Runs five checks and reports pass/fail/warning for each:

1. Container engine – verifies the active engine (Docker or Podman) is reachable and reports its version. Under Podman it also checks the Docker-compatible API socket separately. See glci doctor for the engine-specific hints and config-drift warnings
2. Daemon – checks if the glci daemon is running and reports PID
3. GitLab token – verifies a token is configured
4. CI config – parses the pipeline and reports job/stage count
5. Git repository – confirms the current directory is a git repo with branch and commit

The whole report is printed either way, and the command exits 1 if any check hard-failed: engine unreachable, Podman API socket unreachable, CI config parse error, not a git repository, or an error while checking daemon status. A stopped daemon (it starts on demand) and a missing GitLab token are warnings only and keep exit 0, so glci doctor && glci run works as a gate.