glab-orbit

name	glab-orbit
description	Query the GitLab Knowledge Graph (Orbit) from the CLI. Use when discovering Orbit availability, inspecting schema/DSL/tools, running graph queries, or checking graph indexing status. Triggers on orbit, knowledge graph, graph query, orbit schema, orbit remote query, orbit dsl, orbit tools.

glab orbit

Access the GitLab Knowledge Graph (product name: Orbit) from glab.

The user-facing surface is the experimental glab orbit command family, covering remote Knowledge Graph access, guided setup, and the Orbit local CLI wrapper.

⚠️ Experimental Feature

Upstream marks Orbit as EXPERIMENTAL:

• command shape may change
• the API is gated behind the knowledge_graph feature flag
• access is user-scoped, not project-scoped
• glab orbit local downloads/runs a local Orbit CLI binary and may have separate host/platform constraints

See: https://docs.gitlab.com/policy/development_stages_support/

Quick start

# First: confirm the service is available for your user
glab orbit remote status

# Guided onboarding: verify access, install the Orbit agent skill, and install local CLI
glab orbit setup

# Discover the graph model
glab orbit remote schema
glab orbit remote dsl
glab orbit remote tools

# Inspect specific node types
glab orbit remote schema User Project MergeRequest

Recommended workflow: discover first, query second

The upstream docs strongly point to a discovery-first flow:

1. glab orbit setup or glab orbit remote status — verify Orbit is enabled and reachable
2. glab orbit remote schema — inspect the ontology (entities, edges, properties)
3. glab orbit remote dsl — inspect the authoritative JSON Schema for the query DSL
4. glab orbit remote tools — inspect the MCP tool manifest when integrating with agents/tools
5. glab orbit remote query ... — run actual graph queries once you know the schema

That order matters because schema and dsl are the source of truth for what the graph exposes and what request bodies are valid; tools is still useful for MCP/agent integration metadata.

Common workflows

0) Guided setup

# Interactive onboarding: checks access, prompts to install the skill, prompts to install local CLI
glab orbit setup

# Non-interactive setup: accept all prompts
glab orbit setup --yes

# Verify reachability only
glab orbit setup --skip-skill --skip-local

# Install the Orbit skill at user scope instead of in the current repo
glab orbit setup --global

# Refresh the skill and update the local CLI binary in place
glab orbit setup --upgrade

Use --path <path> for a custom skill install directory, --hostname <host> to verify a specific GitLab host, and --skip-skill / --skip-local when you only want part of the onboarding.

1) Check service health

# Check the default GitLab host for the current repo/user
glab orbit remote status

# Target a specific GitLab host explicitly
glab orbit remote status --hostname gitlab.com

Use this first when you're not sure whether Orbit is even enabled for your account or GitLab instance.

2) Inspect the ontology

# High-level schema overview
glab orbit remote schema

# Expand selected nodes with full detail
glab orbit remote schema User Project MergeRequest

Use schema to learn what entities exist and which relationships can be traversed.

3) Inspect the query DSL schema

# Show the full query DSL JSON Schema
glab orbit remote dsl

dsl returns the authoritative JSON Schema for the query DSL. Use this when generating or validating query bodies programmatically.

4) Inspect the MCP tool manifest

# Show the MCP tool manifest
glab orbit remote tools

tools returns the MCP tool manifest. Use this when integrating Orbit with tool-aware agents or when you need the tool wrapper metadata rather than the bare query DSL schema.

5) Run a remote query

glab orbit remote query reads a full Orbit query envelope from a file or stdin:

{
  "query": { "query_type": "..." },
  "response_format": "llm"
}

# Query from a file
glab orbit remote query ./query.json

# Query from stdin
cat ./query.json | glab orbit remote query -

# Force structured JSON for jq pipelines
glab orbit remote query --response-format raw ./query.json

Notes:

• Default output is llm, which is compact and agent-friendly.
• Use --response-format raw when you want structured JSON for further processing.
• --format / -f are deprecated compatibility aliases; update scripts to --response-format so deprecation warnings stay out of automation logs.
• The query body shape is defined by glab orbit remote dsl, not by guesswork.

6) Check indexing progress

# By full path
glab orbit remote graph-status --full-path gitlab-org/gitlab

# By numeric IDs
glab orbit remote graph-status --project-id 278964
glab orbit remote graph-status --namespace-id 9970

# Compact output for agents
glab orbit remote graph-status --full-path gitlab-org/gitlab --response-format llm

Use graph-status when a query looks incomplete and you need to confirm whether the relevant project/group has been indexed yet.

Troubleshooting

Orbit returns 404 / unavailable:

• Orbit endpoints are typically behind the knowledge_graph feature flag.
• Upstream documents exit code 2 for endpoint unavailable.
• Start with glab orbit remote status to verify availability before building queries.

Unauthorized / forbidden:

• Orbit access is user-scoped.
• Re-check glab auth status and confirm the current account has access to a Knowledge Graph-enabled namespace.
• Upstream documents exit code 3 for unauthenticated and 4 for forbidden.

Rate limited:

• Upstream documents exit code 5 for HTTP 429 responses.
• Slow down query bursts and prefer fewer, broader discovery calls.

Query body keeps failing validation:

• Fetch the current DSL schema with glab orbit remote dsl.
• Fetch the ontology with glab orbit remote schema.
• Prefer --response-format raw when debugging exact response structure.

Need local/offline graph commands:

• Use glab orbit setup to install the local CLI binary, then glab orbit local to run it.
• Keep remote discovery (status, schema, dsl, tools) in the workflow so generated local queries still match the server-side graph model.

Related skills

• glab-api — fall back to direct REST API calls when you need lower-level GitLab access
• glab-auth — verify login state before Orbit calls
• glab-mcp — separate MCP server tooling for AI integrations

Command reference

glab orbit remote status [flags]
  --hostname    Target GitLab host

glab orbit remote schema [node...] [flags]
  --hostname    Target GitLab host

glab orbit remote dsl [flags]
  --hostname    Target GitLab host

glab orbit remote tools [flags]
  --hostname    Target GitLab host

glab orbit remote query [file|-] [flags]
  --hostname         Target GitLab host
  --response-format  llm|raw (default: llm)

glab orbit remote graph-status [flags]
  --full-path        Project/group full path
  --hostname         Target GitLab host
  --jq               Filter JSON output with a jq expression
  --namespace-id     Group ID
  --project-id       Project ID
  --response-format  raw|llm (default: raw)

glab orbit setup [flags]
  --global      Install the Orbit skill at user scope (`~/.agents/skills/`)
  --hostname    GitLab hostname to verify
  --path        Custom Orbit skill install directory
  --skip-local  Skip the local CLI binary install step
  --skip-skill  Skip the agent-skill install step
  --upgrade     Re-fetch the skill and update the local CLI binary in place
  --yes         Skip every confirmation prompt

glab orbit local [command] [flags]
  Runs the Orbit local CLI; setup/download may happen before first use.