본문으로 이동

문서 명령줄

명령줄

vmpal은 docker나 gh처럼 쓰는 VMPal의 명령줄 도구입니다. 터미널, 직접 작성한 스크립트, CI에서 사용할 수 있습니다. VM을 만들고 시작하며, VM 안에서 명령을 실행하고, 파일을 VM 안팎으로 복사합니다. VM 화면을 창, 버튼, 텍스트 목록으로 읽고, 스크린샷을 찍고, VM 안에서 클릭하고 입력할 수도 있습니다. VMPal Hub의 스크립트도 만들고 실행합니다.

AI 에이전트에게 요청하기

vmpal을 가장 빠르게 사용하는 방법은 코딩 에이전트에게 요청하는 것입니다. VMPal은 사용 중인 VMPal 버전에 맞는 vmpal의 전체 도움말과 가이드를 에이전트에게 제공합니다. 에이전트가 명령이나 스크립트를 작성하고 설명해 줍니다. 에이전트가 이 Mac의 터미널을 쓸 수 있다면 직접 실행까지 합니다. vmpal을 설치하려면 관리자 비밀번호가 필요하므로, 아직 설치하지 않았다면 에이전트가 실행할 명령을 알려 줍니다.

  1. VMPal에서 Settings › AI Agents를 열고 Let coding agents on this Mac manage all VMs(이 Mac의 코딩 에이전트가 모든 VM을 관리하도록 허용) 설정을 켜세요. 그러면 에이전트가 VM과 스크립트도 관리할 수 있습니다. 이 설정을 켜지 않아도 에이전트는 vmpal 사용법을 설명할 수 있습니다.
  2. Add to Claude Code, Add to Codex, Add to Grok Build 또는 Add to Antigravity를 클릭하세요. Cursor, VS Code, Kiro 등 다른 에이전트는 Others… 버튼을 클릭하세요. 사용하는 에이전트가 목록에 없다면 Manual Setup… 버튼을 클릭하면 추가할 내용을 확인할 수 있습니다. 그런 다음 에이전트를 다시 시작하세요.
  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에도 도움말이 내장되어 있습니다. 가이드는 자주 하는 작업을 차례대로 안내합니다.

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/CD에서는 CI 작업마다 VM의 새 클론에서 실행하는 방법을 설명합니다.

기본 사항

  • VM 지정하기. VM의 이름("Windows 11"), ID 또는 .vmpal 폴더 경로를 사용하세요. ID는 앞 4자 이상만 써도 됩니다. 이름과 ID는 vmpal list로 확인할 수 있습니다. cp의 <VM>:<path>에는 이름이나 ID를 쓰세요.
  • 출력은 일반 텍스트입니다. --json을 쓰면 스크립트가 읽을 수 있도록 결과를 JSON 한 줄로 출력합니다. exec에서는 출력을 나오는 대로 보여 주는 대신 마지막에 전체 결과를 출력합니다. -q는 ID만 출력하며 list, create, clone, script list, script run, script runs에서 쓸 수 있습니다.
  • 묻지 않습니다. vmpal은 명령줄에서 사용자에게 아무것도 묻지 않으므로 스크립트와 CI에서 안심하고 쓸 수 있습니다. 할 수 없는 작업이면 실패하고 이유를 알려 줍니다. 다만 VMPal이 대신할 수 없는 로그인처럼 사람이 직접 처리해야 하는 대기도 일부 있습니다. 스크립트를 이 Mac에서 실행하게 하면 VMPal은 Scripts on this Mac 설정에서 선택한 대로 따릅니다.
  • 제한 시간. 대기는 --timeout에 지정한 시간이 지나면 중단됩니다. 90(초), 90s, 10m, 2h, 1h30m처럼 쓰며 최대 24h까지 지정할 수 있습니다. 단, vmpal ui의 --timeout은 밀리초 단위이거나 10s처럼 쓰며 최대 45초입니다.
  • 에이전트 제어. VM마다 vmpal과 AI 에이전트가 VM 안에서 작업하도록 허용하는 설정이 있습니다. Settings › AI Agents › Allow agent control of this VM입니다. exec, cp, run, ssh, ui, sign-in에는 이 설정이 필요하며, start --wait처럼 VM이 명령을 실행할 수 있을 때까지 기다리는 대기에도 필요합니다. run에서는 복제할 원본 VM에 이 설정이 켜져 있어야 합니다. 누군가 끄지 않았다면 켜져 있습니다. vmpal set <VM> --agent-control on으로 다시 켤 수 있습니다.
  • Mac 전체 설정. vmpal에는 Let coding agents on this Mac manage all VMs 설정이 필요하지 않습니다. 이 설정은 AI 에이전트용입니다.

종료 코드

다른 명령줄 도구처럼 vmpal도 종료 코드로 스크립트나 CI 작업에 결과를 알려 줍니다.

코드 의미
0 성공
1 VMPal이나 VM이 요청을 거부했거나 대기 시간이 초과됨
2 명령줄이 잘못됨

exec과 run은 실행한 명령의 종료 코드로 종료하므로, 테스트가 실패하면 CI 작업도 실패합니다. 다음 코드도 사용합니다.

코드 의미
1 명령의 종료 코드가 Windows의 0xC0000005처럼 0~255 범위를 벗어남. 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에서는 관리자 권한으로 실행(Run as administrator)처럼 높은 권한으로 실행합니다. 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은 VM이 시작될 때 VMPal Tools를 업데이트합니다.
  • 터미널 전용(Terminal only) 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. Scripts on this 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

스크립트의 동작 방식은 스크립트에서 설명합니다. 나머지 명령은 명령 목록에서 확인하세요.