Help us learn about your current experience with the documentation. Take the survey.

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 Local with your AI agent. glab orbit local mirrors glab orbit remote, so the same patterns work whether you query the GitLab instance or your local machine.

glab orbit local and glab orbit setup ship today, in glab 1.94 or later.

Two top-level commands:

  • glab orbit local: wraps the managed orbit binary to index and query the local graph.
  • glab orbit setup: guided onboarding that verifies access, installs the GitLab Orbit skill, and installs the local binary.

Prerequisites

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

No GitLab account or network connection is required to use glab orbit local once the binary is installed.

Install

Install the managed orbit binary:

glab orbit local --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: which agents to configure, project or user scope, local or remote graph, 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 local 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

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

Inspect the schema

glab orbit local schema lists every table and column in the local DuckDB graph:

glab orbit local schema

Pass table names as positional arguments to scope the output:

glab orbit local schema gl_definition              # scoped to one table
glab orbit local schema gl_definition gl_edge      # scoped to two tables
FlagPurpose
--rawEmit JSON instead of the default table view.
--dbOverride 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 local 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 local 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

GitLab Orbit Local does not consume GitLab Credits. All processing is local.