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:

glab orbit --install

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

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.

glab orbit setup

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

The skill drives the orbit binary directly. To connect an MCP client to the local graph instead, see Connect via MCP.

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

Index a repository

glab orbit index /path/to/your/repo
Flag Purpose
--threads Worker thread count. 0 (default) auto-detects from CPU cores.
--stats Include detailed statistics in the JSON output.
--verbose Verbose logging to stderr.

Run SQL against the graph

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

Table names resolve to the current checkout: run from inside an indexed repository, gl_definition, gl_file, and the other node tables contain only that repository’s indexed commit, and gl_edge only that commit’s edges, so queries need no project_id or commit_sha predicates. Outside an indexed checkout the query runs against every indexed commit, with a note on stderr.

Flag Purpose
--repo Scope the tables to another checkout instead of the current directory.
--all Query every indexed repository and commit.
-F, --format Output format: table (default), json, ndjson, or csv.
--db Override the DuckDB path. Defaults to ~/.orbit/graph.duckdb.

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:

glab orbit schema

Pass table names as positional arguments to scope the output:

glab orbit schema gl_definition              # scoped to one table
glab orbit schema gl_definition gl_edge      # scoped to two tables
Flag Purpose
--raw Emit JSON instead of the default table view.
--db Override the DuckDB path. Defaults to ~/.orbit/graph.duckdb.

Run as an MCP server

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

glab orbit mcp serve

It serves run_sql, get_graph_schema, and index over the MCP protocol against ~/.orbit/graph.duckdb. 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.