Use GitLab Orbit Local with the GitLab CLI (glab)

  • Tier: Free, Premium, Ultimate
  • Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
  • Status: Beta
This page contains information related to upcoming products, features, and functionality. It is important to note that the information presented is for informational purposes only. Please do not rely on this information for purchasing or planning purposes. The development, release, and timing of any products, features, or functionality may be subject to change or delay and remain at the sole discretion of GitLab Inc.

The GitLab CLI (glab) is the canonical way to install, run, and integrate GitLab Orbit with your AI agent. glab orbit forwards one flat command tree to the managed orbit binary. Commands such as index, grep, and sql use the local graph, while commands such as query and ontology use the hosted graph.

The flat glab orbit command tree requires glab 1.117 or later.

glab orbit setup provides guided onboarding, installs the GitLab Orbit skill, and configures supported AI agents.

Prerequisites

  • glab 1.117 or later is installed.
  • A local Git repository to index.

The local-graph verbs (index, grep, context, sql, schema, list, mcp, and repo-map) require no GitLab account or network connection once the binary is installed. Hosted verbs (query, status, ontology, dsl, tools, and graph-status) require an authenticated GitLab account and network access.

Install

Install the managed orbit binary:

shell
glab orbit --install

glab downloads the binary, verifies its checksum, and keeps it up to date. Verify the install:

shell
glab orbit version

Set up your AI agent

glab orbit setup configures AI coding agents to consult the graph: it writes a managed section into each agent’s instruction file and installs the GitLab Orbit skill.

shell
glab orbit setup

Run glab orbit setup --help for the full option list, including supported agents and project or user scope.

The binary’s own orbit setup also detects the installed agents, installs the skill, and registers the MCP server with --mcp. orbit uninstall reverts it. To connect an MCP client by hand, see Connect via MCP.

You can also install the GitLab Orbit skill manually with glab skills install --global orbit.

Index a repository

shell
glab orbit index /path/to/your/repo
FlagPurpose
--threadsWorker thread count. 0 (default) auto-detects from CPU cores.
--statsInclude detailed statistics in the JSON output.
--verboseVerbose logging to stderr.

Run SQL against the graph

shell
glab orbit sql 'SELECT count(*) FROM gl_definition'
echo 'SELECT name FROM gl_definition LIMIT 3' | glab orbit sql -

Queries include all indexed revisions through one DuckDB client by default. Use --repo /path/to/repo to select that checkout’s current revision. Use --db /path/to/revision.duckdb to select one database file.

FlagPurpose
--repoQuery only the given checkout’s current revision.
--allQuery every indexed repository and commit (the default).
-F, --formatOutput format: table (default), json, ndjson, or csv.
--dbRead a specific revision database. Defaults to the indexed revision databases.

Inspect the schema

glab orbit schema lists the graph tables and their columns. The per-project search-index tables and the schema fingerprint are hidden; name one explicitly to see it:

shell
glab orbit schema

Pass table names as positional arguments to scope the output:

shell
glab orbit schema gl_definition              # scoped to one table
glab orbit schema gl_definition gl_edge      # scoped to two tables
FlagPurpose
--rawEmit JSON instead of the default table view.
--dbOverride the DuckDB file path. Omit to use the local graph managed by GitLab Orbit.

Run as an MCP server

Expose the local graph to any MCP-compatible AI agent:

shell
glab orbit mcp serve

It serves run_sql, get_graph_schema, and index over the MCP protocol against revision databases under ~/.gitlab/orbit/local/. See Connect via MCP for the full agent integration guide.

Exit codes

glab orbit returns 0 on success and a non-zero exit code on failure, with details on stderr. Scripts and agents can branch on success or failure.

Billing

The local-graph verbs (index, grep, context, sql, schema, list, mcp, and repo-map) process data locally and do not consume GitLab Credits. Hosted verbs require network access, and query consumes GitLab Credits.