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 <command> --help for the binary’s own command reference.

Hosted commands such as query, status, ontology, dsl, tools, and graph-status call the GitLab Orbit Remote REST API. glab injects your GitLab credential automatically. glab orbit setup provides guided onboarding and configures supported AI agents.

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 to call the GitLab Orbit Remote API directly. Useful for scripting, debugging, and exploring the schema before writing queries. Requires glab 1.117 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 status
glab orbit ontology
glab orbit ontology MergeRequest Project
glab orbit dsl
glab orbit 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 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 graph-status --full-path your-group/your-project
glab orbit graph-status --namespace-id 24
glab orbit graph-status --project-id 2

Exit codes

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

Billing

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