Orbit local CLI skill

Index and query a local copy of the GitLab Orbit graph. The local CLI parses a checked-out repository into a DuckDB property graph and answers questions with read-only SQL — a different surface from Orbit Remote, which speaks the JSON DSL over gRPC. Use this skill for the working tree; use the orbit skill for production data.

Invocation

The binary is orbit. This skill writes commands as orbit <subcommand>. When you reach it through glab, prefix with glab orbit local and add --yes to skip the download/run prompts in non-interactive shells:

orbit index .                     # bundled binary
glab orbit local --yes index .    # same, via the glab wrapper

glab orbit local --install --yes installs/updates the managed binary. Full wrapper flags, config keys, and pass-through rules: references/cli.md.

Gotchas (read first)

• index operates on git repositories found under PATH. Pointing it at a plain subdirectory that is not its own repo indexes nothing (no graph stats are printed at all). Pass a repository root.
• Queries are SQL, not the DSL. orbit sql "SELECT …" runs against DuckDB tables (gl_definition, gl_edge, gl_file, gl_directory, gl_imported_symbol). There is no query_type/nodes/relationships JSON here — that is Orbit Remote.
• definition_type values are capitalized (Function, Method, AssociatedFunction, Struct, Field, Variant, Module, Constant, …). Filtering WHERE definition_type='function' returns zero rows; use 'Function'. Run orbit schema gl_definition when unsure of columns.
• Relationships live in gl_edge, keyed by source_id/target_id with relationship_kind in DEFINES, CALLS, IMPORTS, CONTAINS, EXTENDS. Join back to gl_definition on id to resolve names.
• The graph is per-commit. The node tables (gl_definition, gl_file, gl_directory, gl_imported_symbol) carry commit_sha; gl_edge does not - join back to a definition to scope edges to a commit. Re-run index after checking out a different commit. Default database is ~/.orbit/graph.duckdb (override with --db).

Command surface

Quick start

orbit index .                                   # index the current repo
orbit schema gl_definition gl_edge              # confirm columns before querying
orbit sql "SELECT definition_type, count(*) n FROM gl_definition GROUP BY 1 ORDER BY n DESC"

Paste-ready SQL for callers, definitions-in-file, subclasses, and imports: references/sql.md.

Repository map

For a hierarchical orientation pass over a local checkout (languages, structure, key abstractions, per-file APIs) instead of ad-hoc SQL, use the native orbit repo-map command:

orbit repo-map overview                 # start here
orbit repo-map tree crates              # types grouped by file under a subtree
orbit repo-map api crates/orbit-local   # types + callables + signatures

It is scoped to the current commit; index first if the commit is not indexed. Full workflow and subcommands: references/repo_map.md.

References