OMMX CLI のインストールと実行

OMMX CLI のインストールと実行#

ommx コマンドでは、Artifact の内容確認・入出力、Local Registry の管理、 同梱のエージェントプラグインやスキルの取得ができます。単体の実行ファイルとして インストールする方法と、OMMX Python パッケージに付属する CLI を使う方法があります。

CLI を含む Python SDK がすでに uv プロジェクトに導入されている場合は、 プロジェクトのルートで次のように実行できます。

uv run ommx --help

cargo-binstall で単体の実行ファイルをインストールする#

cargo-binstall を インストールし、Rust SDK のリリース から利用する v3 のバージョンを選びます。例えば、公開済みの 3.0.0-beta.6 には CLI のバイナリが添付されています。

cargo binstall ommx@3.0.0-beta.6
ommx --help

cargo-binstall はリリースのメタデータに従って、利用環境に対応するアーカイブを 選択します。単体の実行ファイルは Python 環境がなくても利用できます。

最新の安定版を選ぶ場合は cargo binstall ommx を使います。v3 のプレリリースを 利用する間は、v3 のバージョンを明示してください。バージョンを省略すると安定版の v2 系列が選ばれます。利用したいコマンドを含むリリースを選んでください。 このドキュメントで説明するエージェントプラグイン・スキルのコマンドは 3.0.0-beta.6 より後の機能です。提供状況は Rust SDK のリリースノート と Python SDK のリリースノート を参照してください。

Python パッケージに付属する CLI を使う#

Python の ommx パッケージには、3.0.0b8 から ommx コマンドが付属します。 uv プロジェクトにパッケージを追加すると、プロジェクトの環境で CLI を実行できます。

uv add 'ommx>=3.0.0b8'
uv run ommx --help

プロジェクトの依存関係で選ばれた OMMX のバージョンが使われます。 対応する ommx がすでに依存関係に含まれている場合は、CLI を別途インストールする 必要はありません。同じ CLI バージョンであれば、コマンド構文も同じです。 利用できるコマンドは、インストールしたバージョンによって異なります。

バージョンとコマンドを確認する#

uv run ommx --version
uv run ommx --help
uv run ommx inspect --help

単体の実行ファイルを使う場合は、uv run ommx を ommx に置き換えます。 OMMX の Rust SDK と Python SDK のバージョンは独立して管理されているため、 Python 経由で起動した場合も、ommx --version は Rust CLI のバージョンを表示します。

同梱プラグインや個別のスキルを取得して導入する手順は、 OMMX のエージェントプラグインとスキルを取得・導入する を 参照してください。

保存した記録を削除・復元し、保存領域を整理する#

Local Registry はOMMXのローカル保存領域です。ArtifactやExperimentには、 example.com/team/experiment:obsoleteのような名前（ref）を付けられます。 名前を削除する操作と、データ本体を回収して容量を空ける操作は別です。

以下の./local-registryは、実際に使っている保存領域のパスに置き換えてください。 各コマンドの--rootで対象を明示します。省略するとOMMX_LOCAL_REGISTRY_ROOT、 それも未設定ならOS既定の保存先を使います。

まず対象を確認する#

uv run ommx prune-anonymous --root ./local-registry --experiments --older-than 7d
uv run ommx gc --root ./local-registry

どちらも既定では報告のみで、名前やデータを削除しません。 prune-anonymousは名前を自動生成した匿名Artifactを対象にし、--experimentsで 匿名Experimentも含めます。--older-than 7dは7日以上経過した名前に絞る指定です。 gc（ガベージコレクション）は、どの名前からも参照されなくなったデータ本体の 回収候補を表示します。

一つの名前を削除・復元する#

名前を確認し、例示名を実際の削除対象に置き換えてから実行します。 rmは直ちに名前を削除します。 データ本体はこの操作では削除しません。

uv run ommx rm example.com/team/experiment:obsolete --root ./local-registry

出力のRollback行には、削除した名前と、その内容を識別するManifest digestを含む ommx restore-ref ...コマンドが表示されます。復元するときは、そのコマンドの先頭に uv runを付けて実行してください。--rootも出力に含まれるため、同じ保存先へ復元できます。 同じ名前が既に別の内容を指している場合は、上書きせずエラーになります。

復元には、削除時のデータ本体が残っている必要があります。 必要な復元は、次のデータ回収より先に行ってください。

確認した対象を整理する#

匿名の名前を一括削除する場合は、先ほどの報告を確認してから--deleteを付けます。 削除した名前ごとに復元用コマンドが表示されます。

uv run ommx prune-anonymous --root ./local-registry --experiments --older-than 7d --delete

データ本体の回収は、別途gc --deleteで行います。

uv run ommx gc --root ./local-registry --delete

残る名前やExperimentのcheckpointから参照されているデータは回収しません。 参照されていないデータのうち、データ本体の最終更新から既定で24時間の 猶予期間（grace period）が経過したものを回収します。名前を削除してから24時間の 復元を保証するものではなく、古いデータは削除直後のGCでも回収される可能性があります。 回収後は復元できない場合があります。 書き込み中のデータを保護するため、 通常は猶予期間を短くせず、uv run ommx gc --helpで条件を確認してください。

Pythonから同じ操作を行う場合は、remove_image()、 restore_image()、prune_anonymous()、 gc()を使えます。引数や戻り値の詳細はAPI Referenceを参照してください。

目次