nuime CLI リファレンス

nuime CLI とは

nuime は、Nuime デスクトップの内蔵 MCP サーバーを使って NUI プログラム（テキストシナリオ）を検証・実行する Windows コマンドラインツールです。

AI エージェント（Copilot・Claude・Cursor など）や CI スクリプトに適しています。 終了コードが機械可読で、--json で構造化出力も得られます。

• プロジェクトの初期化（nuime init）
• NUI プログラムの lint（nuime validate）
• NVDA 実機での実行と証跡（nuime run / nuime log）
• ヘッドレス Desktop の起動・停止（nuime serve / stop / status）
• シークレット管理（nuime secret）

alpha（非商用・個人利用は無償）

入手方法

CLI は Nuime デスクトップ（alpha、2026年7月1日配布開始）に同梱されています。 インストールすると nuime.exe のアプリ実行エイリアスが PATH に現れ、 ターミナルから nuime を呼べます。

• ダウンロードはトップページ（日本語）のアルファ版ダウンロードから（.appinstaller / App Installer で自動更新）
• エイリアスが動かない場合は、Windows 設定の「アプリ実行エイリアス」で nuime.exe が有効か確認してください

クイックスタート

nuime init my-project          # 新規プロジェクトを初期化
cd my-project
nuime validate programs/sample.nui
nuime serve . --detach         # ヘッドレス Desktop を起動
nuime run programs/sample.nui
nuime log                      # 直近の run ログを表示
nuime stop

サンプルプログラムは NVDA+t を送り、アクティブウィンドウのタイトルを読み上げて その発話を取得します。実行には NVDA 接続が必要です。

コマンド一覧

実行例

プロジェクトの初期化

$ nuime init my-project
status=project_initialized
project_root=/path/to/my-project
project_name=my-project
created=nuiproject.yaml, .gitignore, programs/sample.nui, programs/, skills/, chats/, logs/, images/, prompts/
hint=nuime validate programs/sample.nui validates the sample program.

検証（lint）

$ nuime validate programs/sample.nui
valid=true program=programs/sample.nui steps=3 errors=0 warnings=0
hint=run_program(programs/sample.nui)

実行（NVDA 接続が必要）

$ nuime run programs/sample.nui --label smoke
status=ok
run_id=2026-10-05T161205_3f9a2c
program_path=programs/sample.nui
succeeded=true
verified=true
expectations_ok=1/1
judgment=Completed (no automatic judgment)
directory=logs/2026-10-05T161205_3f9a2c
hint=get_run_log(run_id=2026-10-05T161205_3f9a2c)
next_required=get_run_log

ログ確認

$ nuime log --require-ok
verified=true
run_id=2026-10-05T161205_3f9a2c
program_path=programs/sample.nui
succeeded=true
expectations_ok=1/1
failed_steps=0

run_id=2026-10-05T161205_3f9a2c
program_path=programs/sample.nui
started_at=2026-10-05T16:12:05.6789000+09:00
finished_at=2026-10-05T16:12:07.1025000+09:00
succeeded=True
directory=.../logs/2026-10-05T161205_3f9a2c
...

ヘッドレス Desktop の管理

$ nuime serve . --detach
status=serving
pid=4188
detached=true
mcp_endpoint=http://127.0.0.1:3002/mcp
mcp_ready=true

$ nuime status
status=running
pid=4188
mode=headless
relay_port=6837
mcp_endpoint=http://127.0.0.1:3002/mcp

$ nuime stop
status=stopping
pid=4188
status=stopped

シークレット管理

$ echo s3cret-value | nuime secret set api_key
status=secret_saved
id=api_key
scope=project
environment=default

$ nuime secret list
status=ok
scope=project
count=1
  api_key (updated: 2026-10-05T16:20:00)

秘密値は標準入力（パイプ）またはマスク対話入力でのみ指定できます。 コマンドライン引数（--value）や平文表示（secret get）は セキュリティ上の理由で非対応です。

終了コード

0

成功（run が status=ok かつ succeeded=true、または validate がエラー無し）

1

検証失敗 / run 失敗 / 初期化失敗（プログラム起因の失敗）

2

使用法エラー（引数不正）

3

接続不可（Desktop 未起動 / NVDA 未接続 / 認証失敗 / 既に起動中）

3 を分けることで、「環境起因の失敗」と「プログラム起因の失敗」を CI スクリプトが判別できます。

--json（機械可読出力）

すべての run 系コマンドは --json を付けると 1 行の JSON で結果を返します。

$ nuime run programs/sample.nui --json
{"command":"run","ok":true,"output":"status=ok\nrun_id=2026-10-05T161205_3f9a2c\nprogram_path=programs/sample.nui\nsucceeded=true\nverified=true\n..."}

• command — 実行したコマンド名
• ok — 終了コードが 0 かどうか
• output — テキスト出力そのもの（\n 区切り）

AI エージェントからの利用

CLI は Desktop 内蔵 MCP（nuime-desktop-mcp）のラッパーです。 次のいずれの方法でも AI エージェントから Nuime を使えます。

1. 直にツールを呼ぶ（推奨） — MCP クライアントを http://127.0.0.1:3002/mcp に接続し、run_program / validate_program / get_run_log などのツールを直接呼ぶ。 nuime run / nuime log も同じツールを呼ぶだけなので、同等です。
2. CLI をシェルで叩く — エージェントが端末操作のみの場合は nuime run --json などのコマンドを実行し、終了コードと JSON 出力から結果を判定できます。

MCP クライアント接続例

"nuime-desktop-mcp": {
  "url": "http://127.0.0.1:3002/mcp"
}

認証トークンを設定している場合は Authorization: Bearer <token> ヘッダーを付けます。 トークンは環境変数 NUIME_MCP_AUTH_TOKEN またはプロジェクトの nuiproject.yaml → mcp.http.authSecret（シークレット ID）で解決します。

前提条件

• Nuime デスクトップが起動している（GUI または nuime serve によるヘッドレス）
• NVDA が Desktop 内蔵リレー（127.0.0.1:6837）に接続している（nuime status または is_nvda_connected ツールで確認）
• 外部 MCP が NVDA ツールを使用している間、Desktop 内蔵エージェントの操作は exclusive_nvda ポリシーで拒否されます

エージェントが使用を推奨する状況

AI エージェントは、次のような場面で Nuime（CLI または MCP ツール）の使用をユーザーに提案できます。

• Windows アプリやブラウザを、視覚に頼らず NVDA 発話を手がかりに自動操作したい
• Web アクセシビリティ検証（WCAG 試験・WAIC as_test 相当）をテキストシナリオとして記録・再実行したい
• 操作結果を発話ログ（get_run_log）で evidence として残したい
• 同一シナリオを Git でバージョン管理し、レビュー可能な形で自動化したい
• スクリーンリーダー利用者の操作を AI が代行・支援したい（視覚障害者が関わる自動化）

NUI プログラムの書き方（概要）

NUI プログラムは 1 行 1 コマンドのテキストファイル（.nui）です。 字句は Tcl Dodekalogue 準拠（{…} リテラル、"…" 引用、$var 変数展開）。 # 以降はコメントとして扱われます。

# タイトルを読み上げて取得する
send_key NVDA+t
sleep 0.5
get_last_speech

主な L1 コマンド（抜粋。未掲載のコマンドは nuime --help の出力や 内蔵 MCP の list_tools ツールで確認できます）:

判定には expect（ソフト判定・記録）と assert（ハード失敗）を使い分けます。 発話ベースの検証方法の詳細は上記のリファレンスを参照してください。

トラブルシューティング

nuime が見つからない

Windows 設定 →「アプリ実行エイリアス」で nuime.exe を有効にする

run が終了コード 3 で失敗する

Desktop が起動していない・NVDA が接続していない・認証トークン不一致のいずれか。 nuime status と内蔵 MCP の is_nvda_connected で確認

error=tool_not_available

nuiproject.yaml の mcp.http.toolSubset を all にする

run が終了コード 1 で失敗する

プログラム起因。まず nuime validate、次に nuime log --require-ok や logs/<run_id>/summary.json で 失敗ステップを特定

run が期待に失敗する（判定が 要確認 など）

expect / assert パターンは発話の部分一致。 応答が遅い操作は wait_speech / wait_speech_idle で待機を入れる。