Quick Start

Assumes you have already installed glci and met the prerequisites.

1. Verify your setup#

cd ~/my-gitlab-project
glci doctor

  ✓ Docker              docker 27.5.1
  ✗ Daemon              not running
  ✓ GitLab token        ...ab3f
  ✓ CI config           12 jobs, 4 stages
  ✓ Git repository      main (a1b2c3d)

The daemon shows “not running” on a fresh install – it starts automatically on first run.

2. Explore your pipeline#

glci show                          # visual pipeline graph
glci jobs                          # list jobs with stages, rules, needs
glci lint                          # validate CI config

glci show evaluates rules: in a merge request context by default. Simulate other contexts:

glci show --context tag=v1.0.0
glci show --context branch=main

3. Run your pipeline#

glci run                           # run all jobs
glci run build test                # run specific jobs by name
glci run --stage test              # run all jobs in a stage

On first run, glci auto-starts a background daemon, pulls the Docker image, creates a per-pipeline Docker network with a mock GitLab server and runner container, and begins executing jobs.

Ctrl+C: first press detaches (jobs continue in background), second press cancels the pipeline.

Common flags#

glci run --env DB_HOST=localhost --env DEBUG=true   # inline variables
glci run --env-file .env.local                      # variables from file
glci run -f .gitlab-ci.production.yml               # alternate CI config
glci run -j 4                                       # max 4 parallel jobs

4. View results#

glci log                           # logs from latest pipeline
glci log 1 build                   # log for specific job in pipeline #1
glci history                       # list past pipeline runs
glci history show 1                # details for pipeline #1
glci ps                            # active pipelines and containers

5. Iterate on a failing job#

glci run --reuse-artifacts test-job # re-run, reusing artifacts from prior run
glci retry                          # retry all failed jobs from last pipeline

Interactive TUI#

Run glci with no arguments for a full interactive experience – pipeline graph, job selection, live logs, manual job triggers, and run history.

What happens under the hood#

1. Parses .gitlab-ci.yml (resolves include:, extends:, !reference, default:)
2. Evaluates rules: against simulated CI variables to determine which jobs run
3. Builds an execution plan (stage ordering, needs: DAG)
4. Sends the pipeline to the background daemon (auto-started if not running)
5. Daemon creates a per-pipeline Docker network with mock server and runner containers
6. Jobs are dispatched via docker exec into the runner container
7. Independent jobs within a stage run in parallel (configurable with -j)
8. Artifacts are stored in ~/.glci/projects/ and passed to downstream jobs

Common first-run issues#

Next steps#

• Running Pipelines – full glci run reference
• Configuration – config files and options
• Context Simulation – test branch, MR, and tag pipelines locally