ドキュメントに関する現在のご利用体験についてお聞かせください。アンケートにご協力ください。

GitLab Orbit CLIでGitLab Orbit Localを使用する（`orbit`）

プラン: Free、Premium、Ultimate
提供形態: GitLab.com、GitLab Self-Managed、GitLab Dedicated
ステータス: ベータ版

GitLab Orbit CLI（orbit）は、任意のローカルリポジトリのコードグラフを構築し、ローカルのDuckDBファイルに対してクエリを実行します。GitLabへの接続は不要です。

インストール

ワンラインインストーラーでスタンドアロンのorbitバイナリをインストールします。

curl -fsSL "https://gitlab.com/gitlab-org/orbit/knowledge-graph/-/raw/main/install.sh" | bash

これによりorbitがPATHに追加されます。新しいターミナルを開き、インストールを確認します。

orbit help

npm install -g @gitlab/orbitでnpmからインストールすることもできます。

GitLab CLI（glab）をすでに使用している場合は、glab orbit local --installでマネージドバイナリをインストールすることもできます。そのバイナリはorbitを直接使用するのではなく、glab orbit local <command>として実行します。詳細はglabでGitLab Orbit Localを使用するを参照してください。

ソースからビルドする

GitLab Orbitにコントリビュートする場合や、未リリースのビルドを実行する場合は、バイナリを自分でコンパイルします。

前提条件:

Rustツールチェーン（stable）
ツール管理用のmise

git clone https://gitlab.com/gitlab-org/orbit/knowledge-graph.git
cd knowledge-graph
mise install
mise run build:cli

コンパイルされたバイナリはtarget/release/orbitにあります。PATHに追加するか、直接実行してください。

リポジトリをインデックス作成する

orbit index /path/to/your/repo

GitLab Orbitはリポジトリを解析し、DuckDBグラフを~/.orbit/graph.duckdbに書き込みます。複数のリポジトリをインデックス作成できます。各リポジトリはマニフェストテーブル内でプロジェクトIDとブランチによってスコープが設定されます。

フラグ	説明
`--threads`	ワーカースレッド数。`0`（デフォルト）はCPUコア数から自動検出します。
`--stats`	JSON出力に詳細な統計情報を含めます。
`--verbose`	stderrへの詳細ログを有効にします。
`--db`	DuckDBのパスを上書きします。デフォルトは`~/.orbit/graph.duckdb`です。

スキーマを確認する

orbit schemaはローカルDuckDBグラフのすべてのテーブルとカラムを一覧表示します。

orbit schema

テーブル名を位置引数として渡すと、出力をスコープできます。

orbit schema gl_definition              # scoped to one table
orbit schema gl_definition gl_edge      # scoped to two tables

フラグ	説明
`--raw`	デフォルトのテーブルビューではなくJSONで出力します。
`--db`	DuckDBのパスを上書きします。デフォルトは`~/.orbit/graph.duckdb`です。

ローカルグラフに対してSQLを実行する

orbit sql 'SELECT count(*) FROM gl_definition'
orbit sql -F json 'SELECT name FROM gl_definition LIMIT 3'
echo 'SELECT 1+1' | orbit sql -
orbit sql --file query.sql

フラグ	説明
`-F`、`--format`	`table`（デフォルト）、`json`、`ndjson`、または`csv`。
`-f`、`--file`	ファイルからSQLを読み込みます。
`--db`	DuckDBのパスを上書きします。デフォルトは`~/.orbit/graph.duckdb`です。

インデックス済みリポジトリを一覧表示する

グラフには複数のリポジトリを保持できます。内容を確認するには次のコマンドを実行します。

orbit list
orbit list -F json

各行にはリポジトリのパス、ブランチ、コミット、インデックス作成ステータス、最終インデックス作成日時、およびステータスがerrorの場合はエラーメッセージが表示されます。

+------------------------+--------+------------+---------+---------------------+---------------+
| repo_path              | branch | commit_sha | status  | last_indexed_at     | error_message |
+------------------------+--------+------------+---------+---------------------+---------------+
| /home/dev/workspace/kg | main   | 9606ae8... | indexed | 2026-05-18 10:14:02 |               |
| /tmp/cli-test          | main   | 654f3a6... | indexed | 2026-05-18 10:13:55 |               |
+------------------------+--------+------------+---------+---------------------+---------------+

インデックス作成に失敗したリポジトリはstatus = errorとerror_messageに理由が記録されます。これにより、失敗したリポジトリや処理できないリポジトリが一覧から消えることなく確認できます。

フラグ	説明
`-F`、`--format`	`table`（デフォルト）、`json`、`ndjson`、または`csv`。
`--db`	DuckDBのパスを上書きします。デフォルトは`~/.orbit/graph.duckdb`です。

まだ何もインデックス作成されていない場合、orbit listは0で終了します。テーブルビューには何も表示されず、構造化フォーマットは有効な空の出力（jsonの場合は[]、ndjsonの場合はレコードなし）を返すため、orbit list -F json | jqのようなパイプラインも正常に動作します。

MCPサーバーとして実行する

stdioを通じてローカルグラフをMCP対応のAIエージェントに公開します。

orbit mcp serve

~/.orbit/graph.duckdbに対してrun_sql、get_graph_schema、indexを提供します。クライアントごとの設定についてはMCPで接続するを参照してください。

AIアシスタントをセットアップする

orbit setupは、AIコーディングアシスタントがgrepを使用する前にグラフを参照するよう設定します。設定するアシスタントの名前を指定します。

orbit setup claude

サポートされているアシスタントはclaude、codex、opencode、piです。デフォルトでは、ガイダンスはリモートのGitLab Orbitグラフを参照します。ローカルグラフを参照するよう変更するには、--localを渡します。

orbit setup claude --local

変更内容

このコマンドはユーザー自身のファイルを変更します。単独では実行されず、ユーザーが呼び出したときのみ実行されます。

指定したアシスタントごとに、orbit setupは以下を実行します。

CLAUDE.mdやAGENTS.mdなどのアシスタントの指示ファイルにブロックを追加します。ブロックはとマーカーの間に配置され、マーカーの外側はそのまま保持されます。コマンドを再度実行すると、2つ目のコピーを追加するのではなく、既存のブロックが置き換えられます。
アシスタントがサポートしている場合、アシスタントのJSON設定にエントリを追加します。Claude Codeの場合はsettings.json内のPreToolUseフック、OpenCodeの場合はプラグインファイルとその登録です。エントリにはorbitマーカーが付与され、マーカー付きのエントリのみが置き換えまたは削除されます。

デフォルトでは~/.claude/CLAUDE.mdなどのユーザーグローバル設定に書き込みます。現在のプロジェクトに書き込むには--projectを渡し、特定のプロジェクトディレクトリを対象にするには--dir <path>を渡します。

orbit setupが既存のファイルを初めて変更する前に、元のファイルを同じ場所に<name>.orbit-backupとしてコピーします。元の状態に戻したい場合は、そのコピーを手動で復元してください。既存のバックアップは上書きされないため、コピーには常にorbit適用前のバージョンが保持されます。

--projectの使用には注意が必要です。プロジェクトの指示ファイルは通常バージョン管理にコミットされるため、変更がgit statusに表示され、チームメンバーに影響する可能性があります。デフォルトのユーザーグローバルスコープはユーザー自身にのみ影響します。

設定を削除する

変更を元に戻すには、次のコマンドを実行します。

orbit setup claude --remove

これにより、マーカーで区切られたブロックとマーカー付きのJSONエントリが削除され、各ファイルの残りの部分はそのまま保持されます。ファイルにorbitエントリのみが含まれていた場合、そのファイルは削除されます。アシスタント名を省略すると、すべてのアシスタントのセットアップが削除されます。バックアップファイルは削除されません。

orbit setupによるファイルの変更を避けたい場合は、このコマンドをスキップし、同じ指示ブロックとフックを手動で追加してください。

ストレージ

グラフは~/.orbit/graph.duckdbに保存されます。複数のリポジトリが同じデータベースを共有します。最初からやり直すにはファイルを削除してください。

CLIを設定する

orbit configは~/.orbit/settings.jsonに保存された設定を読み書きします。保存された設定は以降のすべての実行に適用されます。

orbit config list                          # all settings and their saved values
orbit config get telemetry.enabled         # one setting
orbit config set telemetry.enabled false   # save a setting

設定	値	デフォルト	説明
`telemetry.enabled`	`true`、`false`	`true`	CLIが使用状況テレメトリを送信するかどうか。

テレメトリ

CLIはGitLabプロダクト分析サービスに使用状況イベントを送信し、チームがGitLab Orbitの使用状況を把握できるようにします。各イベントには実行されたコマンドのみが記録され、リポジトリの内容、ファイルパス、クエリテキストは送信されません。テレメトリはデフォルトで有効です。

保存された設定またはCI用の環境変数で無効にできます。

orbit config set telemetry.enabled false   # persists for every run
export ORBIT_TELEMETRY_ENABLED=false        # for CI or one shell

環境変数は保存された設定より優先されます。

変数	説明
`ORBIT_TELEMETRY_ENABLED`	`false`でテレメトリを無効化、`true`で有効化します。保存された設定より優先されます。
`ORBIT_TELEMETRY_COLLECTOR_URL`	テスト用に別のコレクターにイベントを送信します。デフォルトはGitLabコレクターです。

課金

GitLab Orbit LocalはGitLabクレジットを消費しません。すべての処理はローカルで行われます。

次のステップ

MCPで接続する - Claude Code、Codex、その他のエージェントをローカルグラフに接続します。
glabでGitLab Orbit Localを使用する - glab orbit localを通じてCLIを呼び出します。
スキーマリファレンス - 利用可能なノードタイプとプロパティ。
Cookbook - 一般的なユースケース向けのコピー＆ペーストクエリ。

GitLab Orbit CLIでGitLab Orbit Localを使用する（orbit）