Use GitLab Orbit with the GitLab CLI (glab)

The GitLab CLI (glab) is the canonical way to set up and query GitLab Orbit from the command line.

glab orbit runs the managed orbit binary. It forwards each command to the binary, which glab downloads, verifies, and keeps up to date for you. Run glab orbit remote <command> --help for the binary’s own command reference.

• glab orbit remote: query the GitLab Orbit Remote REST API. glab injects your GitLab credential automatically. Available in glab 1.94 or later.
• glab orbit setup: guided onboarding that installs the GitLab Orbit skill and configures your AI agent.

Prerequisites

• GitLab 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 GitLab Orbit enabled.

Set up your AI agent

glab orbit setup configures AI coding agents (Claude Code, OpenCode, Cursor, Codex, Gemini CLI) to consult the graph, and installs the GitLab Orbit skill:

glab orbit setup

To connect an MCP client instead, configure it manually.

Query GitLab Orbit from the command line

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

glab resolves your credential and passes it to the binary, so no extra authentication step is needed. Use --hostname to target a specific GitLab instance, and --yes to skip the one-time run confirmation in scripts.

Discover the schema

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

Run a query

Replace your-group with your own group path. This query returns the first five projects in that group:

Put the request body in query.json:

{
  "query": {
    "query_type": "traversal",
    "nodes": [{
      "id": "p",
      "entity": "Project",
      "filters": {
        "full_path": {"starts_with": "your-group/"}
      }
    }],
    "limit": 5
  }
}

glab orbit remote query query.json

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

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

If --response-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 your-group/your-project
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.

Billing

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