GitLab Orbit CLI

The GitLab Orbit CLI (orbit) queries GitLab Orbit from the terminal. Your agent runs the same commands for you.

The CLI reads two sources:

• GitLab Orbit on your GitLab instance holds your GitLab data and the code on the default branch of each project.
• The local graph on your machine holds the code in your checkout, including commits that you have not pushed.

Install the CLI

You should use the GitLab CLI (glab) to install the GitLab Orbit CLI and connect your agents. glab downloads and verifies the GitLab Orbit CLI, and tells you when a new version is available.

To install the CLI and set up your agents, see set up your agent.

glab handles these options itself:

To skip the prompts on every run, set the glab options orbit_cli_auto_download and orbit_cli_auto_run to true:

glab config set --global orbit_cli_auto_download true
glab config set --global orbit_cli_auto_run true

When you run setup in a repository, it sets orbit_cli_auto_run only for that repository.

Install the standalone binary

If you cannot use glab, install the standalone orbit binary. The binary runs the same commands as glab orbit. In the commands on this page, replace glab orbit with orbit, for example orbit setup.

• With npm:

  shell

  npm install -g @gitlab/orbit

• On macOS and Linux:

  shell

  curl -fsSL "https://gitlab.com/gitlab-org/orbit/knowledge-graph/-/raw/main/install.sh" | bash

  To update, run the command with --force:

  shell

  curl -fsSL "https://gitlab.com/gitlab-org/orbit/knowledge-graph/-/raw/main/install.sh" | bash -s -- --force

• On Windows:

  powershell

  irm https://gitlab.com/gitlab-org/orbit/knowledge-graph/-/raw/main/install.ps1 | iex

• By hand: download the archive for your platform from the latest release, and put orbit on your PATH.

Command catalog

Commands that use the GitLab Orbit API need a GitLab credential and GitLab Orbit turned on for your group. Commands that use only the local graph need no GitLab account and no network. grep and context use the local graph, and also the GitLab Orbit API when a GitLab credential is available.

For all flags, run glab orbit <command> --help.

Query GitLab Orbit

Sign in once with glab, then run queries and check indexing progress from the terminal.

Prerequisites:

• GitLab Orbit is turned on for your group.
• The Reporter, Security Manager, Developer, Maintainer, or Owner role for the group.

To sign in:

1. Run glab auth login. On GitLab Self-Managed or GitLab Dedicated, select your instance from the list, or add --hostname <gitlab.example.com>.
2. Optional. On GitLab Self-Managed or GitLab Dedicated, to use glab orbit outside a clone of a project on your instance, run glab config set --global host <gitlab.example.com>.

glab orbit passes your glab credential to the CLI on every run. The standalone orbit binary uses a personal access token with the read_api scope in GITLAB_TOKEN if you set it, otherwise your glab credential. On GitLab Self-Managed or GitLab Dedicated, also set GITLAB_URL to the URL of your instance.

Run a query

To run a query, pass the query text:

glab orbit query "<query>"

This query returns five projects in a group. Replace my-group with the full path of your group:

glab orbit query "MATCH (p:Project) WHERE p.full_path STARTS WITH 'my-group/' RETURN p.full_path LIMIT 5"

To list the properties of node types, run glab orbit schema MergeRequest Project.

Check indexing progress

To check the indexing progress of a group or project, pass its full path:

glab orbit status --full-path <my-group/my-project>

Without --full-path, --namespace-id, or --project-id, status shows only the health of the service. In a terminal, it prints a summary. In a pipe or a file, it prints JSON. When indexing is complete, SDLC data and Code show indexed, and the summary ends with Ready.

Use only one of --full-path, --namespace-id, and --project-id.

Local graph

The local graph is part of the GitLab Orbit CLI. The local graph covers the code on your machine, which GitLab Orbit does not have. Your agent can find definitions, callers, and imports in code that you committed but have not pushed. The local graph works offline and needs no GitLab account. For merge requests, pipelines, work items, and vulnerabilities, query GitLab Orbit.

Your agent can use the local graph and GitLab Orbit in the same conversation.

Index a repository

glab orbit setup indexes the current repository for you. To index a repository yourself, run this command in it:

glab orbit workspace index .

The CLI parses the files in the working tree, skips the files that .gitignore excludes, and writes definitions, imports, and cross-file references to the graph. The parser and supported languages are the same as for GitLab Orbit.

• When you pass the path of a directory, the CLI indexes each repository in the directory.
• Each indexed commit keeps its own graph. When you index the same commit again, the CLI reindexes only the files that changed since the last run.
• After you switch branches or commit, grep and context index the new commit for you.
• To list the indexed repositories, run glab orbit workspace list.

workspace sql, workspace schema, and workspace mcp serve index the current repository the first time you use them in it, even when you indexed other repositories. They don’t index a new commit of a repository that is already indexed. grep, context, or workspace index do.

Index in the background

By default, workspace index runs in the foreground. If another index of the same repository is running, it waits for that index first. To index without blocking a shell command that has a short timeout, use these options:

With --async, if open readers still hold the locks after up to 30 seconds, the command exits with code 75 and prints the log file path to stderr. The background index keeps waiting, so you don’t need to run it again.

Commands that read the local graph also wait for a running index, up to 10 minutes, then exit with code 75. To change the wait, set ORBIT_WAIT_TIMEOUT_MS.

Search and read code

grep searches every line of every file in the working tree, like rg, and adds the enclosing definitions from the graph:

glab orbit grep read_file

The output is similar to:

grep "read_file" @ 6e979595: 3 lines in 2 files
Function read_file — src/utils.py:1-2
  1|def read_file(path):
  2|    return open(path).read()

src/utils.py
1-» Function read_file:1-2
1:def read_file(path):

src/main.py
1-» imports read_file (utils) → src/utils.py:1
1:from utils import read_file
8-» Method run:8-10
10:        read_file("x")

• If the term names a definition, its source prints first. Then each file prints its path once, with line:text for each match. A line-» Kind name:start-end line comes before the matches inside each definition, and import lines show where the name comes from.
• Plain words ignore case, _, and -, so read_file also matches ReadFile. Quote a|b to match either word. Patterns with regular expression characters are regular expressions. For an exact string, use -F.
• Common rg options such as -A, -B, -C, -w, -l, -c, -g, and -t work. To search definitions of one kind, start the query with the kind, such as def:read_file or class:App.
• grep and context index files that you edited after the last index. If indexing an edited file takes longer than two seconds or fails, grep marks the file (edited since index) and does not show its definitions. For more information, see troubleshooting.
• In a clone of a GitLab project, a search without paths also searches the merge requests, issues, and comments of the group of the origin remote, and prints them after the local results. To search only GitLab, start the query with mr:, issue:, commit:, or comment:.

To read the source of a definition and its callers, pass its name to context:

glab orbit context read_file

context also takes fully qualified names, file paths, path:start-end ranges, and directories, several at a time. It also reads GitLab, in the project of the origin remote: mr:42, issue:7, branch:<name>, pipeline:123, job:456, or a GitLab URL. With no target, it reads the merge request and failed CI/CD jobs of the current branch.

Settings, storage, and telemetry

The CLI keeps its settings and the local graph in ~/.gitlab/orbit/. The local graph is one DuckDB file for each indexed commit under local/revisions/, and a local/manifest.duckdb file that lists them.

• Commands that use the local graph accept --db <path> for a different graph file.
• When an update of the CLI changes the format of the local graph, the next workspace index rebuilds the graph file. Index your other repositories again after you update.

The CLI sends usage events, such as the command, the result, the duration, and the CLI version, to GitLab product analytics. It never sends repository content, file paths, or query text. Telemetry is on by default. To turn it off, run:

glab orbit config set telemetry.enabled false

The CLI reads these environment variables:

Exit codes

Related topics

• glab orbit reference
• Connect your agent
• Query language
• Troubleshooting