orbit

# Orbit skill Query GitLab Orbit (previously GitLab Knowledge Graph) through the flat `glab orbit` command tree. It needs glab v1.126.0 or later. Hosted commands handle authentication, response framing, and exit codes. Local commands use the managed binary and the local DuckDB graph. ## Prerequisites If a `glab orbit` command fails with "command not found", an auth error, or a feature-flag exit code, work through the [first-run setup](references/troubleshooting.md#first-run-setup). ## Fix inaccurate guidance If guidance is wrong or outdated (command, flag, or behavior), tell the user. With their confirmation, open a focused MR against `metadata.source-project` fixing `metadata.source-path` (one fix per MR, Conventional Commits). If they decline, note the discrepancy in one line and continue with the corrected command. ## Query language Queries use read-only openCypher 9-based syntax (`MATCH ... RETURN`). If you find a legacy JSON query, run `glab orbit skills get orbit-gql-migration` to convert it. ## Discovery `glab orbit help` and `glab orbit <command> --help` are the authoritative usage references. Run `glab orbit skills` to list available skills. Run `glab orbit skills get orbit` to print the composed skill (`SKILL.md` by default), or append a path such as `references/local/cli.md` to print a file. Run `CALL db.schema()` once per session, because the schema does not change mid-session. It lists every relationship as `(Source)-[:TYPE]->(Target)` and the properties of the common nodes, such as `User`, `Project`, `Group`, `MergeRequest`, and `WorkItem`. Run `CALL db.schema('Node')` only for a node it does not list properties for. Query syntax and paste-ready queries are in [`references/gql.md`](references/gql.md). Batch schema reads: make every schema read a question needs in one shell command, not one command per read. Each `CALL db.schema` call takes one node. On the first read, chain the overview with the nodes that the question names. Later, batch only the new node reads. ```shell glab orbit query 'CALL db.schema()'; echo; glab orbit query "CALL db.schema('Vulnerability')"; echo; glab orbit query "CALL db.schema('Pipeline')" ``` The named-query catalog at `GET /api/v4/orbit/query/templates` is rendered in your mode. Do not reuse discovery results across users or mode changes. Entries contain only `name`, `description`, and `raw_query`; there is no client language selector. See [catalog troubleshooting](references/troubleshooting.md#named-query-catalog). Each `glab orbit query` has fixed per-call overhead. Prefer one aggregate query, with `count(...)` in `RETURN`, over N lookups for "how many X grouped by Y", and batch related lookups. When editing Orbit docs or skills, fence executable GQL queries as `gql orbit-query` so docs smoke tests run them. ## Running a query Pass query text inline. The CLI builds the request envelope, so a short query needs no temporary file: ```shell glab orbit query 'CALL db.schema()' glab orbit query "CALL db.schema('Project')" glab orbit query "MATCH (p:Project {full_path: 'gitlab-org/gitlab'}) RETURN p.id, p.full_path LIMIT 1" ``` With a standalone install, use `orbit query` instead of `glab orbit query`. Quote the whole query for the shell; single-quoted string literals then need double quotes around the query. `--file` reads a JSON request envelope whose `query` field holds the query text, not a bare query file. `--file -` reads that envelope from stdin. Default output is `llm` (compact, agent-friendly). Pass `--response-format raw` to pipe into `jq`. Endpoints are user-scoped, so do not pass `-R owner/repo`. ## Common pitfalls Read [`references/gql.md`](references/gql.md) before you construct a query. These traps recur: - At least one node needs an ID or a property filter. `LIMIT` does not bound the scan, so `MATCH (p:Project) RETURN p LIMIT 5` rejects. - Write relationship types after a colon: `-[:AUTHORED]->`. `-[AUTHORED]->` declares a variable and rejects. - Pipelines for a merge request need the `source: 'merge_request_event'` filter. - Prefer a single anchored node when you can bound the target directly. Extra anchor nodes can change the row shape and skew aggregate counts. - To find MRs that ever touched a file, use `HAS_DIFF`; see [file history](references/gql.md#merge-requests-that-touched-a-file). Use `HAS_LATEST_DIFF` for one MR's current revision. - Issues, epics, tasks, and incidents are the `WorkItem` node. There is no `Issue` node. - There is no `OR`, `XOR`, `RETURN DISTINCT`, `count(*)`, `OPTIONAL MATCH`, or `WITH`. `DISTINCT` works only inside `count()`: `count(DISTINCT pl)`. - For packages, their files, dependencies and vulnerabilities, and container repositories, load the `orbit-package-registry` skill first: `glab orbit skills get orbit-package-registry`. ## Iteration budget Resolve a user question in at most 5 query attempts, validation errors included. Changing only the row limit or the returned properties is not progress. Full rules: [`references/troubleshooting.md`](references/troubleshooting.md#iteration-budget-rules). ## Reporting results Orbit answers come from graph queries, not an authoritative source. Flag known coverage gaps inline when they affect the result. Full guidance: [`references/reporting.md`](references/reporting.md). <!-- orbit:include local:quick-start --> ## Managed CLI `glab orbit` downloads, verifies, and runs the GitLab Orbit CLI binary from the `orbit-cli` package (macOS, Linux, and Windows). `grep` and `context` read the local graph and index the working tree on their own. `workspace` groups the other local-graph commands (`index`, `list`, `reset`). The top-level `index` and `list` still run as deprecated aliases. `query`, `status`, and `schema` call the GitLab Orbit API. glab handles `--install`, `--update`, and `--yes` itself and forwards everything else to the binary. `--install` and `--update` are mutually exclusive. `--yes` skips the confirmation prompts, so pass it in scripts and agent runs. Put these flags before the subcommand (`glab orbit --yes status`); the binary rejects `--yes` after other subcommands, except for `setup` and `uninstall`, which take their own. glab's own `update` command also takes `--yes`. `glab help orbit` shows the wrapper help. `glab orbit help` and `glab orbit <command> --help` show the binary's. ```shell glab orbit --install --yes # install without running glab orbit --update # install the latest compatible version ``` Skip the confirmation prompts for good with `glab config set orbit_cli_auto_run true` and `glab config set orbit_cli_auto_download true`. Point glab at your own build with `glab config set orbit_cli_binary_path /path/to/orbit` or the `GLAB_ORBIT_CLI_BINARY_PATH` env var. That skips download, version checks, and updates. glab records `orbit_cli_binary_version`, `orbit_cli_binary_checksum`, and `orbit_cli_last_update_check` itself. Do not set them by hand. ## References | Topic | Location | |---|---| | First-run setup, exit codes, service health, iteration budget | [`references/troubleshooting.md`](references/troubleshooting.md) | | openCypher 9-based syntax and paste-ready queries | [`references/gql.md`](references/gql.md) | | Empty results and query validation errors | [`references/gql.md`](references/gql.md#troubleshooting) | | Reporting results and coverage caveats | [`references/reporting.md`](references/reporting.md) | | Maintaining this skill (contributing, doc sync) | [`references/maintaining.md`](references/maintaining.md) |