glab-orbit

What this skill does

# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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:

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

```bash
# 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 --format raw ./query.json
```

Notes:
- Default output is `llm`, which is compact and agent-friendly.
- Use `--format raw` when you want structured JSON for further processing.
- The query body shape is defined by `glab orbit remote dsl`, not by guesswork.

### 6) Check indexing progress

```bash
# 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 --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 `--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

```text
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]
  --format      llm|raw (default: llm)
  --hostname    Target GitLab host

glab orbit remote graph-status [flags]
  --format        raw|llm (default: raw)
  --full-path     Project/group full path
  --hostname      Target GitLab host
  --namespace-id  Group ID
  --project-id    Project ID

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