Orbit CLI

How the Orbit CLI brings Orbit to your terminal and to your AI agents.

What the Orbit CLI does

The Orbit CLI is the way into Orbit from a terminal or an AI agent. Most people run it through the GitLab CLI as glab orbit. It answers from two graphs. The local graph holds the code of the checkouts on your machine. Orbit's graph covers the projects in the groups where Orbit is on. Here is a simplified view.

The Orbit CLI sends local questions to the local graph and the rest through GitLab to Orbit's graph

1. Install with the GitLab CLI

On first use, the GitLab CLI downloads the Orbit CLI from Orbit's package registry on GitLab.com. It checks the SHA256 checksum of the download. From then on, it passes every glab orbit command to the Orbit CLI.

The GitLab CLI checks for a new version at most once a day. It prints a notice when one exists. The glab orbit update command installs it. Getting started lists the other ways to install the CLI.

2. Connect AI agents

The glab orbit setup command finds the AI agents on your machine: Claude Code, Codex, GitLab Duo, OpenCode, and pi. It installs the Orbit skill and the plugin, hook, or extension each agent uses. That integration loads the Orbit instructions from the CLI when a session starts. Then setup indexes the current repository. The glab orbit uninstall command removes what setup wrote, except files you edited since.

The glab orbit skills command fetches the skills that match your GitLab instance.

3. Index a checkout

The glab orbit workspace index . command walks the working tree of the checkout in the current folder. So uncommitted and untracked files are part of the graph. It skips what .gitignore excludes. It lists binary, minified, and very large files, but it doesn't parse them. Tree-sitter grammars parse each supported language into the code types that the data model page describes.

Each checkout and commit gets its own file on your machine. The glab orbit workspace sql command reads every indexed checkout at once, so one query can span several repositories. A repeat run on the same commit parses only the files that changed. The glab orbit grep and glab orbit context commands index the current commit when it isn't indexed yet.

4. Ask the local graph

The main commands that read the local graph are:

  • glab orbit grep works like grep. It shows each match inside its enclosing definition, with that definition's callers and callees. When authenticated with glab, a GitLab kind such as mr: or issue: searches the top-level group behind origin; a plain search covers local code only.
  • glab orbit context expands a definition, a file, a line range, or a folder. When authenticated with glab, it also reads GitLab targets such as mr:42, issue:7, and pipeline:123.
  • glab orbit workspace sql runs DuckDB SQL on the local graph.

5. Ask Orbit's graph

Orbit's graph answers what the local context can't. It holds merge requests, pipelines, vulnerabilities, and the code of every indexed project. The main commands that ask Orbit's graph through the GitLab API are:

  • glab orbit query sends a question to Orbit's graph.
  • glab orbit schema shows the node and edge types.
  • glab orbit status --full-path <path> shows the indexing progress of a project or a group.

GitLab checks who you are and which groups you can see, as security explains. The GitLab CLI passes your sign-in to the Orbit CLI in its environment. The Orbit CLI never stores the token.

Why use the Orbit CLI

One tool covers all your context. An agent learns one set of commands. The same commands work on a checkout and on your whole organization.

Several agents can index and query in separate worktrees at the same time.

Decisions