Use Orbit with the GitLab CLI (`glab`)

Tier: Premium, Ultimate
Offering: GitLab.com
Status: Experiment

The availability of this feature is controlled by a feature flag. For more information, see the history. This feature is available for testing, but not ready for production use.

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 set up and query Orbit from the command line.

Two top-level commands:

glab orbit remote: typed subcommands that call the Orbit Remote REST API. Available in glab 1.94 or later.
glab orbit setup: one-command install of the Orbit skill and MCP config for your AI agent. Planned for a future glab release. Until it ships, configure your MCP client manually.

Prerequisites

Orbit is enabled on your group.
glab is installed and authenticated:
```
glab auth login
```
Your user has access to at least one top-level group with Orbit enabled.

Set up your AI agent

glab orbit setup is planned for a future glab release. When it ships, one command will install the Orbit skill and write the MCP config for your AI agent (Claude Code, OpenCode, Cursor, Codex, Gemini CLI).

Until it ships, configure your MCP client manually.

Query Orbit from the command line

Use glab orbit remote (or the r alias) to call the Orbit Remote API directly. Useful for scripting, debugging, and exploring the schema before writing queries. Requires glab 1.94 or later.

Subcommand	Endpoint	Purpose
`glab orbit remote status`	`GET orbit/status`	Cluster health.
`glab orbit remote schema [node...]`	`GET orbit/schema`	Graph ontology. Positional args expand specific nodes.
`glab orbit remote tools`	`GET orbit/tools`	MCP tool manifest with the full DSL JSON Schema.
`glab orbit remote query [file\|-]`	`POST orbit/query`	Run a query from a file or stdin.
`glab orbit remote graph-status`	`GET orbit/graph_status`	Indexing progress for a namespace, project, or full path.

Discover the schema

glab orbit remote status
glab orbit remote schema
glab orbit remote schema MergeRequest Project
glab orbit remote tools

Run a query

echo '{"query":{"query_type":"traversal","node":{"id":"p","entity":"Project","filters":{"full_path":{"op":"starts_with","value":"your-group/"}}},"limit":5}}' \
  | glab orbit remote query -

The --format flag maps to the body’s response_format:

--format llm - compact text optimized for AI agent consumption.
--format raw - structured JSON, suitable for piping to jq.

If --format is unset, the body’s response_format wins, with llm as the final fallback.

Check indexing progress

Pass exactly one scope flag:

glab orbit remote graph-status --full-path gitlab-org/gitlab
glab orbit remote graph-status --namespace-id 24
glab orbit remote graph-status --project-id 2

Exit codes

glab orbit remote maps HTTP errors to stable exit codes so scripts and agents can branch on them without parsing stderr.

Status	Exit code	Meaning
`200`	`0`	Success.
`404`	`2`	`knowledge_graph` feature flag is off, or path typo.
`401`	`3`	Missing or expired token.
`403`	`4`	No Knowledge Graph enabled namespaces available.
`429`	`5`	Rate limited. Inspect `Retry-After` and back off.
Other	`1`	Unstructured error. Response body, if any, is included.

Billing

glab orbit remote query consumes GitLab Credits the same way as MCP queries. status, schema, tools, and graph-status calls are free.

Use Orbit with the GitLab CLI (glab)