本文へスキップ

ドキュメント コマンドライン

コマンドライン

vmpalはVMPalのコマンドラインツールで、dockerやghと同じように使えます。ターミナル、自作のスクリプト、CIで使用します。VMの作成と起動、VM内でのコマンドの実行、VMとのファイルのコピーができます。VMの画面をウインドウ、ボタン、テキストの一覧として読み取ったり、スクリーンショットを撮ったり、VM内でクリックや入力をしたりすることもできます。さらに、VMPalのHubにあるスクリプトの作成と実行も行えます。

AIエージェントに頼む

vmpalをいちばん手軽に使うには、コーディングエージェントに頼みましょう。VMPalは、お使いのバージョンのVMPalに合ったvmpalのヘルプとガイドをすべてエージェントに渡します。エージェントはコマンドやスクリプトを書いて、その内容を説明します。このMacのターミナルを使えるエージェントなら、実行まで行います。vmpalのインストールには管理者パスワードが必要なため、まだインストールしていない場合は、実行するコマンドをエージェントが教えてくれます。

  1. VMPalで設定 › AIエージェントを開き、このMacのコーディングエージェントによるすべての仮想マシンの管理を許可をオンにします。これで、エージェントがVMとスクリプトも管理できるようになります。vmpalの説明だけなら、この設定がなくてもできます。
  2. Claude Codeに追加、Codexに追加、Grok Buildに追加、Antigravityに追加のいずれかをクリックします。Cursor、VS Code、Kiroなどのエージェントでは、その他… をクリックします。お使いのエージェントが一覧にない場合は、手動設定… で追加する内容を確認できます。その後、エージェントを再起動します。
  3. たとえば、次のように頼みます。
    • 「VMPalのコマンドラインを見せて。」
    • 「UbuntuのVMの新しいクローンでテストを実行するGitHub Actionsのジョブを設定して。」
    • 「このプロジェクトをWindowsのVMにコピーしてビルドするスクリプトを書いて。」

インストール

vmpalはVMPalに含まれています。使うには、PATHに含まれるフォルダにリンクを作成します。

sudo mkdir -p /usr/local/bin
sudo ln -sf /Applications/VMPal.app/Contents/Helpers/VMPalMachine.app/Contents/MacOS/VMPalMachine /usr/local/bin/vmpal

コピーではなく、リンクを作成してください。vmpalはリンクをたどってVMPalを見つけます。リンクがない場合は、フルパスに--cliを付けて実行します。

"/Applications/VMPal.app/Contents/Helpers/VMPalMachine.app/Contents/MacOS/VMPalMachine" --cli <command>

vmpalは、Macにログインしているユーザとして実行してください。VMPalが起動していない場合は、vmpalがバックグラウンドで起動します。

ヘルプを読む

ほとんどのコマンドラインツールと同じく、vmpalにもヘルプが組み込まれています。よくある作業は、ガイドで順を追って説明しています。

vmpal help              # every command
vmpal help run          # one command's options, and its guide
vmpal help ci           # a guide: setup, ci, exec, cp, sign-in or ui
vmpal ui help           # ui's own commands

すべてのコマンドはコマンド一覧にあります。CIの各ジョブをVMの新しいクローンで実行する方法は、CI/CDで説明しています。

基本

  • VMの指定:名前("Windows 11")、ID、または.vmpalフォルダのパスで指定します。IDは先頭の4文字以上でもかまいません。名前とIDはvmpal listで確認できます。cpの<VM>:<path>では、名前かIDを使います。
  • 出力はプレーンテキストです。--jsonを付けると、スクリプトで読み取れるように結果を1行のJSONで出力します。execの場合は、出力を逐次表示する代わりに、最後に結果全体を出力します。-qはIDだけを出力するオプションで、list、create、clone、script list、script run、script runsで使えます。
  • 確認で止まらない:vmpalはコマンドラインで何かを尋ねて止まることがないため、スクリプトやCIでも安全に使えます。実行できないときは失敗し、その理由を表示します。ただし、VMPalが代わりに行えないサインインなど、人の操作が必要な待機もいくつかあります。このMacでスクリプトを実行させる場合、VMPalはこのMacでのスクリプトでの選択に従います。
  • タイムアウト:待機は--timeoutの時間で打ち切られます。90(秒)、90s、10m、2h、1h30mの形式で、最大24hまで指定できます。vmpal uiは例外で、--timeoutはミリ秒か10sの形式で、最大45秒です。
  • エージェントによる操作:各VMには、vmpalとAIエージェントがVM内で作業することを許可する設定があります(設定 › AIエージェント › エージェントによるこの仮想マシンの操作を許可)。exec、cp、run、ssh、ui、sign-inにはこの設定が必要です。start --waitのように、VMがコマンドを実行できるようになるまで待つ操作にも必要です。runでは、クローン元のVMでこの設定が必要です。誰かがオフにしていない限り、オンになっています。vmpal set <VM> --agent-control onで再びオンにできます。
  • Mac全体の設定:vmpalには、このMacのコーディングエージェントによるすべての仮想マシンの管理を許可は必要ありません。この設定はAIエージェント向けです。

終了コード

一般的なコマンドラインツールと同じく、vmpalは終了コードで結果をスクリプトやCIジョブに伝えます。

コード 意味
0 成功した
1 VMPalまたはVMが拒否した、または待機が打ち切られた
2 コマンドラインが正しくない

execとrunはコマンド自身の終了コードで終了するため、テストが失敗すればCIジョブも失敗します。次のコードも使います。

コード 意味
1 コマンドの終了コードが0〜255の範囲外だった(Windowsの0xC0000005など)。vmpalがそのコードを表示します
124 コマンドが--timeoutを超えて実行された
125 vmpalがコマンドを実行できなかった。runでは、クローンを作成または起動できなかった場合や、コピーに失敗した場合も含みます
128 + N シグナルNでvmpalが停止した

sshはssh自身の終了コードで終了し、接続できなかった場合は255になります。vmpalがsshを起動できなかった場合は125で終了します。

VM内のコマンド

vmpal execは、docker execがコンテナ内でコマンドを実行するのと同じように、VM内でコマンドを実行します。Macのシェルとは、いくつか動作が異なります。

  • シェルを介さない:execはプログラムを直接実行します。パイプ、&&、変数を使うには、vmpal exec "Ubuntu" -- /bin/sh -c 'make && make test'のようにシェルを自分で実行します。Windowsではpowershell.exe -Command '...'を使います。
  • 実行するユーザ:コマンドは、VMにサインインしているユーザとして実行されます。Linuxで誰もサインインしていない場合は、VMのアカウントで実行されます。Windowsでは標準の権限で実行されます。
  • 管理者:--adminを付けると、sudoのようにrootとして、Windowsでは管理者として実行と同じく昇格した状態で実行します。macOSのVMで--adminを使うには、まずVM内で管理者が承認する必要があります。VMPal Toolsのアップデート後にも、もう一度承認が必要です。手順はvmpal help execで確認できます。
  • テキスト出力:execは出力をUTF-8のテキストとして読み取ります。そのためバイナリの出力は変化してしまいます。バイナリファイルはcpでコピーしてください。
  • サインイン:VMがコマンドを実行できるようになるまで待つコマンドは、WindowsやmacOSのサインイン画面で自動的にサインインもします。create --wait、start --wait、waitなどです。サインインには、VMPalが保存しているパスワードを使います。パスワードを入力するのはVMなので、vmpalがパスワードを目にすることはありません。--no-sign-inでこの動作をオフにできます。
  • パスワード:VMのパスワードを出力するのは、info --show-passwordとtool --show-passwordだけです。ただしcreateは、キーチェーンにパスワードを保存できない場合に、新しいVMのパスワードを出力します。create --password-file <path>を使うと、自分だけが読めるファイルにパスワードを書き込みます。
  • VMPal Tools:VMPal Toolsは、各VM内で動作するVMPalのヘルパーです。10分を超えて実行されるコマンド、--env、出力の逐次表示には、macOSではVMPal Tools 0.34、Linuxでは0.35、Windowsでは0.37が必要です。VMPal Toolsは、VMの起動時にVMPalがアップデートします。
  • “ターミナルのみ”のVM:vmpal create <system> --terminal-onlyは、デスクトップなしでLinuxをインストールします。このVMは、VMPalのターミナルウインドウのタブとして表示されます。この形でインストールできるシステムはvmpal systemsで確認できます。vmpal ssh <VM>は、このMacのsshでVMにサインインします。execと違い、入力ができ、端末も使えます。

スクリプト

VMPalのHubはスクリプトを保存し、指示に応じて実行します。実行場所はスクリプトごとに選べます。

オプション 実行場所
--run-in <VM> 実行のたびに作成するVMの新しいクローン。クリーンなCIランナーと同じように使えます
--run-in-place <VM> VM自体
--host このMac(このMacでのスクリプトの設定で許可されている範囲で)
vmpal script create "Test App" --file test-app.sh --run-in "Ubuntu"   # a fresh clone of Ubuntu each run
vmpal script run "Test App" --wait                                    # run it now, and exit with its status
vmpal script log "Test App"                                           # the run's output

スクリプトのしくみはスクリプトで説明しています。そのほかのコマンドはコマンド一覧をご覧ください。