Use Orbit Local with the GitLab CLI (`glab`)

Tier: Free, Premium, Ultimate
Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
Status: Experiment

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 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.

Both glab orbit local and glab orbit setup are planned for a future glab release. Every command on this page is the future shape, not the current one. Until they ship, build from source - see use orbit directly.

Two top-level commands (both planned, not yet shipped):

glab orbit setup: install the Orbit skill and point your AI agent at the local graph.
glab orbit local: typed subcommands that wrap the orbit binary. Includes glab orbit local mcp serve to run Orbit Local as an MCP server.

Prerequisites

glab is installed and authenticated:
```
glab auth login
```
A local Git repository to index.

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

Set up your AI agent

glab orbit setup is planned, not yet shipped. Until it ships, configure your MCP client manually.

Once shipped, glab orbit setup will install the Orbit skill and write the MCP config in one command. It prompts for Local or Remote and auto-detects your agent.

glab orbit setup
# Pick "Local" when prompted to point the MCP config at your local graph.

Supported agents: Claude Code, OpenCode, Cursor, Codex, Gemini CLI.

Flag	Purpose
`--agent=<name>`	Override auto-detection.
`--skill-only`	Install the skill files only; skip MCP config.
`--mcp-only`	Write MCP config only; skip skill install.
`--dry-run`	Print what would change without writing anything.

The MCP config points at orbit mcp serve instead of the remote endpoint. Your agent can call query_graph and get_graph_schema against the local DuckDB graph.

Index a repository

glab orbit local 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 a query

echo '{"query_type":"traversal","node":{"id":"d","entity":"Definition","columns":["name","definition_type"],"filters":{"definition_type":"Method"}},"limit":10}' \
  | glab orbit local query -

Pass a file path or - for stdin. The query language is identical to Orbit Remote.

Flag	Purpose
`--format llm`	Compact text optimized for AI agent consumption.
`--format raw`	Structured JSON, suitable for piping to `jq`.

Inspect the schema

glab orbit local schema
glab orbit local schema --expand Definition File
glab orbit local schema --query

Run as an MCP server

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

glab orbit local mcp serve

This serves query_graph and get_graph_schema over the MCP protocol against ~/.orbit/graph.duckdb. See Connect via MCP for the full agent integration guide.

List indexed repositories

glab orbit local status

Shows which repositories are present in the local graph, their indexing state, and the database path.

Exit codes

glab orbit local maps errors to stable exit codes so scripts and agents can branch on them.

Status	Exit code	Meaning
Success	`0`	Command completed.
No graph	`2`	`~/.orbit/graph.duckdb` not found. Run `index` first.
Bad query	`4`	Query DSL failed validation or compilation.
Other	`1`	Unstructured error. Stderr contains details.

Billing

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

Use Orbit Local with the GitLab CLI (glab)