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）

単一の .nui ファイルまたはディレクトリを指定して構文を検証します。プロジェクトルート相対、カレントディレクトリ相対、Windows 絶対パス、WSL マウントパス（/mnt/...）に対応し、ディレクトリ指定時は配下のすべての *.nui を再帰的に検証します。

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

# ディレクトリ内のすべての NUI プログラムを一括検証
$ nuime validate programs/

実行（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 --tail 50
[truncated: showing last 50 of 210 lines (use --full for complete log)]
verified=true
run_id=2026-10-05T161205_3f9a2c
program_path=programs/sample.nui
succeeded=true
expectations_ok=1/1
failed_steps=0
...

$ nuime log --summary
verified=true
run_id=2026-10-05T161205_3f9a2c
program_path=programs/sample.nui
succeeded=True
started_at=2026-10-05T16:12:05.6789000+09:00
finished_at=2026-10-05T16:12:07.1025000+09:00
judgment=OK: verified
hint=Use 'nuime log  --full' for the complete log, or '--tail 50' for recent lines.

外部エージェントや CI 環境でのトークン消費・文脈圧迫を防ぐため、nuime log は既定で末尾 200 行 / 12,000 文字に切り詰められます。全文は --full、要約は --summary、件数絞り込みは --tail <N> で取得できます。

ヘッドレス Desktop の管理

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

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

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

注意: nuime status の relay_port と relay_key は、CLI オプション、環境変数（NUIME_DESKTOP_RELAY_*）、または既定値に基づき表示されます。

WSL (Windows Subsystem for Linux) での利用: WSL 上のシェルから nuime serve /mnt/c/... のようにパスを渡した場合、Windows パス（C:\...）へ自動変換されます。なお、/home/... などの Linux ネイティブ領域は Windows プロセスから直接アクセスできないため、プロジェクトは Windows ドライブ配下（/mnt/c/...）に配置してください。

シークレット管理

$ 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 → プロジェクトシークレットの順に解決し、 シークレット ID は nuiproject.yaml → mcp.http.authSecret（既定 mcp_http_auth）で指定します。 nuime CLI も --token → NUIME_MCP_AUTH_TOKEN → プロジェクトシークレットの同じ順序で解決するため、 nuime secret set mcp_http_auth だけで両方が繋がります。

前提条件

• Nuime デスクトップが起動している（GUI または nuime serve によるヘッドレス）
• NVDA がインストールされ、Desktop 内蔵リレー（127.0.0.1:6837）に接続していること（nuime status または is_nvda_connected で確認）。 未導入の場合は winget install -e --id NVAccess.NVDA でインストールし、nuime nvda --write-config で nvda.ini の自動接続を設定できます（詳細は nuime nvda を実行）。
• 外部 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 で確認（NVDA のセットアップ・接続手順は nuime nvda を参照）

error=tool_not_available

nuime run の実行には nuiproject.yaml の mcp.http.toolSubset を all に設定し、nuime reload を実行（または Desktop を再起動）してください（validate 等は既定値で利用可能です）

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

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

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

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