openresearch-cli

OpenResearch CLI（orx）

orx up は、ローカルの Git リポジトリとローカルデータベースで、プロジェクト、実験ブランチ、実行を管理します。コードの読み取り、差分の確認、編集にはローカルのセッション用ワークツリーを使用してください（orx-git を参照）。

この概要は意図的に短くしてあります。最重要ルールとコマンドのクイックリファレンスを示し、その他の情報は用途別の モジュール を案内しています。orx skill <name> でモジュールを読み込んでください（同梱のインデックスは orx skill の出力の最後に表示されます）。

最重要ルール — 作業を始める前にお読みください

以下の4つのルールが、以降のすべてを規定します。どれか1つでも破ると、結果は通知なく無効になります。これはスタイル上の好みではありません。orx-experiment-tree モジュールでは、その理由を詳しく説明しています。これらは絶対に守るべきルールです。

1. 実行によって結果が出たノードは、決して編集しないでください。 実行によってベースラインが確立されるか、仮説が検証された時点で、ルートを含め、そのノードは固定されます。固定は恒久的なものであり、期待外れの結果も結果であることに変わりはありません。それまでは暫定状態です。ノードの初期設定、依存関係の修正、実行可能にする作業はすべて、そのノード自身のブランチで行います（orx-experiment-tree）。新しい仮説を検証するには、子ノードをブランチとして作成し、その子を編集してください。
2. 実行コマンドと環境は、すべてのノードで同一でなければならない固定の契約です。 子ノードは親の実行コマンドをそのまま継承します。変更しないでください。ノードごとに異なる起動コマンドを設定してはならず、環境変数や環境変数を前置したコマンド（LR=3e-4 python …）を使って動作を変えてもなりません。ノード間で異なってよいのは、そのノードの git ブランチ上にあるコミット済みのコード／設定だけです。ローカルプロジェクトのコマンドは、orx project edit <projectId> --run-command '<cmd>' で一度だけ設定してください。
3. コマンド内のパラメーターではなく、コードを変えてください。 ハイパーパラメーターはコード／設定ファイルに記述し、バリエーションごとに子ブランチを作成してください。実行コマンドを編集したり、環境変数を渡したりして、値を変えてはなりません。各ノードでは、異なるコードに対して同じコマンドを実行するため、記録された結果の要約を比較可能な状態に保てます。
4. ツリーは横ではなく、下に伸ばしてください。 1ラウンド内では少数の選択肢（1つの意思決定に対する選択肢）を試し、次のラウンドではそのラウンドの勝者から下に進んでください。子ノードが横一列に長く並び、孫ノードがないルートは失敗パターンです。orx-experiment-tree モジュールの「Shape the tree」を参照してください。

コマンドを変更したり、環境変数を渡したり、子ノードをブランチとして作成してそのブランチを編集し、さらに下へ進む代わりに、ルートにノードを追加したくなったら、いったん止まってください。それは近道ではなく、避けるべきパターンです。

セットアップ

orx login          # opens a browser, stores a token at ~/.config/openresearch/credentials.json
orx logout         # remove the stored token

• API のベース URL は、--api-url → OPENRESEARCH_API_URL → 組み込みのデフォルト値の順に決定されます。ローカル以外で使用する場合は、OPENRESEARCH_API_URL を設定してください。
• ローカルのプロジェクトコマンドと実行コマンドにトークンは不要です。OpenResearch の計算リソース、インスタンスのプロビジョニング、アカウント設定には orx login が必要です。

コマンドのクイックリファレンス

プロジェクトを対象とするコマンドにはプロジェクト ID、実験を対象とするコマンドには実験 ID、実行を対象とするコマンドには実行 IDを指定します。混同しないでください。ID はそれぞれ orx projects、orx project view、orx runs で取得できます。以下の各グループには、フラグとルールの全容を説明するモジュール（orx skill <name>）があります。

認証

コマンド	動作
orx login [--api-url <url>] [--device]	ブラウザーを開き、ループバック OAuth を実行して、トークンを保存します。--device（SSH 接続時のデフォルト）を指定すると、任意のデバイスで承認するためのリンクとコードが表示されます。
orx logout	保存されているトークンを削除します。

検索（プロジェクトおよび実験を対象）

コマンド	動作
orx projects [--json]	ローカルの orx ストアにあるプロジェクトを一覧表示します。
orx orgs [--json]	OpenResearch の計算リソースで利用可能な組織 ID を一覧表示します（ログインが必要です）。
orx project view <projectId>	ローカルプロジェクトの詳細と実験ツリーを表示します。実験 ID はここで確認できます。
orx runs <projectId> [--experiment <id>]	実行を新しい順に表形式で一覧表示します。実行 ID はここで確認できます。

実行の証拠（実行単位）— モジュール orx-logs

コマンド	説明
orx logs <runId>	ローカルのログパス、サイズ、短いプレビューを表示します。証拠の全容を確認するには、ファイルを調べてください。

実験の作成と実行（書き込み）— モジュール orx-create、orx-compute、orx-git

コマンド	説明
orx up	ローカルダッシュボードを開き、ローカルプロジェクトをインポートまたは作成します。
orx project edit <localProjectId> [--name "<n>"] [--run-command "<cmd>"]	ローカルプロジェクトの名前または固定の実行コマンドを編集します。
orx project share <localProjectId> [--out <file> | --publish] [--chat <chatId>... | --no-chats] [--no-logs] [--no-artifacts]	ユーザーから依頼された場合に限り、プロジェクトのコード、実験ツリー、完了した実行、ログ、成果物、チャットを .orx ファイルとして保存し、共同作業者に送信します。--chat を指定すると、指定したチャットだけに絞り込めます。--publish はリンクを求められた場合に限り、プロジェクトを openresearch.sh にアップロードし、誰でも開けるリンクを表示します。再公開すると、同じリンクが更新されます。
orx project unpublish <localProjectId>	プロジェクトの公開リンクとファイルを削除します。
orx project import <file.orx | link> [--path <dir>]	共有された .orx ファイルまたは openresearch.sh/p/... リンクを、新しいローカルプロジェクトとして開きます。ツリー、実行、選択したチャットも含まれます。
orx create-experiment <localProjectId> --title "<t>" [...]	ローカルの実験ノードを追加し、その Git ブランチを表示します。
orx compute status / show <backend> / test <backend>	マシン全体の計算設定と準備状況を確認します。
orx compute configure <backend> --help / default set <backend> / connect <backend>	計算環境を設定するか、認証します。orx-compute を読み込みます。
orx compute instructions show --json	設定または起動の前に、マシン全体に適用されるカスタムレシピとそのリビジョンを確認します。
orx compute [--gpu <id>] [--count <n>] [--provider <name>] / orx compute --cpu	GPU／CPU 計算カタログを一覧表示します。
orx instance create <orgId> (--gpu <id> … | --cpu <flavor> …)	組織内でスタンドアロンインスタンスを起動します。orx-instances を参照してください。
orx exp status/run/cancel/wait/wake <localExpId>	ローカルの実験ノードの状態を確認、実行、キャンセル、待機するか、起動予約を登録します。
orx exp move/archive/unarchive/delete <localExpId>	実験ノードの親を変更、非表示、復元、または完全に削除します。orx-experiment-tree を参照してください。
orx exp desc <expId> [--set "<text>" | --stdin]	実験の説明を読み取るか、上書きします。

実行によって変更された内容の差分比較を含め、ノードのコードを読み取る、または編集するには、ローカルセッションのワークツリーで通常の Git を使用します。orx-git モジュールを参照してください。

文献と論文 — alphaXiv / OpenAlex / bioRxiv / PubMed（ログイン不要）— モジュール orx-lit-review

学術・研究に関するクエリ（論文、著者、ブログ、モデルのリリース）では、Web 検索の前に使用してください。

コマンド	説明
orx discover keyword "<query>"	一致箇所のスニペット付きで、alphaXiv の全文検索機能を呼び出します。
orx discover embedding "<query>"	alphaXiv のセマンティック検索機能を呼び出します。メインエージェントが候補に順位を付け、焦点を絞った追加検索を判断します。orx-lit-review を参照してください。
orx discover openalex "<query>"	分野横断型の OpenAlex 学術グラフを検索します。
orx discover biorxiv "<query>"	OpenAlex の bioRxiv インデックスを通じて、bioRxiv のプレプリントを検索します。
orx discover pubmed "<query>"	NCBI E-utilities を通じて、PubMed の生物医学文献を検索します。
orx paper <id|url> [--source <source>] [--full]	論文を取得します。alphaXiv のレポートでは全文への自動フォールバックが行われ（--full は生テキストを強制します）、OpenAlex／bioRxiv／PubMed ではメタデータと要約を取得します。ソースは ID から自動判定されます。

スキルとテンプレート — モジュール orx-customize

コマンド	説明
orx skills add <path>	SKILL.md ファイルまたはスキル ZIP から再利用可能なスキルを保存し、複数のプロジェクトで使用できるようにします。
orx templates add <path>	.tex ファイルまたはテンプレート ZIP から再利用可能な LaTeX テンプレートを保存し、複数のプロジェクトで使用できるようにします。

メタ

コマンド	説明
orx skill [name[/resource]]	この概要、バンドルされたモジュール、または compute/hf のような遅延読み込みされるモジュールリソースを表示します。
orx feedback --kind <bug|feature_request|frustration> --summary <summary> --details <details>	重要な OpenResearch のバグ、機能リクエスト、またはユーザーの不満をメンテナーに報告します。orx-feedback モジュールを参照してください。

モジュール

詳細は各モジュールに記載されています。orx skill <name> で読み込んでください（1 行の説明付きバンドル一覧は、orx skill の出力末尾に表示されます）。

• orx-experiment-tree — 実験ツリーモデル、自動研究ループ、orx exp desc。
• orx-create — ローカルプロジェクトを初期化し、ローカル実験ノードを追加します。
• orx-compute — 実行を開始して監視します。バックエンドを特定した後、バンドルされたリファレンスを読んでください。
• orx-instances — 手動作業用の永続的なスタンドアロンマシンを作成します。
• orx-git — 通常の git を使ってノードのコードを読み取り、編集し、差分を表示します。
• orx-agent-delegation — orx の MCP ツールを使って、他のモデルやチャットに作業を委任します。
• orx-logs — 進捗確認、デバッグ、測定のために、永続化された実行出力を取得します。
• orx-results — 測定された実験結果を解釈、比較、要約します。
• orx-reports — プロジェクトの artifacts ディレクトリに、永続的な研究成果を作成します。
• orx-figures — matplotlib または TikZ で出版品質の図を作成します。プロットコードを書く前に読み込み、続けて図の種類に対応するリファレンスを 1 つ読んでください。
• orx-customize — プロジェクト間で再利用できるスキルと LaTeX テンプレートを追加します。
• orx-paper — PDF にレンダリングしてコンパイルできる論文またはプレプリントを LaTeX で作成します。
• orx-feedback — 研究の詳細を漏らさずに、重要な OpenResearch のバグ、機能リクエスト、ユーザーの不満を報告します。
• orx-lit-review — メインエージェントによる複数コーパスの検索、情報源を選択した追加調査の方針、論文の内容を扱います。学術・研究に関する問い合わせの際に、最初に使うことを推奨します。

一般的なワークフロー

プロジェクトの状況を把握する（読み取り専用の調査）：

orx projects                     # find the project id
orx project view <projectId>     # see the tree, pick an experiment id
orx skill experiment-tree        # the model + the auto-research loop
orx runs <projectId>             # find a run id
orx logs <runId>                 # locate its log, then inspect the file

プロジェクトを実際に目標に向けて進めるには、各ノードのコードを Git ブランチ上で編集し、作業を継続しながら、orx-experiment-tree モジュールの自動研究ループに従ってください。実行が完了するたびに、次の 4 つの選択肢から判断します。実行で何も明らかにならなかった場合は同じノードを修復し、別の兄弟ノードを追加してラウンドを補充し、勝者を昇格させて次の階層へ進むか、停止します。