CLIリファレンス

LinuxまたはmacOSとNode.js 22以上があれば、任意のディレクトリで実行できます。

npx @omochi-ui/cli hub
npx @omochi-ui/cli --help

npm install -g @omochi-ui/cliまたはcargo install omochi-cli --lockedでインストールすると、以下の例のようにomochi-uiを直接使えます。ダッシュボード画面は同梱され、hubがローカルGatewayも自動起動します。対応環境とソースビルドはインストールを参照してください。ビルド済みチェックアウトではbun run omochi-uiを使います。

コマンド一覧

コマンド	用途	注意点
up --open [FILE]	プリセットのサービス・Hub・一時ダッシュボードを起動	設定ファイルを指定可能
dev -- COMMAND [ARGS...]	アプリと標準入出力ブリッジを起動	プレビュー画面は別途起動
hub	ダッシュボードサーバー	必要ならローカルGatewayを起動
gateway	起動中のアプリをHubへ中継	アプリ自体は起動しない
pair --name NAME	標準入力の招待を登録	通常通信とは別の登録操作
status	Gateway接続状態の確認	稼働中Hubへ問い合わせ
id	自分のEndpointIdを表示	初回はIDを作成
trust list	登録済みの相手を一覧	名前とEndpointIdを確認
trust forget NAME_OR_ENDPOINT_ID	相手の権限を取り消す	稼働プロセスの確認失敗はエラー
generate catalog	カタログから型付きバインディングを生成	ローカルスキーマのみ利用

up

omochi-ui up --open examples/quickstart/omochi.toml

プリセットが指定するプロセスとHubを起動します。配置は保存するまで一時的です。Ctrl+Cで所有するプロセスを停止します。

dev

# ターミナル1: チェックアウトのルート
bun run --filter @omochi-ui/dev-server dev
# ターミナル2
bun run omochi-ui dev -- uv run --project examples/python examples/python/app.py

既定のブリッジは5555、プレビューは5173です。配布アーカイブに開発用Vite画面は含まれません。

hubとgateway

omochi-ui hub
omochi-ui gateway --remote --pair --name workstation

Hubは既定で127.0.0.1:5555にバインドします。ポート変更は--port、Origin許可の追加は--allow-originで行います。外部公開が必要でなければ既定のループバックを維持してください。Gatewayのリモート待受は明示的な--remoteが必要です。

HubにGatewayを追加する招待を発行するには、アプリ側のマシンでgateway --remote --pairを実行します。Web URLの既定値はhttps://app.omochi.fyi/です。--web-urlには、認証情報・クエリ・フラグメントを含まない2048文字以下の絶対HTTPS URLを指定します。--pairで新しい招待を発行したときだけ、ネイティブ用招待とブラウザ用リンクを表示します。独自のホストを使う場合は--web-urlで上書きできます。

ネイティブ招待と#g:リンクは、同じパディングなしbase64url JSONと一時的な秘密を含みます。旧hex形式や#connect:形式は受け付けません。非公開の経路で共有してください。

ホストされたブラウザーでオーナーとしてHubに接続し、Gatewayリンクを開いて このハブに追加 を押すと、ネイティブHubのidentityをGatewayに登録します。そのHubはGatewayが公開するすべてのサービス・操作・リソースにアクセスできます。共有ビューアーは登録できません。ブラウザーの接続記録の削除だけではGatewayの信頼は失効せず、取り消すにはGatewayでtrust forget <hub-endpoint-id>を実行します。Flutterアプリでは この端末に追加 で端末内Hubを登録する経路も使えます。詳細は接続ガイドを参照してください。

ネイティブHubのダッシュボードを共有するには、hub --remoteで起動し、ローカル画面の ダッシュボードを共有 から権限付き共有リンクを作成します。Web URLの既定値はhttps://app.omochi.fyi/で、--web-urlで上書きできます。--web-urlを指定する場合は--remoteが必要です。--remoteは--offlineとは併用できません。受信者のブラウザはこのHubへ接続し、Gatewayとは直接ペアリングしません。

release版Hubは既定でhttps://relay.omochi.fyi、debug版はn0リレーを使います。ブラウザは共有リンクに含まれるリレーへ接続し、本番リレーの正確なURLにだけ共通の入場トークンを付けます。ダッシュボードへのアクセス権限はHubが別途確認します。

全体の管理には、ローカル接続画面の オーナーブラウザを登録 でリンクを発行し、対象ブラウザーで承認します。オーナー登録・取り消しはローカル画面専用です。ホストされたオーナーはボード・共有の管理とGateway登録を行えます。オーナー権限とGatewayの信頼は別です。

pair・status・trust

pairはネイティブomochi://invite/とHTTPS #g:リンクの両方に対応します。秘密がシェル履歴に残らないよう標準入力へ貼り付けます。マシン間接続に登録・確認・失効の手順があります。--offlineで公開検索とリレーを止め、--relayで専用リレーを選びます。statusは接続試行と診断を表示します。

カタログ生成

omochi-ui generate catalog --catalog ./catalog.json --name ProductCatalog \
  --typescript ./src/product.ts --python ./src/product.py --rust ./src/product.rs

出力言語は一部だけ指定できます。--checkは既存生成物が古いと失敗します。生成だけではブラウザにカスタム部品の実装は追加されません。

コンポーネント名は生成する型名と通信上の名前にそのまま使うため、[A-Za-z_][A-Za-z0-9_]*に一致する必要があります。TypeScriptでは各位置に$も使えます。Pythonではクラス内の参照に名前マングリングが働くため、先頭が__の名前には対応していません。Rustでは生成するComponentPropsがSDKのtraitと重複するため、Componentを使えません。型名にはPropsを付けるため、classなどの予約語は使えます。制約は指定した出力言語にだけ適用し、未対応の名前があればどの出力も変更せずにエラーになります。

enumは文字列・真偽値・数値・nullを扱え、配列やunion内でもJSONの型を保ちます。空のenumや、オブジェクト・配列を値に持つenumは出力前にエラーになります。TypeScriptはリテラルのunion、PythonはTrue・False・Noneを使ったLiteralを生成し、小数の値はfloatに広げます。Rustは文字列プロパティの名前付きenumを維持し、同じ型の非文字列enumにはbool・serde_json::Number・()、型が混在するenumにはValueを使います。ネストした文字列enumはStringになります。広げた型はJSONの値を保ちますが、宣言されたenumの値だけに制限するものではありません。Rustの文字列variant名が変換後に重複する場合は数値の接尾辞を付けます。

Pythonは元のプロパティ名を維持し、classのような予約語やdata-labelのようなクラスのフィールドにできないキーには関数形式のTypedDictを使います。これらのキーは辞書で指定でき、必須・任意の区別も保たれます。

TypeScriptとPythonではコンポーネントのプロパティ名keyをビルダーのノードキー引数に予約しています。allOfやローカル参照を含め、propertiesまたはrequiredにkeyがある場合、TypeScriptまたはPython出力の指定はどの出力も変更せずにエラーになります。これらの言語向けにはプロパティ名を変更してください。Rustではノードキーをプロパティとは別の引数で渡すため使用できます。入れ子のオブジェクト内のキーは3言語とも使用できます。

ローカル$refと兄弟キーワードはJSON Schema 2020-12の参照規則に従い、参照先と兄弟の両方の制約を適用します。たとえばenum: ["a", "b"]への参照にenum: ["b", "c"]を添えると、TypeScriptでは"b"だけを受け付ける交差型になります。descriptionなどの注釈だけでは型を変えません。required・properties・itemsだけの制約には、参照先が保証するobjectまたはarray型を補います。ローカルにプロパティ定義がない必須フィールドはTypeScriptでunknownとし、交差型によって参照先の型も保持します。相対参照はそれぞれの記述元ファイルを基準に解決します。PythonとRustには下記のallOf近似を適用します。

プロパティや配列要素のスキーマでは、$refがなくても隣接する制約を合わせます。たとえば文字列または数値を受け付けるanyOfにenum: ["allowed"]を添えると、TypeScriptでは"allowed"だけを受け付けます。allOfに隣接するオブジェクトのプロパティや必須フィールドも交差型に残ります。PythonとRustにはallOfと同じ近似を適用します。生成する型はJSON Schemaのすべての制約を検証するものではありません。

コンポーネントの型には、コンポーネント自身と入れ子のallOfの各層からプロパティと必須フィールドを収集し、共通mixinも反映します。同名のプロパティはスキーマをallOfとして合成するため、TypeScriptでは層の順序によらずすべての制約が必要になります。同一のスキーマは重複を除き、異なるスキーマの合成にはPythonでは下記の近似、RustではValueを使います。必須フィールドは各層の指定を合わせます。条件分岐の中にあるフィールドは、無条件のコンポーネントプロパティとしては追加しません。

コンポーネントレベルのanyOfとoneOfには対応していません。入れ子のallOfや解決したローカル参照に含まれる場合も、どの出力も変更せずにコンポーネント名とunionのキーワードを示すエラーになります。プロパティのスキーマ内では、配列要素や入れ子のオブジェクトプロパティも含めてunionを利用できます。

Pythonには型の交差演算子がないため、プロパティのallOfで各層が同じPython型になる場合はその型にまとめます。オブジェクト同士ならdict[str, Any]、単一の層ならその型を使い、異なる型の組み合わせや空のallOfはAnyに広げます。他言語と同様にifまたはthenを持つ層は省略し、残る層がなければPythonではAnyを使います。この近似は配列やunion内でも適用され、JSONの値は保ちますが、スキーマの全制約を検証するものではありません。空のスキーマ{}は制約を加えず、TypeScriptではunknown、PythonではAny、RustではValueを使います。真偽値スキーマなど未対応の層は、どの出力も書き込まずにエラーになります。

Rustのフィールドはsnake caseになりますが、JSON出力ではカタログの元のプロパティ名を略語やアンダースコアも含めて維持します。Rustの予約語にはr#typeのようなraw identifierを使い、self・super・crateには末尾に_を付けます。Rustの識別子に変換できない名前や、変換後に同じフィールド名になるプロパティがある場合は、どの出力も書き込まずにエラーになります。

正確なオプションを調べる

omochi-ui --help
omochi-ui dev --help
omochi-ui help hub

設定と保存先とトラブル対応も参照してください。