# 명령줄

Device MCP의 명령줄 도구인 device-mcp-cli로 터미널, 셸 스크립트, CI에서 iPhone, iPad, Android 기기나 시뮬레이터를 조작합니다. 모든 명령은 JSON으로 응답할 수 있습니다.

`device-mcp-cli`는 Device MCP의 명령줄 도구입니다. 앱에서 하거나 AI 에이전트에게 맡기는 일을 터미널, 셸 스크립트, Makefile, CI에서 실행할 수 있습니다. 기기 목록을 보고, 스크린샷을 찍고, 화면을 읽고, 탭하고 입력하고, 앱을 실행하거나 설치하고, 위치를 설정하고, 라이선스를 관리할 수 있습니다.

모든 명령은 JSON으로 응답할 수 있으므로 스크립트에서 텍스트를 파싱하는 대신 `jq`로 결과를 읽을 수 있습니다.

## 1. 설치
* **Homebrew**: `brew install --cask device-mcp`로 설치하면 `device-mcp-cli`가 `PATH`에 추가됩니다.
* **웹사이트에서 다운로드한 경우**: 터미널에서 다음 명령을 한 번 실행해 `PATH`에 추가하세요.

```bash
sudo ln -sf "/Applications/Device MCP.app/Contents/MacOS/device-mcp-cli" /usr/local/bin/device-mcp-cli
```

Device MCP가 스스로 업데이트해도 이 링크는 계속 작동합니다. 다음 명령으로 확인하세요.

```bash
device-mcp-cli --version
device-mcp-cli --help                  # every command
device-mcp-cli help apps launch        # one command, with its options
```

## 2. 작동 방식
* **명령은 Device MCP가 실행합니다.** 기기 명령은 Mac의 Device MCP 앱으로 전달됩니다. 앱이 실행 중이 아니면 명령이 앱을 열지 먼저 묻습니다. `--launch`는 묻지 않고 열고(스크립트에서 사용하세요), `--no-launch`는 절대 열지 않습니다. `status`, `mcp`, `tools`, `logs`는 앱을 열지 않습니다.
* **기기 지정**: `--device`(또는 `-d`)에 기기 이름이나 UDID를 지정합니다. 지정하지 않으면 `devices select`로 고른 기기를, 고른 기기가 없으면 Device MCP에서 선택된 기기를 사용합니다.
* **JSON**: 어떤 명령에든 `--json`을 붙이세요. 오류도 JSON으로 출력됩니다.
* **통제권은 사용자에게**: 앱 설치와 제거, 링크 열기, 클립보드 읽기나 변경, Build & Run은 AI 에이전트가 할 때와 마찬가지로 Device MCP에서 먼저 사용자에게 묻습니다. [승인](ai-agents/approvals.md)을 참고하세요. 기기 페어링 해제와 라이선스 비활성화는 항상 묻습니다.
* **Free와 Pro**: 모든 명령이 Device MCP Free에서 작동하지만, Build & Run, 앱 설치, 3D 뷰 인스펙터에는 [Device MCP Pro](license.md)가 필요합니다. Free에서는 한 번에 기기 한 대만 미러링합니다.

## 3. 명령
`<device>`는 기기 이름이나 UDID입니다. 모든 명령에 `--json`을 붙일 수 있고, 기기 명령에는 `--device`도 붙일 수 있습니다.

### 기기
| 명령 | 설명 |
| --- | --- |
| `devices` | 기기 목록을 보여 줍니다. 이름, 종류, OS, 연결, 상태, UDID가 표시됩니다. `--all`을 붙이면 모든 시뮬레이터와 에뮬레이터, 그리고 새 시뮬레이터로 만들 수 있는 모델까지 표시됩니다. |
| `devices info` | 기기의 모델, OS, 화면 크기, 미러링 상태와 잠금 상태를 보여 줍니다. `--settings`를 붙이면 라이트/다크 모드와 손쉬운 사용 설정도 표시됩니다. |
| `devices select <device>` | 이후 명령이 사용할 기기를 고르고, Device MCP에 그 기기를 표시합니다. |
| `devices start-mirroring`, `devices stop-mirroring` | 기기 미러링을 시작하거나 중지합니다. |
| `devices reconnect` | 미러링 화면이 멈춘 기기를 다시 연결합니다. |
| `devices unpair <device>` | iPhone이나 iPad와 Mac의 페어링을 해제합니다. |
| `devices remove <device>` | Device MCP의 목록에서 기기를 제거합니다. |
| `simulators` | iOS 및 watchOS 시뮬레이터와 Android 에뮬레이터 목록을 보여 줍니다. |
| `simulators start <name>` | 시뮬레이터나 에뮬레이터를 시작하고 실행될 때까지 기다립니다. `--model "iPhone 17 Pro"`를 붙이면 새 시뮬레이터를 만듭니다. |
| `simulators stop <name>` | 시뮬레이터나 에뮬레이터를 종료합니다. |

### 화면
| 명령 | 설명 |
| --- | --- |
| `screenshot` | 전체 해상도로 스크린샷을 저장합니다. `-o`로 파일(`.png` 또는 `.jpg`)이나 폴더를 지정합니다. 기본값은 `~/Pictures/Device MCP`입니다. |
| `record start`, `record stop` | 화면을 동영상으로 기록해 `~/Movies/Device MCP`에 저장합니다. |
| `elements` | 화면에 있는 요소의 목록을 보여 줍니다. 각 요소의 유형, 레이블, 값, 프레임, 그리고 `tap --ref`에 쓰는 ref(`e12`)가 표시됩니다. |

### 터치와 키
| 명령 | 설명 |
| --- | --- |
| `tap` | 요소의 텍스트(`--text "Sign In"`)나 ref(`--ref e12`)로 요소를 탭하거나, 특정 지점(`-x 120 -y 640`)을 탭합니다. `--double`은 두 번 탭하고, `--long`은 길게 누릅니다. |
| `type <text>` | 포커스된 필드에 입력합니다. `--field "Email"`은 필드를 탭하고, 내용을 비운 다음 입력해 필드를 채웁니다. `--submit`은 Return 키를 누릅니다. `-`를 쓰면 파이프나 파일에서 텍스트를 읽습니다. |
| `scroll up\|down\|left\|right` | 스크롤합니다. `--distance 300`은 콘텐츠를 정확히 그만큼의 포인트만 움직입니다. |
| `swipe --from x,y --to x,y` | 한 지점에서 다른 지점으로 스와이프합니다. |
| `press <button>` | `home`, `lock`, `volume_up`, `volume_down`, `mute`, `siri`, `back` 버튼을 누릅니다. |
| `key <key>` | 키보드 키를 누릅니다. `--modifier command` 등으로 보조 키를 함께 누를 수 있습니다. |
| `gesture <gesture>` | `go_home`, `app_switcher`, `control_center`, `notification_center`, `spotlight` 제스처를 실행합니다. |
| `rotate <orientation>` | 기기를 `portrait`, `landscape_left`, `landscape_right`, `portrait_upside_down` 방향으로 회전합니다. |
| `hide-keyboard` | 화면 키보드를 숨깁니다. |
| `wait-for <text>` | 텍스트가 화면에 나타날 때까지(`--gone`: 사라질 때까지) 최대 `--timeout`초 동안 기다립니다. |
| `alert accept\|dismiss` | 권한 요청 같은 시스템 팝업에 응답합니다. `--button`은 버튼의 텍스트로 버튼을 탭합니다. |

### 앱
| 명령 | 설명 |
| --- | --- |
| `apps` | 설치된 앱 목록을 보여 줍니다. 이름, 번들 ID, 버전이 표시됩니다. `--user`를 붙이면 사용자가 설치한 앱만 표시합니다. |
| `apps foreground` | 맨 앞에 있는 앱과 그 번들 ID를 보여 줍니다. |
| `apps launch <app>` | 번들 ID나 이름으로 앱을 실행합니다. 테스트 실행에는 `--language`, `--locale`, `--arg`, `--env`를 사용하세요. |
| `apps terminate <bundle-id>` | 실행 중인 앱을 종료합니다. |
| `apps install <path>` | `.ipa`, `.app`, `.apk`를 설치합니다. Device MCP Pro가 필요합니다. |
| `apps uninstall <bundle-id>` | 앱과 앱 데이터를 제거합니다. |
| `apps container <bundle-id>` | Xcode처럼 개발용 앱의 데이터를 `.xcappdata` 패키지로 다운로드합니다. |
| `open-url <url>` | 웹 페이지나 딥 링크(`myapp://…`)를 엽니다. |
| `build-and-run <project>` | Xcode 프로젝트를 빌드하고 설치한 다음 실행합니다. Device MCP Pro가 필요합니다. [Build & Run](ai-agents/build-and-run.md)을 참고하세요. |
| `crashes` | 크래시 리포트를 최신순으로 보여 줍니다. `--app`으로 특정 앱의 리포트만 볼 수 있습니다. |
| `crashes show <path>` | 크래시 리포트를 보여 줍니다. 무엇이 어디에서 크래시됐는지 알 수 있습니다. `--app`은 앱의 가장 최근 크래시를 보여 줍니다. |

### 기기 설정
| 명령 | 설명 |
| --- | --- |
| `location set <latitude> <longitude>` | 위치를 시뮬레이션합니다. `location clear`는 실제 위치로 되돌립니다. |
| `appearance light\|dark` | 기기를 라이트 모드나 다크 모드로 바꿉니다. |
| `clipboard get`, `clipboard set <text>` | 기기 클립보드의 텍스트를 읽거나 바꿉니다. |

### Device MCP
| 명령 | 설명 |
| --- | --- |
| `status` | Device MCP의 실행 여부, 버전, MCP 서버, 라이선스를 보여 줍니다. |
| `app open`, `app quit` | Device MCP를 백그라운드에서 열거나 종료합니다. |
| `mcp` | MCP 서버가 켜져 있는지와 서버 주소를 보여 줍니다. `mcp on`과 `mcp off`로 서버를 켜고 끕니다. |
| `mcp setup claude\|codex` | Claude Code나 Codex에 Device MCP를 추가합니다. `--print`는 추가하는 대신 명령을 보여 줍니다. |
| `mcp config` | Cursor 같은 다른 MCP 클라이언트에 넣을 JSON을 보여 줍니다. |
| `license` | 라이선스를 보여 줍니다. Free인지, 아니면 요금제, 키, 시트, 라이선스가 적용되는 버전이 표시됩니다. |
| `license activate <key>` | 이 Mac에서 라이선스 키를 활성화합니다. |
| `license revoke` | 이 Mac에서 라이선스를 비활성화하고 시트를 해제합니다. |
| `logs` | 버그 리포트에 첨부할 Device MCP 로그를 보여 줍니다. `-f`를 붙이면 새 줄을 계속 출력합니다. |

### 그 밖의 기능
| 명령 | 설명 |
| --- | --- |
| `call <tool> [name=value…]` | AI 에이전트처럼 Device MCP의 MCP 도구를 무엇이든 실행합니다. |
| `tools` | 이 도구들과 각 도구의 인수 목록을 보여 줍니다. |

## 4. 예시
### 로그인하고 결과 확인하기
셸 스크립트나 CI 단계에서 실행하는 앱 스모크 테스트입니다.

```bash
set -e
device-mcp-cli apps launch com.example.myapp --launch
device-mcp-cli wait-for "Sign In"
device-mcp-cli type "test@example.com" --field "Email"
device-mcp-cli type - --field "Password" < password.txt
device-mcp-cli tap --text "Sign In"
device-mcp-cli wait-for "Welcome" --timeout 20 || {
  device-mcp-cli screenshot -o failure.png
  exit 1
}
```

### 모든 기기의 스크린샷 찍기
```bash
device-mcp-cli devices --json |
  jq -r '.devices[] | select(.state == "ready" or .state == "running") | .udid' |
  while read -r udid; do device-mcp-cli screenshot --device "$udid" -o ~/Desktop/; done
```

### 화면의 요소 탭하기
`elements`는 화면의 요소를 ref와 함께 나열합니다. `jq`로 요소를 찾은 다음 탭하세요.

```bash
REF=$(device-mcp-cli elements --json | jq -r '.elements[] | select(.label == "General") | .ref')
device-mcp-cli tap --ref "$REF"
```

### 다른 언어와 지역에서 앱 테스트하기
```bash
device-mcp-cli apps launch com.example.myapp --language fr --locale fr_FR
device-mcp-cli location set 48.8584 2.2945
device-mcp-cli open-url "myapp://map"
device-mcp-cli appearance dark
```

### 새 시뮬레이터에서 빌드하고 실행하기
```bash
device-mcp-cli simulators start --model "iPhone 17 Pro" --launch
device-mcp-cli build-and-run ~/Projects/MyApp/MyApp.xcodeproj --scheme MyApp
device-mcp-cli screenshot -o ~/Desktop/myapp.png
```

### 버그 화면 기록하기
```bash
device-mcp-cli record start
# reproduce the bug on the device
device-mcp-cli record stop
```

### Mac 설정하기
CI용 Mac이나 새 팀원의 Mac에서 다음을 실행합니다.

```bash
device-mcp-cli license activate --launch < license-key.txt
device-mcp-cli mcp on
device-mcp-cli mcp setup claude
device-mcp-cli status
```

## 5. JSON과 종료 코드
`--json`을 붙이면 명령이 JSON 객체 하나를 출력합니다. 예를 들어 `device-mcp-cli devices --json`은 다음을 출력합니다.

```json
{
  "devices" : [
    {
      "connection" : "USB",
      "current" : true,
      "kind" : "iphone",
      "mirroringStopped" : false,
      "model" : "iPhone 17 Pro",
      "name" : "My iPhone",
      "osVersion" : "27.0.1",
      "platform" : "iOS",
      "state" : "ready",
      "udid" : "00008150-000A1B2C3D4E5F60"
    }
  ]
}
```

기기의 `kind`는 `iphone`, `ipad`, `watch`, `android`, `simulator`, `emulator` 중 하나입니다. `state`는 `ready`, `locked`, `blocked`(`issue`와 `fix`에 원인과 해결 방법이 담깁니다), `connecting`, `running`, `shut_down`, `booting`, `shutting_down`, `creating`, `starting` 중 하나입니다.

오류가 나면 `{"error": {"code": "…", "message": "…"}}`를 출력합니다.

| 코드 | 종료 코드 | 의미 |
| --- | --- | --- |
| `not_running` | 69 | Device MCP가 실행 중이 아니고 열리지도 않았거나, 응답하기 전에 종료되었습니다. |
| `no_answer` | 69 | Device MCP가 실행 중이지만 응답하지 않았습니다. 업데이트하거나, 종료한 다음 다시 여세요. |
| `not_installed` | 69 | Device MCP가 설치되어 있지 않습니다. |
| `invalid_arguments` | 64 | 인수가 잘못되었거나 라이선스 키 형식이 올바르지 않습니다. |
| `pro_required` | 1 | Device MCP Pro가 필요한 명령입니다. |
| `not_approved` | 1 | Device MCP에서 사용자가 거부했거나 아무도 응답하지 않았습니다. |
| `timed_out` | 1 | Device MCP가 제한 시간 안에 끝내지 못했습니다. |
| `cancelled` | 1 | 사용자가 아니요로 답했습니다. |
| `failed` | 1 | 그 밖의 모든 오류입니다. 메시지에 원인이 나옵니다. |

성공한 명령은 0으로 종료합니다.

## 6. AI 에이전트와 함께 사용하기
에이전트도 명령줄을 사용할 수 있습니다. 예를 들어 앱의 테스트 스크립트나 CI 단계를 작성하게 할 수 있습니다.

* *"내 iPhone에서 로그인하고, 홈 화면이 로드되지 않으면 실패하는 스크립트를 작성해 줘."*
* *"온보딩의 모든 화면을 스크린샷으로 찍는 CI 단계를 추가해 줘."*

에이전트가 실행한 명령은 **Agent** 탭에 **device-mcp-cli**로 표시됩니다. [에이전트 활동](ai-agents/agent-activity.md)을 참고하세요.