본문으로 이동

문서 명령줄 명령줄

명령 목록

vmpal은 docker나 gh처럼 쓰는 VMPal의 명령줄 도구입니다. 이 페이지에서는 모든 명령을 간단히 정리하고, 이어서 알아 둘 규칙을 설명합니다. 명령의 옵션은 vmpal help <command>로, 가이드는 vmpal help <topic>으로 확인하세요.

표에서 <VM>은 VM의 이름, ID나 ID의 앞 4자 이상, 또는 .vmpal 폴더 경로입니다. vmpal list로 확인할 수 있습니다.

AI 에이전트에게 요청하기

이 모든 일을 AI 에이전트가 대신할 수 있습니다. VMPal은 모든 명령의 도움말과 가이드를 에이전트에게 제공하므로, 에이전트가 명령을 작성하거나 직접 실행할 수 있습니다. 에이전트를 VMPal에 연결한 다음, 예를 들어 이렇게 요청하세요.

  • "내 Windows VM에 폴더를 복사하려면 어떤 vmpal 명령을 쓰나요?"
  • "내 Ubuntu VM을 복제해서 클론에서 테스트를 실행한 다음, 클론을 삭제해 주세요."

VM

명령 기능
vmpal list VM 목록과 각 VM의 현재 상태를 보여 줍니다
vmpal info <VM> VM 하나의 전체 정보를 보여 줍니다
vmpal systems 설치할 수 있는 시스템을 ID와 함께 나열합니다. 터미널 전용으로 설치할 수 있는 시스템도 알려 줍니다
vmpal create <system> --wait VM을 만들고, 설치가 끝나 명령을 실행할 수 있을 때까지 기다립니다
vmpal create --file <path> 시스템 ID 대신 IPSW나 ISO 파일로 설치합니다
vmpal create <system> --terminal-only 데스크톱 없이 Linux를 설치합니다
vmpal create <system> --password-file <path> 새 VM의 비밀번호를 본인만 읽을 수 있는 파일에 씁니다
vmpal clone <VM> 종료된 VM을 복제합니다. 클론은 즉시 준비됩니다
vmpal clone <VM> --shut-down 먼저 VM을 종료한 다음 복제합니다
vmpal clone <VM> --start --wait 클론도 시작하고, 명령을 실행할 수 있을 때까지 기다립니다
vmpal set <VM> --cpus 4 --memory 8 하드웨어, 공유 폴더, 포트, 네트워크, 로그인 등 VM의 설정을 바꿉니다. 전체 설정은 vmpal help set에서 확인하세요
vmpal set <VM> --display 1440x900@2x 어떤 화면에서든, 백그라운드에서도 VM의 디스플레이를 지정한 포인트 크기와 배율(1x 또는 2x)로 유지합니다. 창에는 창 크기에 맞춰 조정되어 표시되고, 클론도 이 설정을 유지합니다. UI 테스트와 스크린샷에 사용하세요. window를 지정하면 다시 창을 따라갑니다
vmpal set <VM> --render-scale 75 Windows VM의 디스플레이를 창의 가로세로 각각 75% 또는 50% 크기로 렌더링하고 MetalFX로 확대합니다. 값이 낮을수록 GPU에 막혀 느린 게임이 빨라지지만 화면은 덜 선명해집니다. 100을 지정하면 원래 크기로 돌아갑니다
vmpal set <VM> --user <name> VMPal이 만들지 않았거나 VM 안에서 이름을 바꾼 계정의 이름을 VMPal에 알려 줍니다. VM 안에서는 아무것도 바꾸지 않습니다
vmpal delete <VM> VM을 휴지통으로 옮깁니다
vmpal delete <VM> --force 실행 중인 VM을 먼저 끈 다음 휴지통으로 옮깁니다
vmpal delete <VM> --permanently 휴지통을 거치지 않고 완전히 삭제합니다
vmpal import <path> 다른 Mac의 .vmpalvm 파일이나 Parallels VM을 가져옵니다. .vmpal 폴더는 현재 위치 그대로 추가됩니다
vmpal move <VM> <location> 종료된 VM을 VMPal의 다른 보관 위치로 옮깁니다. --wait를 쓰면 이동이 끝날 때까지 기다립니다
vmpal compress <VM> 다른 Mac으로 옮길 수 있도록 VM을 .vmpalvm 파일로 압축합니다. --output으로 지정하지 않으면 데스크톱에 저장됩니다
vmpal cancel <VM> VM의 다운로드나 이동을 중지합니다
vmpal cancel 진행 중인 가져오기나 압축을 중지합니다

create의 다른 옵션은 vmpal help create에서 확인하세요. --name, --cpus, --memory, --disk, --location, --user, Linux용 --install-updates, Windows용 --sign-in-automatically, --start-at-login, --no-agent-control이 있습니다.

CPU, 메모리, GPU 등 일부 설정은 VM을 종료했다가 다시 시작해야 적용됩니다. vmpal restart <VM> --apply-settings가 이 과정을 대신해 줍니다.

전원

명령 기능
vmpal start <VM> --wait VM을 시작하고, 명령을 실행할 수 있을 때까지 기다립니다
vmpal start <VM> --background 창 없이 시작합니다. 창은 vmpal show로 엽니다
vmpal start <VM> --recovery macOS VM을 macOS 복구로 시작합니다
vmpal stop <VM> VM을 종료합니다
vmpal stop <VM> --force 전원 플러그를 뽑듯 즉시 끕니다
vmpal pause <VM> 실행 중인 VM을 일시 정지합니다
vmpal resume <VM> 일시 정지된 VM을 재개합니다
vmpal suspend <VM> 세션을 디스크에 저장하고 닫습니다. vmpal start로 중단한 지점부터 이어서 실행합니다
vmpal restart <VM> VM 안의 시스템을 재시작합니다
vmpal restart <VM> --apply-settings 재시작해야 적용되는 설정을 위해 VM을 종료했다가 다시 시작합니다
vmpal restart <VM> --reset 리셋 버튼을 누른 것처럼 즉시 재시작합니다
vmpal show <VM> 실행 중인 VM의 창을 앞으로 가져옵니다
vmpal show <VM> --apps-on-mac View › Run Windows Apps on Mac처럼 Windows VM의 앱을 각각 별도의 Mac 창으로 보여 줍니다. GPU 가속을 쓰는 Linux VM도 View › Run Linux Apps on Mac처럼 같은 방식으로 동작합니다. 다음에도 VM이 이 방식으로 열립니다
vmpal show <VM> --window 앱 대신 VM의 창을 다시 표시합니다
vmpal wait <VM> 명령을 실행할 수 있을 때까지 기다립니다. 기본적으로 10분이 지나면 중단합니다
vmpal wait <VM> --until stopped 대신 stopped 상태가 될 때까지 기다립니다. --until에는 running과 installed도 쓸 수 있습니다

대기 제한 시간은 start, stop, clone --start가 5분, start --wait, clone --start --wait, restart --wait, wait가 10분입니다. create --wait, move --wait, compress --wait는 2시간이 지나면 중단합니다. --timeout으로 최대 24시간까지 다른 제한 시간을 지정할 수 있습니다.

VM 내부

명령 기능
vmpal exec <VM> -- <command> docker exec처럼 VM 안에서 명령을 실행합니다. 출력은 나오는 대로 표시됩니다
vmpal exec <VM> --arch x64 -- <command> arm64와 x64용으로 함께 빌드된 프로그램의 x64 버전을 실행합니다. --arch arm64는 다른 쪽을 실행합니다
vmpal cp <from> <to> docker cp처럼 파일을 VM 안팎으로 복사합니다. VM 쪽은 <VM>:<path>로 씁니다
vmpal run <VM> -- <command> 새 CI 러너처럼 종료된 VM의 새 클론에서 명령을 실행합니다. --copy-in과 --copy-out으로 파일을 복사합니다. 실행이 끝나면 VMPal이 클론을 삭제합니다. 자세한 내용은 CI/CD를 참고하세요
vmpal ssh <VM> 이 Mac의 ssh로 터미널 전용 Linux VM에 로그인합니다. 입력과 터미널을 사용할 수 있습니다
vmpal ssh <VM> -- <command> ssh로 그 VM에서 명령을 실행합니다
vmpal ssh <VM> --tty -- <command> ssh -t처럼 명령에 터미널도 제공합니다. top 같은 프로그램에 사용하세요
vmpal sign-in <VM> VMPal에 저장된 비밀번호로 로그인 화면에서 로그인합니다
vmpal ui <VM> ... 화면의 창, 버튼, 텍스트와 Windows의 UAC 같은 OS 프롬프트를 읽고(vmpal ui <VM> tree), 클릭하고, 입력하고, 스크린샷을 찍습니다. 사용법은 vmpal ui help에서 확인하세요
vmpal status <VM> 명령을 실행할 수 있는지, 화면 상태, 입력을 누가 쓰고 있는지 보여 줍니다
vmpal send-files <VM> <path>... 파일을 VM 사용자의 데스크톱에 끌어다 놓듯 넣습니다
vmpal reinstall-tools <VM> VM에 VMPal Tools를 다시 설치합니다

스냅샷

스냅샷은 VM의 현재 상태를 저장해 두었다가 나중에 그 상태로 돌아갈 수 있게 합니다.

명령 기능
vmpal snapshot <VM> [name] 스냅샷을 만듭니다
vmpal snapshots <VM> VM의 스냅샷을 나열합니다
vmpal revert <VM> [name] 스냅샷으로 되돌립니다. 이름을 지정하지 않으면 가장 최근 스냅샷으로 되돌립니다
vmpal revert <VM> --snapshot-first 현재 상태를 새 스냅샷으로 저장한 다음 되돌립니다
vmpal rename-snapshot <VM> <snapshot> <new name> 스냅샷의 이름을 바꿉니다
vmpal delete-snapshot <VM> <snapshot> 스냅샷을 완전히 삭제합니다

Hub

이 명령은 VMPal Hub의 스크립트를 관리합니다. 스크립트는 VMPal이 보관하고 대신 실행하는 셸 또는 PowerShell 스크립트입니다. AI 에이전트는 VMPal의 MCP 도구로 같은 작업을 합니다.

<script>는 스크립트의 이름(대소문자 구분 없음)이나 ID입니다.

명령 기능
vmpal script create <name> --file <path> VMPal Hub에 스크립트를 추가합니다. --file -는 표준 입력에서 스크립트를 읽습니다. 다른 스크립트와 이름이 같으면 "Test App 2"처럼 번호가 붙습니다
vmpal script edit <script> 이름(--name), 내용(--file), 설정, 실행 위치를 바꿉니다. --no-targets를 쓰면 어디에서도 실행되지 않습니다
vmpal script show <script> 설정, 실행 위치, 최근 실행 5개와 로그 경로, 스크립트 내용을 보여 줍니다
vmpal script list 모든 스크립트를 언어, 색상, 실행 위치와 함께 나열합니다
vmpal script run <script> --wait 지금 실행하고, 실행이 끝날 때까지 기다립니다
vmpal script stop <script> 대기 중이거나 진행 중인 실행을 중지합니다. --run <ID>는 실행 하나만 중지합니다
vmpal script runs <script> 실행 목록을 ID, 상태, 실패 이유와 함께 최신순으로 나열합니다. 가장 최근에 끝난 50개와 대기 중이거나 진행 중인 실행이 표시됩니다. --limit <n>으로 최대 100개까지 개수를 지정할 수 있습니다
vmpal script log <script> 가장 최근 실행의 로그를 출력합니다. --run <ID>는 다른 실행의 로그를 출력하고, --tail <bytes>는 로그의 끝부분만 출력합니다
vmpal script duplicate <script> 스크립트를 복사해 Hub 목록에서 바로 아래에 놓습니다
vmpal script move <script> --before <script> Hub 목록에서 위아래로 옮깁니다. --to-end는 목록 끝으로 옮깁니다
vmpal script delete <script> 스크립트를 실행 기록, 로그와 함께 삭제합니다. 진행 중인 실행은 중지됩니다

다음 옵션은 스크립트를 실행할 위치를 정합니다. script create, script edit, script run에서 쓸 수 있습니다.

옵션 스크립트 실행 위치
--run-in <VM> VM의 새 클론. 새 CI 러너처럼 쓰고 버리는 복사본입니다
--run-in-place <VM> VM 자체
--host 이 Mac에서 내 계정으로
  • script run은 이번 실행에만 이 옵션을 사용합니다.
  • script edit은 기존 실행 위치를 이 옵션으로 바꿉니다.
  • 실행은 VM을 최대 30분까지 기다립니다. 예를 들어 복제하기 전에 VM이 종료되기를 기다립니다.

다음 옵션은 script create와 script edit에서 스크립트의 설정을 바꿉니다.

옵션 설정 내용
--language powershell PowerShell 스크립트로 만듭니다. .ps1 파일은 처음부터 PowerShell 스크립트입니다
--timeout <duration> 실행 하나가 걸릴 수 있는 최대 시간입니다. 기본값은 1시간이며 최대 24시간입니다
--color <color> Hub에서 스크립트의 행에 색을 입힙니다: red, orange, yellow, green, mint, teal, cyan, blue, indigo, purple, pink, brown, gray. script edit에서 --color none을 쓰면 색을 없앱니다

script run --wait는 CI 작업처럼 종료하므로 종료 코드로 실행의 성공 여부를 알 수 있습니다. script run에서 --timeout은 실행 하나가 걸릴 수 있는 시간이 아니라 vmpal이 실행을 기다리는 시간입니다. 기본적으로 스크립트의 제한 시간에 35분을 더한 만큼 기다립니다.

휴대폰과 태블릿

<phone>은 VMPal의 Remote 섹션에 있는 iPhone, iPad, iOS 시뮬레이터, Android 기기의 이름입니다. 자세한 내용은 휴대폰과 태블릿을 참고하세요. vmpal start <phone>으로 기기를 연결하면 VM처럼 vmpal ui <phone>으로 화면을 사용할 수 있습니다.

명령 기능
vmpal device <phone> install <path> 앱을 설치합니다. 해당 iPhone용으로 서명한 .app이나 .ipa, 시뮬레이터용 .app, Android용 .apk를 설치할 수 있습니다
vmpal device <phone> launch <bundle ID> 앱을 시작하고(실행 중이면 먼저 종료) 앱이 출력하는 내용을 보관합니다. 앱에 넘길 인수는 -- 뒤에 씁니다. --no-console을 쓰면 아무것도 보관하지 않습니다
vmpal device <phone> logs <bundle ID> launch로 시작한 뒤 앱이 출력한 내용입니다. Android에서는 앱의 logcat입니다. --lines <n>으로 줄 수를 조절합니다
vmpal device <phone> crashes [<bundle ID>] 충돌 보고서를 최신순으로 보여 줍니다. vmpal device <phone> crash <report>로 보고서 하나를 읽습니다
vmpal device <phone> apps 시스템 앱을 제외하고 설치된 앱을 보여 줍니다
vmpal device <phone> terminate <bundle ID> 앱을 종료합니다. uninstall은 앱을 삭제합니다
vmpal device <phone> rotate landscape-left 기기를 회전합니다: portrait, landscape-left, landscape-right, upside-down
vmpal device <phone> button home 버튼을 누릅니다: home, volume-up, volume-down, Android에서는 back, recents, power도 쓸 수 있습니다
vmpal device <phone> open-url <url> 웹 페이지나 앱 자체의 링크를 엽니다
vmpal device <phone> pinch --scale 2 두 손가락으로 핀치합니다. --x와 --y(0~1)로 지정하지 않으면 가운데에서 합니다. 1보다 크면 확대합니다
vmpal device <phone> release iPhone이나 iPad에서 VMPal의 테스트 세션을 끝내, Xcode로 직접 작성한 UI 테스트를 실행할 수 있게 합니다

기타

명령 기능
vmpal library VMPal의 보관 위치, Base OS 파일, 진행 중인 다운로드, 가져오기, 압축을 보여 줍니다
vmpal add-location <path> 다른 디스크의 폴더처럼 VMPal이 VM을 보관할 폴더를 추가합니다
vmpal remove-location <path> VMPal의 목록에서 폴더를 뺍니다. 폴더 안의 VM은 그대로 남습니다
vmpal delete-base-os <id> Base OS 파일을 휴지통으로 옮깁니다
vmpal diagnostics 버그 보고에 쓸 수 있도록 VMPal의 로그, 충돌 보고서, VM 설정을 zip 파일로 묶고 보내는 방법을 알려 줍니다. 비밀번호는 포함되지 않습니다
vmpal diagnostics <VM> VM 하나에 대해 같은 작업을 합니다. 해당 VM의 전체 로그와 그 VM의 파일만 포함합니다
vmpal diagnostics --problem <text> 버그 보고에 무엇이 잘못되었는지 적습니다
vmpal tool <name> [<json>] VMPal의 MCP 도구 하나를 이름으로 호출하고 인수를 JSON으로 전달합니다. --file <path>는 파일에서, -는 표준 입력에서 인수를 읽습니다. --show-password를 쓰면 결과에 VM의 비밀번호를 그대로 남깁니다
vmpal help 모든 명령을 나열합니다
vmpal help <command> 명령 하나의 옵션과 가이드를 보여 줍니다
vmpal help <topic> 가이드를 읽습니다: setup, ci, exec, cp, sign-in, ui

알아 둘 규칙

VM 안의 명령

  • 에이전트 제어. exec, cp, run, ssh, ui, sign-in은 VM이 에이전트 제어를 허용할 때만 동작하며, start --wait처럼 VM이 명령을 실행할 수 있을 때까지 기다리는 대기도 마찬가지입니다. 누군가 끄지 않았다면 켜져 있습니다. 다시 켜려면 vmpal set <VM> --agent-control on을 실행하세요.
  • 셸이 없습니다. exec은 셸 없이 프로그램 자체를 실행합니다. 파이프와 &&를 쓰려면 셸을 직접 실행하세요: vmpal exec "Ubuntu" -- /bin/sh -c 'make && make test'.
  • 텍스트 출력. exec은 출력을 텍스트로 읽기 때문에 바이너리 출력이 바뀝니다. 바이너리 파일은 cp로 복사하세요.
  • 관리자 권한. --admin은 명령을 관리자 권한으로 실행합니다. macOS VM에서는 먼저 VM 안에서 관리자가 이를 승인해야 합니다. 방법은 vmpal help exec에서 확인하세요.
  • 제한 시간. exec은 2시간, cp는 1시간이 지나면 명령을 중지합니다. --timeout으로 최대 24시간까지 다른 제한 시간을 지정할 수 있습니다. 이전 버전의 VMPal Tools에서는 10분입니다.
  • 입력이 없습니다. exec으로 실행한 명령은 입력을 받지 않습니다. 터미널 전용 VM에서는 vmpal ssh로 입력할 수 있습니다.
  • 폴더 복사. cp는 cp -R처럼 동작합니다. 예를 들어 vmpal cp . "Ubuntu:src"는 현재 폴더의 내용을 src에 복사합니다.
  • 로그인. Windows는 누군가 로그인한 뒤에만 명령을 실행합니다. 그래서 create --wait, start --wait, wait, clone --start --wait, restart --wait, run은 VMPal에 저장된 비밀번호로 대신 로그인합니다. Windows나 macOS 로그인 화면에서 로그인하며, --no-sign-in으로 이 기능을 끌 수 있습니다. Windows가 시작할 때마다 스스로 로그인하게 하려면 vmpal set <VM> --sign-in-automatically on을 실행하세요.

종료 코드

다른 명령줄 도구처럼 종료 코드는 스크립트나 CI 작업에 명령의 성공 여부를 알려 줍니다.

명령 종료 코드
exec, run 실행한 명령의 종료 코드. 시간이 초과되면 124, vmpal이 명령을 실행하지 못하면 125, 시그널 N을 받으면 128 + N이며, Windows의 0xC0000005처럼 0~255를 벗어난 코드는 1로 바꾸고 원래 코드를 vmpal이 출력합니다
ssh ssh 자체의 종료 코드. 연결하지 못하면 255, vmpal이 ssh를 시작하지 못하면 125
script run --wait 모든 실행이 성공하면 0. 그렇지 않으면 실행이 하나일 때는 그 실행의 종료 코드, 여러 개일 때는 1
그 밖의 모든 명령 성공하면 0, 실패하면 1, 명령줄이 잘못되면 2

스크립트

  • 이 Mac의 스크립트는 내 계정으로 실행됩니다. 그래서 vmpal이 이 Mac에서 스크립트를 실행하게 될 때마다 VMPal은 Scripts on this Mac 설정을 확인합니다. --host, 이 Mac에서 실행되는 스크립트의 script run, 그런 스크립트의 내용 변경이 해당합니다. 이 설정에는 세 가지 선택지가 있습니다.
    • Allow (agents ask you)(허용, 에이전트가 사용자에게 확인): 기본값이며, 묻지 않고 허용합니다.
    • Ask in VMPal(VMPal에서 확인): 스크립트 버전마다 한 번씩 묻습니다.
    • Off(끔): 거부합니다.