Vectreal

@vctrl/cli

Vectreal のコマンドラインツールです。一度サインインすれば、選択した組織でターミナルやエージェントに代わりに操作させることができます。

現在は非公開です。npm で公開されるまでは、ワークスペースのルートから pnpm の -s を付けて実行してください。

pnpm -s vectreal login

-s を付けないと、CLI の実行前に pnpm が独自のバナーを stdout に出力するため、--json の出力を読み取る処理が動作しなくなります。

コマンド

コマンド	内容
vectreal login [--origin <url>] [--no-browser]	ブラウザーでサインインし、セッションを OS のキーチェーンに保存します。以降のコマンドで使うオリジンを記憶します。
vectreal whoami [--json]	セッションが使用するユーザー、組織、ロール、スコープを表示します。
vectreal init [--project <id> | --create <name>]	.vectreal/project.json を書き込んで、現在のディレクトリをプロジェクトに関連付けます。
vectreal logout	サーバー上のセッションを終了し、このマシンからも削除します。
vectreal mcp	エージェントがストリームを閉じるまで、stdio（MCP）経由でエージェントに Vectreal のツールを提供します。
vectreal mcp install [--origin <url>]	この CLI と同じ方法で起動するよう、現在のディレクトリの .mcp.json にサーバーを登録します。

オリジンには、--origin、VECTREAL_ORIGIN、最後にサインインしたオリジン、https://vectreal.com の順で適用されます。平文の http は localhost でのみ使用できます。

MCP サーバー

vectreal mcp は、以下のツールをエージェントに提供します。

ツール	内容
search_docs, read_doc	Vectreal のドキュメントを検索して読みます。サインインは不要です。
whoami, list_projects, create_project, list_scenes	セッションのユーザーと、組織のプロジェクトおよびシーンを確認します。
create_scene_from_file	ローカルの GLB を、そのままドラフトシーンとしてアップロードします。
describe_model	ローカルの GLB のサイズ、メッシュ、マテリアル、アニメーションクリップ、およびレンダリングせずにビューアーで配置される位置を確認します。
get_scene_settings, update_scene_settings	すべての設定セクションを読み取り、環境、操作、境界、シャドウ、表示設定を変更します。
publish_scene, unpublish_scene	パブリッシャーと同様にローカルの GLB を圧縮（Draco、KTX2）して公開します。または、シーンをオフラインにします。
get_embed_snippet	公開済みシーンのスニペットとプレビュー URL を取得します。要求に応じて埋め込みキーを作成し、ドメインを許可します。

projectId を受け取るツールでは、vectreal init で関連付けたプロジェクトが既定で使われます。エージェントが CLAUDE_PROJECT_DIR を設定している場合、サーバーはそのディレクトリからプロジェクトを探し、設定されていない場合は起動元のディレクトリから探します。保存済みのセッションでサインインするため、先に vectreal login を実行してください。セッションなしでツールを呼び出すと、その旨が表示されます。

Claude Code に登録するには、プロジェクトディレクトリで次を実行してください。

pnpm -s --dir <path to this repo> vectreal mcp install

書き込まれるエントリには、このマシン上のパスが記載されます。@vctrl/cli が npm で公開されるまでは、.mcp.json をバージョン管理の対象に含めないでください。

出力と終了コード

--json を指定した場合、結果は JSON として stdout に出力されます。それ以外はすべて stderr に出力されます。

コード	意味
0	完了
1	失敗
2	使用方法が誤っています
3	サインインしていない、またはサーバーがセッションを受け付けなくなりました。vectreal login を実行してください

セッションの保存場所

セッションは OS のキーチェーン（macOS Keychain、Windows Credential Manager、Linux の Secret Service）に、オリジンごとに 1 件保存されます。ヘッドレスの Linux マシンで Secret Service が利用できない場合など、キーチェーンを使用できない場合は、代わりに $XDG_CONFIG_HOME/vectreal/credentials.json（既定値は ~/.config/vectreal）に保存されます。その場合、各コマンドは stderr にその旨を出力します。macOS と Linux では、このファイルを読み取れるのはユーザー本人だけです。Windows では、プロファイルフォルダーのアクセス許可に依存します。

ローカルスタックに対するサインイン

ローカルの Supabase スタックに CLI の OAuth クライアントを一度登録してから、CLI の接続先を開発サーバーに設定してください。

pnpm nx run vectreal-platform:supabase-register-cli-client

pnpm -s vectreal login --origin http://localhost:4200