CLI 레퍼런스
설치
npm install -g tapflowyarn global add tapflowpnpm add -g tapflow업데이트:
npm update -g tapflowtapflow doctor
환경 문제를 진단합니다. 플랫폼을 생략하면 전체를, ios / android를 지정하면 해당 플랫폼만 검사합니다.
tapflow doctor
tapflow doctor ios
tapflow doctor android검사 항목은 다음과 같습니다(기기/AVD는 존재하기만 하면 됩니다. 부팅은 릴레이가 필요할 때 처리합니다).
- Common: Node.js 버전, 포트 4000 사용 가능 여부. 이 Mac에서 릴레이가 4000 포트로 실행 중이면 이 항목이 실패합니다.
- iOS (macOS만): Xcode,
xcrun simctl, 사용 가능한 시뮬레이터, 네트워크 필터, 네트워크 훅, 네트워크 훅 심볼, Lean mode - Android: Android SDK, adb, aapt(build-tools), AVD, Lean mode
네트워크 필터는 두 항목으로 나뉩니다. 실패하는 이유가 다르기 때문입니다 — 설치·승인·켜져 있는가, 그리고 이 맥의 버전들이 이 tapflow가 싣고 온 것과 같은가. 켜져 있는지는 자기 버전이 없는 세 번째 조건입니다. 필터를 꺼도 확장은 활성 상태로 남으므로, 버전은 전부 맞는데 아무것도 필터링하지 않는 상태가 생깁니다.
버전은 두 개이고, 검사는 뒤처진 쪽을 지목합니다. /Applications의 앱과 그 안의 시스템 확장은 따로 버전을 갖습니다. 앱만 바뀐 릴리즈가 돌아가는 필터를 교체할 이유는 없기 때문입니다. 앱은 에이전트가 직접 실행하는 바이너리라서 그 자체로 중요합니다. 낡은 앱은 이해하지 못하는 요청을 받게 됩니다. 뒤의 것은 앞의 것으로 알 수 없습니다. 확장 교체는 맥을 재시작해야 끝나므로, 디스크의 앱은 최신인데 필터링은 옛 것이 하고 있는 상태가 생깁니다. 둘 다 실패가 아니라 경고입니다. 확장이 없어도 세션은 정상 동작하고 iOS 네트워크 제어만 안 됩니다. 네트워크 제어를 참고하세요.
네트워크 훅은 앱에 오프라인이라고 알리는 주입 라이브러리입니다. tapflow와 함께 오므로 없다면 설치가 손상된 것이고, 재설치가 복구입니다. 따로 표시하는 이유는 없을 때 조용하기 때문입니다. macOS는 존재하지 않는 주입 경로를 아무 말 없이 무시하므로, 앱은 훅 없이 뜨고 네트워크 제어는 계속 앱을 실행하라고 안내합니다. 실행한 앱이 눈앞에서 돌고 있는데도 세션 내내 그렇습니다.
--json으로 기계 판독용 출력을 얻을 수 있습니다. 문제가 하나라도 있으면 종료 코드 1을 반환합니다. 경고만 있는 항목은 실패로 세지 않습니다.
| 옵션 | 설명 |
|---|---|
[platform] | ios 또는 android. 생략하면 전체 검사 |
--json | { ok, common, ios, android }를 JSON으로 출력 (ANSI 없음) |
전체 흐름은 환경 준비를 참고하세요.
tapflow setup
플랫폼을 실행할 수 있도록 로컬 환경을 설치·구성합니다. 플랫폼을 생략하면 자동 감지하며 ios / android를 지정할 수도 있습니다.
tapflow setup
tapflow setup ios
tapflow setup android한 번 실행으로 끝까지 진행하면서 설치 단계마다 동의를 구합니다(대화형 터미널만 해당. 비대화형에서는 실행 대신 명령을 안내합니다). 두 플랫폼 모두 Homebrew가 없으면 먼저 설치합니다.
- iOS: App Store에서 Xcode 설치를 안내하고 라이선스 동의·초기 설정을 실행하며(sudo 필요) 시뮬레이터 런타임을 내려받습니다.
- Android: JDK를 설치하고
~/Library/Android/sdk에 자기완결 SDK(명령행 도구·platform-tools·에뮬레이터·시스템 이미지 — Android Studio GUI 불필요)를 구성한 뒤 폼팩터별 AVD를 생성합니다.
모든 단계가 준비되면 종료 코드 0, SETUP INCOMPLETE를 출력하면 1을 반환합니다. doctor는 경고만 있는 항목을 통과시키므로 setup 쪽이 더 엄격합니다. setup은 Mac을 쓸 수 있는지가 아니라 요청받은 작업이 끝났는지를 보고합니다.
macOS에서 setup ios는 iOS 네트워크 제어에 필요한 네트워크 필터도 설치하는데, 다른 설치와 마찬가지로 먼저 동의를 구합니다. 이 맥에 승인된 확장이 없으면 macOS가 승인을 물을 때 승인 화면을 열어줄지도 묻습니다. 그 제안을 거절하지 않았다면 승인이 2분 안에 오지 않아도 켜질 때까지 더 기다렸다가 설치를 마칩니다. 설치를 거절했거나 그 기능이 나오기 전에 설정한 맥이라면 tapflow migrate net-filter로 따로 설치합니다.
설치 마지막에 필터가 돌기 시작했는지를 최대 30초까지 기다리므로 그 단계에서 멈춘 것처럼 보일 수 있습니다. 아무것도 보고하지 않으면 완료로 표시하지 않고 그렇게 말합니다. 자세한 것은 migrate net-filter의 같은 동작을 보세요.
setup은 부팅 가능한 기기/AVD를 준비하는 데까지만 하며 실제 부팅은 세션 접속 시 릴레이가 처리합니다. ANDROID_HOME/PATH를 등록한 뒤에는 새 터미널을 열거나 exec $SHELL을 실행하고 tapflow doctor를 돌리세요.
| 옵션 | 설명 |
|---|---|
[platform] | ios 또는 android. 생략하면 자동 감지 |
전체 흐름은 환경 준비를 참고하세요.
tapflow init
이 머신의 tapflow를 설정합니다. tapflow.config.json, 코딩 에이전트가 읽는 AGENTS.md와 CLAUDE.md, 그리고 DNS 자동 발급을 선택하면 자격 증명 .env까지 만듭니다. 어느 디렉터리에서 실행해도 됩니다. 설치 디렉터리에 쓰고, 기본값은 ~/.tapflow이며 TAPFLOW_HOME이나 현재 디렉터리의 기존 설치가 있으면 그쪽입니다(명령이 쓰는 설치 디렉터리). 디렉터리가 없으면 만듭니다.
다시 실행하면 설정은 그대로 두고 AGENTS.md의 tapflow 섹션만 갱신하므로, 기존 설치도 이 문서를 받을 수 있습니다. 설정을 새로 만들려면 --force를 씁니다. 이미 설정이 있는데 --tunnel을 주면 오류로 멈춥니다. 설정을 유지하면 그 플래그를 무시하게 되기 때문입니다.
터널 플래그 없이 대화형 터미널에서 실행하면 터널 선택 화면이 표시됩니다. 터널을 고르지 않으면 스트리밍 성능(HTTPS)도 묻습니다. 시뮬레이터나 에뮬레이터가 있는 머신에서는 어떤 터널을 고르든 Lean mode도 묻습니다. 답은 설정 파일의 tls와 agent.lean에 적힙니다. 비대화형 환경에서 --tunnel 없이 실행하면 터널 없는 기본 설정 파일이 생성됩니다.
tapflow init| 옵션 | 설명 |
|---|---|
--tunnel <provider> | 터널 프로바이더: tailscale 또는 rathole |
--force | 기존 tapflow.config.json 덮어쓰기 |
Tailscale 예시:
tapflow init --tunnel tailscale
# ✓ CONFIG CREATED
# Install dir: /Users/you/.tapflow (default)
# tapflow.config.json created.
# AGENTS.md created for your coding agent.
# Tunnel: tailscale
# → Next: tapflow start터널 없이 기본 설정 생성:
tapflow init
# ✓ CONFIG CREATED
# → Next: tapflow start다른 디렉터리에 설치를 만들 때:
TAPFLOW_HOME=/var/lib/tapflow tapflow inittapflow admin init
CLI에서 최초 관리자 계정을 생성합니다. 브라우저를 사용할 수 없는 서버에서 폴백으로 사용합니다.
이 명령어 실행 전에 릴레이가 먼저 구동 중이어야 합니다. 이메일과 비밀번호를 물어보므로 대화형 터미널이 필요하고 터미널이 없으면(CI 등) 종료 코드 1로 끝납니다. 릴레이는 같은 머신(localhost)에서 온 요청으로만 첫 계정을 만들기 때문에 --relay로 원격 릴레이를 가리키면 403을 받습니다. 릴레이가 실행 중인 머신에서 실행하세요.
tapflow admin init| 옵션 | 설명 |
|---|---|
--relay <url> | 릴레이 URL (기본값: config의 relay.url, 없으면 http://localhost:4000) |
실행 예시:
? Admin email: admin@yourteam.com
? Password: ********
✓ Admin account created
→ Open http://localhost:4000 to sign in비밀번호는 최소 8자 이상이어야 합니다.
웹 온보딩
최초 실행 시 대시보드가 /setup 페이지로 자동 이동하며, 브라우저에서 관리자 계정을 생성할 수 있습니다. CLI가 필요 없습니다. 브라우저를 사용할 수 없는 경우에만 tapflow admin init을 사용하세요.
tapflow start
릴레이와 에이전트를 같은 Mac에서 한 번에 시작합니다. Mac 한 대로 운영할 때 쓰는 명령입니다. 실행할 수 있는 플랫폼이 없으면 릴레이만 시작합니다.
tapflow start| 옵션 | 설명 |
|---|---|
--platform <ios|android|all> | 시작할 플랫폼 (기본값: 자동 감지) |
--device <name> | 릴레이에 노출할 기기를 한정합니다(기본값: 전체). iOS 시뮬레이터는 이름 또는 UDID, Android 에뮬레이터는 AVD 이름 또는 기기 ID로 지정합니다. 부팅은 대시보드에서 필요할 때 이뤄집니다. |
팀 운영 환경에서는
릴레이를 서버에 따로 배포한다면 tapflow relay start와 tapflow agent start를 사용하세요.
tapflow relay start
릴레이 서버만 시작합니다. 서버 배포 시 사용합니다.
tapflow relay start| 옵션 | 기본값 | 설명 |
|---|---|---|
--port <n> | local.port (기본 4000) | 리슨 포트 |
--tunnel <provider> | — | tailscale 또는 rathole. tapflow.config.json에 tunnel 섹션이 없으면 오류로 멈춥니다. 실제로 띄우는 터널은 이 값과 관계없이 tunnel 섹션이 정합니다. tunnel 섹션이 있으면 이 플래그 없이도 터널을 띄웁니다. |
Tailscale (권장)
tapflow relay starttapflow.config.json:
{
"tunnel": {
"provider": "tailscale"
}
}tapflow가 Tailscale MagicDNS 호스트명을 자동으로 읽어 URL을 구성합니다. "publicUrl"을 설정하면 자동 감지 URL을 덮어씁니다.
VPS + rathole
TAPFLOW_TUNNEL_TOKEN을 데이터 디렉터리의 .env(기본값 ~/.tapflow/data/.env)에 적은 뒤 실행합니다:
tapflow relay starttapflow.config.json:
{
"tunnel": {
"provider": "rathole",
"serverAddr": "your-vps.com:2333",
"publicUrl": "https://your-vps.com",
"ssh": {
"host": "your-vps.com",
"user": "ubuntu",
"keyPath": "~/.ssh/id_ed25519"
}
}
}ssh 섹션을 설정하면 tapflow가 SSH로 VPS에 접속해 rathole 서버를 자동으로 관리합니다 — 첫 실행 시 다운로드·설치·시작까지 처리합니다. ssh를 생략하면 VPS에 rathole 서버가 이미 실행 중인 것으로 간주합니다.
터널이 연결되면 배너에 공개 URL이 출력됩니다. 터널 연결에 실패해도 릴레이는 계속 동작합니다 — 터널만 사용 불가 상태가 됩니다.
tunnel 키 전체는 설정 파일에 있습니다. 전체 세팅 방법은 외부 접속을 참고하세요.
tapflow agent start
에이전트만 시작해 릴레이에 연결합니다. 로컬 릴레이를 띄우지 않습니다.
tapflow agent start --relay ws://192.168.x.x:4000 --token tflw_pat_xxxxxxxx| 옵션 | 기본값 | 설명 |
|---|---|---|
--relay <url> | config의 relay.url, 없으면 ws://localhost:4000 | 릴레이 WebSocket URL. tapflow.config.json에 relay.url이 있으면 생략 가능. |
--platform <ios|android|all> | 자동 감지 | 시작할 플랫폼 |
--device <name> | 전체 기기 | 릴레이에 노출할 기기를 한정. iOS 시뮬레이터는 이름 또는 UDID, Android 에뮬레이터는 AVD 이름 또는 기기 ID |
--token <pat> | TAPFLOW_AGENT_TOKEN 환경변수 | 원격 릴레이가 요구하는 agent 스코프 토큰. 에이전트 설정을 참고하세요. |
--relay는 ws:// 또는 wss://로 시작해야 합니다. Mac 한 대에서는 플랫폼마다 에이전트를 하나만 실행할 수 있습니다. 같은 플랫폼의 에이전트가 이미 실행 중이면 AGENT ALREADY RUNNING을 출력하고 종료합니다. 실행할 수 있는 플랫폼이 없으면 종료 코드 1로 끝납니다.
tapflow devices
사용 가능한 시뮬레이터·에뮬레이터 목록을 표시합니다.
tapflow devicestapflow boot
이름 또는 UDID로 시뮬레이터 또는 에뮬레이터를 부팅합니다. iOS 시뮬레이터를 먼저 검색한 뒤 Android 에뮬레이터를 검색합니다.
# iOS
tapflow boot "iPhone 16 Pro"
tapflow boot 822F00B0-D9CF-4B78-8EDD-6322974E4079
# Android (에뮬레이터 이름)
tapflow boot Pixel_8Android 에뮬레이터는 백그라운드에서 시작됩니다. tapflow devices로 상태를 확인하세요.
tapflow reset
모든 시뮬레이터와 에뮬레이터를 종료합니다.
tapflow reset실행 전에 확인 프롬프트가 표시됩니다 (y/N). y를 입력해야 종료가 진행됩니다.
tapflow status
연결된 에이전트, 기기, 활성 세션을 표시합니다.
tapflow status| 옵션 | 기본값 | 설명 |
|---|---|---|
--relay <url> | config의 relay.url, 없으면 ws://localhost:4000 | 릴레이 WebSocket URL. tapflow.config.json에 relay.url이 있으면 생략 가능. |
연결 방식
tapflow status는 릴레이에 WebSocket으로 연결해 정보를 가져옵니다. 5초 안에 응답이 없으면 타임아웃됩니다. 원격 릴레이를 사용한다면 --relay 옵션이 필요합니다.
출력 예시:
● mac-mini-office (iOS)
◉ iPhone 16 Pro ← qa@company.com
○ iPhone 15
1 agent(s) · 2 device(s) · 1 active session(s)tapflow logs
릴레이가 메모리에 보관하는 최근 로그 항목을 출력합니다(기본값: 최근 100줄). 이 버퍼에 기록되는 이벤트는 많지 않습니다. 릴레이의 전체 로그는 릴레이를 실행한 터미널에 출력됩니다.
릴레이는 자기 호스트에만 이 로그를 보여 주므로 이 명령은 릴레이 호스트에서 실행합니다. 다른 머신에서 원격 릴레이를 가리키면 릴레이가 403으로 거절하고 CLI는 릴레이 호스트에서 할 일을 안내합니다. Docker로 운영하면 컨테이너 밖의 CLI도 원격으로 취급되니 docker compose logs를 쓰세요.
tapflow logs| 옵션 | 기본값 | 설명 |
|---|---|---|
--relay <url> | http://localhost:<local.port> (기본 4000) | 이 머신의 릴레이 URL. 릴레이를 다른 포트로 띄웠을 때 지정합니다. relay.url 설정은 읽지 않습니다. |
--lines <n> | 100 | 표시할 로그 줄 수 (최대 500) |
tapflow flow run
저장된 플로우 파일을 LLM 없이 재생합니다. 플로우 작성법은 플로우 레퍼런스를 참고하세요.
tapflow flow run .tapflow/flows/login-smoke.yaml| 옵션 | 기본값 | 설명 |
|---|---|---|
--relay <url> | ws://localhost:4000 | 릴레이 WebSocket URL. relay.url 설정을 읽지 않습니다. |
--token <token> | TAPFLOW_TOKEN 환경변수, 그다음 토큰 파일 | 원격 릴레이에 접속할 개인 액세스 토큰(PAT). API 유형 토큰(view, builds:write)이 필요합니다. |
--session <id> | — | 대상 세션 ID(MCP 서버의 list_devices로 확인) |
--device <name> | — | 대상 기기 이름. 꺼져 있으면 부팅합니다. |
--build <id> | — | 테스트할 빌드 ID. 실행 전에 설치하고 launchApp 스텝이 이 빌드를 실행합니다. |
--no-install | — | --build를 설치하지 않고 실행 |
--junit <path> | — | JUnit XML 리포트를 쓸 경로 |
--artifacts <dir> | .tapflow/artifacts | 실패 스크린샷을 저장할 디렉터리 |
--timeout <seconds> | 10 | 셀렉터마다 기다리는 기본 시간(초) |
--service-tier <tier> | 에이전트 설정 | 기기가 켜질 때 끌 백그라운드 서비스 범위. stock(모두 켬), lean, slim(거의 모두 끔). iOS 18.5 이상. 아래 설명을 참고하세요. |
--keep <features> | — | --service-tier에서 켜 둘 기능(쉼표로 구분). 예: push,photos |
--admission-timeout <seconds> | 600 | Mac이 바빠서 기다리는 최대 시간(초). 바쁜 경우는 같은 Mac에서 다른 기기가 부팅 중일 때, 메모리가 심각하게 부족할 때, 허용된 자동화 기기를 모두 쓰는 중일 때, CPU·메모리 한도를 넘었을 때입니다. 넘으면 종료 코드 2로 멈춥니다. |
--no-record | — | 이 실행을 릴레이에 기록하지 않음 |
--no-reset | — | 이전 실행이 기기에 남긴 상태를 그대로 둠. 아래 설명을 참고하세요. |
--include-tags <tags> | — | 이 태그 중 하나라도 있는 플로우만 실행(쉼표로 구분) |
--exclude-tags <tags> | — | 이 태그 중 하나라도 있는 플로우는 건너뜀(쉼표로 구분). --include-tags보다 우선합니다. |
--parallel <n> | — | 플로우를 릴레이가 고른 기기 최대 n대(1~16)에 나눠 실행합니다. 아래 설명을 참고하세요. |
--platform <platform> | — | --build 없이 --parallel로 실행할 때의 플랫폼. ios 또는 android |
--secret <name> | — | inputText: { secret: NAME } 단계가 입력할 수 있는 환경 변수 이름. 여러 개면 반복합니다. 비밀 값을 참고하세요. |
--session과 --device를 모두 생략하면 부팅된 기기가 정확히 하나일 때 그 기기를 씁니다. 부팅된 기기가 없거나 여러 대면 환경 오류로 멈춥니다.
--service-tier slim으로 실행하면 기기를 켤 때 백그라운드 서비스를 거의 모두 끕니다. 8GB Mac에서 측정했을 때 부팅 중 CPU가 포화된 시간이 lean의 20~49초에서 7~14초로 줄었습니다. 그만큼 같은 Mac의 다른 세션이 덜 느려집니다. 대신 푸시, StoreKit, Wallet, 사진, 연락처, 위젯, Spotlight, 기기 안에서 도는 AI 모델도 꺼지므로 앱에 필요한 기능은 --keep으로 지정하세요. 지정할 수 있는 기능은 push, storekit, app-store, universal-links, spotlight, siri, icloud, keychain-sync, contacts, calendar, reminders, mail, photos, health, homekit, imessage, widgets, wallet, maps, weather, news, game-center, find-my, screen-time입니다. 이미 다른 범위로 켜져 있는 기기는 요청한 범위로 다시 켭니다. 옵션을 주지 않으면 사람이 기기를 고를 때처럼 에이전트 설정(agent.lean)대로 켭니다.
플로우를 실행하기 전에 기기를 리셋합니다. 이전 실행이 남긴 상태에서 시작하지 않게 하기 위해서입니다. iOS에서는 릴레이가 빌드의 앱을 알려줄 수 있으면(builds:write 스코프가 있는 토큰) 실행이 설치할 빌드를 먼저 삭제하므로 그 앱의 알림·개인정보 권한도 함께 지워집니다. 플로우가 쓰는 다른 앱과, 릴레이가 알려주지 못한 빌드는 데이터만 지웁니다. iOS에서는 키체인, simctl privacy가 다루는 개인정보 권한, 페이스트보드, 시뮬레이션 위치도 리셋합니다. 이 항목들은 기기의 모든 앱에 적용되므로 사람이 쓰는 기기를 지정할 때는 이 점을 감안하세요. simctl keychain add-root-cert로 추가한 루트 인증서는 그대로 신뢰됩니다. Android에서는 빌드와 플로우가 쓰는 앱의 데이터를 지우고 gRPC로 스트리밍하는 에뮬레이터(기본값)라면 클립보드도 지웁니다. 실행은 리셋한 항목을 출력하고 에이전트나 릴레이가 리셋을 지원하지 않는 버전이면 경고합니다. 기기를 그대로 두려면 --no-reset을 주세요.
한 Mac에서는 기기를 한 번에 하나씩 부팅합니다. 부팅 중인 기기는 같은 Mac의 다른 세션을 느리게 만들기 때문입니다. 다른 기기가 부팅 중이면 실행은 세션을 놓고 기다렸다가 다시 시도합니다. 기다리는 동안에는 이유를 출력합니다. 사람이 시작한 부팅은 기다리던 실행보다 먼저 진행됩니다.
--parallel 3으로 실행하면 릴레이가 플랫폼에 맞는 기기 3대를 골라 이 실행에 붙입니다. 이전 실행이 켜 둔 기기를 먼저 쓰고 모자라면 꺼진 기기를 부팅합니다. 사람이 쓰는 기기나 사람이 돌아올 수 있는 기기는 고르지 않습니다. 각 기기는 리셋(--no-reset이 아니면)과 설치를 마친 뒤 남은 플로우를 하나씩 가져가므로 오래 걸리는 플로우가 다른 기기를 붙잡지 않습니다. 플랫폼은 --build의 빌드에서 읽고 빌드가 없으면 --platform으로 지정합니다. --device, --session과는 함께 쓸 수 없습니다. 기기를 부팅하거나 빌드를 설치하지 못한 기기, 그리고 플로우 도중 앱이 아닌 이유로 실패한 기기는 실행에서 빠지고 나머지 기기가 계속합니다. 그 플로우는 다시 실행하지 않습니다. 기기별 출력 줄에는 기기 이름이 붙고 JUnit 리포트에는 기기마다 <testsuite>가 생깁니다. 아무 기기도 실행하지 못한 플로우는 오류로 기록되고 종료 코드 2로 끝납니다.
--build를 주면 플로우의 appId가 그 빌드의 번들 ID와 다른 플로우는 실행하지 않고 건너뜁니다. 태그 옵션에 걸러진 플로우도 건너뜁니다. 건너뛴 플로우는 실패로 세지 않지만 실행된 플로우가 하나도 없으면 기기를 고르기 전에 종료 코드 2로 멈춥니다. 자세한 내용은 실행할 플로우 고르기를 참고하세요.
| 종료 코드 | 의미 |
|---|---|
0 | 모든 플로우 통과 |
1 | 하나 이상의 플로우가 제품 문제로 실패 |
2 | 환경·설정 오류, 실패한 플로우가 모두 환경 문제, 또는 --parallel에서 아무 기기도 실행하지 못한 플로우가 있음 |
130 | SIGINT로 취소됨 |
143 | SIGTERM으로 취소됨 |
토큰을 주면 실행 결과를 릴레이에 기록합니다. 기록은 종료 코드를 바꾸지 않습니다. 자세한 내용은 실행 기록을 참고하세요.
tapflow token set
MCP 서버와 tapflow flow run이 읽는 토큰 파일에 토큰을 저장합니다. 저장하기 전에 릴레이에 한 번 물어보고 릴레이가 받지 않는 토큰은 저장하지 않습니다.
tapflow token set --relay wss://tapflow.example.com| 옵션 | 기본값 | 설명 |
|---|---|---|
--relay <url> | TAPFLOW_RELAY_URL 환경변수, 그다음 ws://localhost:4000 | 토큰을 쓸 릴레이. MCP 서버와 flow run이 접속하는 주소와 같아야 합니다. relay.url 설정은 읽지 않습니다. |
- 터미널에서 실행하면 입력이 보이지 않는 프롬프트로 토큰을 받습니다. CI처럼 터미널이 없으면 stdin의 첫 줄을 읽습니다(
echo "$TOKEN" | tapflow token set). 명령 인자로는 받지 않습니다. - 토큰에
view스코프가 있는지 확인합니다. 실행 기록에 필요한builds:write는 확인하지 않습니다. - 같은 릴레이의 토큰은 바꾸고 다른 릴레이의 토큰은 그대로 둡니다. 파일은 본인만 읽을 수 있게(
600) 만듭니다.
tapflow token status
토큰 파일에 토큰이 있는 릴레이를 나열하고 각 토큰이 지금도 통하는지 확인합니다. MCP 서버가 기본으로 접속하는 릴레이(TAPFLOW_RELAY_URL, 없으면 ws://localhost:4000)에는 ← current를 붙이고 토큰 자체는 출력하지 않습니다. flow run은 TAPFLOW_RELAY_URL을 읽지 않고 --relay만 따릅니다.
tapflow token status| 옵션 | 기본값 | 설명 |
|---|---|---|
--relay <url> | TAPFLOW_RELAY_URL 환경변수, 그다음 ws://localhost:4000 | current로 표시할 릴레이 |
tapflow migrate
업그레이드 후 이 설치에 필요한 마이그레이션을 한 번에 실행합니다.
tapflow migrate아래 마이그레이션을 하나씩 확인해서 해당하는 것만 목록으로 보여 줍니다.
data-dir: 설치 폴더에 데이터가 든.tapflow-data/가 있을 때.net-filter: macOS에서 iOS 네트워크 필터가 설치돼 있는데 지금 tapflow 버전보다 오래됐거나, 설치돼 있는데 동작하지 않을 때. 필터는 선택 기능이라서 설치한 적 없는 맥은 건드리지 않습니다.
터미널에서는 목록을 보여 주고 한 번 묻습니다. 터미널이 없으면(CI, 프로비저닝 스크립트) 목록을 출력하고 묻지 않고 실행합니다. 각 서브커맨드를 따로 실행할 때와 같습니다. 단, net-filter 단계는 macOS 승인 때문에 한 번 더 물을 수 있습니다.
마이그레이션은 순서대로 실행하고 하나가 실패하면 나머지는 실행하지 않고 exit code 1로 끝납니다. 할 일이 없으면 exit 0입니다. .tapflow-data/와 .tapflow/data/가 둘 다 있으면 data-dir은 알리기만 하고 건너뜁니다. 어느 쪽에 데이터가 있는지는 사용자만 알 수 있기 때문입니다. 필터 앱은 지워졌는데 확장이 아직 돌고 있을 때도 net-filter를 같은 방식으로 건너뜁니다. 이 상태는 tapflow doctor ios가 설명합니다.
여기서는 --ignore-running-devices를 받지 않습니다. 필요하면 tapflow migrate net-filter --ignore-running-devices로 실행하세요.
tapflow migrate data-dir
구 .tapflow-data/를 통합 .tapflow/data/ 레이아웃으로 옮깁니다. 업그레이드 후 한 번 실행하면 되고, 멱등이라 다시 돌려도 안전합니다.
먼저 릴레이를 멈추세요. 릴레이 포트(local.port 또는 TAPFLOW_PORT)를 무언가 쓰고 있으면 아무것도 옮기지 않고 거부합니다. 옮기는 동안 릴레이가 돌고 있으면 그 뒤에 올라온 빌드가 다시 .tapflow-data/에 쌓이기 때문입니다. tapflow relay start --port로 다른 포트에 띄운 릴레이는 감지하지 못하므로 직접 멈춰야 합니다.
tapflow migrate data-dir하는 일:
.tapflow-data/를.tapflow/data/로 원자적 rename 합니다. 파일시스템 rename 한 번이라 복사도, 절반만 옮겨진 상태도 없습니다.tapflow.config.json의local.dataDir이 구 기본값.tapflow-data를 가리키면 다시 써줍니다. 커스텀 경로는 건드리지 않습니다..tapflow/data/와.tapflow/artifacts/를.gitignore에 추가해 옮긴 비밀이 git에 올라가지 않게 합니다.
이 명령을 안 돌려도 기존 설치는 그대로 동작합니다. 지정된 local.dataDir은 존중되고, config 없는 기본 설치는 .tapflow-data/를 계속 읽습니다. 두 경로가 서로 다른 파일시스템에 있거나 둘 다 이미 존재하면, 명령은 추측하지 않고 멈춘 뒤 수동 단계를 안내합니다. config는 옮기기 전에 먼저 고치고 옮기기에 실패하면 되돌립니다. 되돌리지도 못하면 원래대로 적어야 할 값을 출력합니다.
tapflow migrate net-filter
tapflow가 iOS 네트워크 필터를 싣기 전에 설정한 맥에 그 필터를 설치합니다. macOS 전용입니다.
tapflow migrate net-filtertapflow setup ios도 필터를 설치하지만, setup은 맥을 새로 준비할 때 돌리는 명령입니다. 이미 설정을 마친 맥은 setup을 다시 돌릴 이유가 없어서, 확장이 node_modules에만 들어오고 맥에는 올라가지 않습니다. 이 명령이 그 자리를 맡고, setup에서 필터 설치를 거절한 경우에도 같습니다.
@tapflowio/ios-agent와 함께 온 서명된 확장을 /Applications로 복사하고 macOS에 활성화를 요청합니다. 승인은 그 맥 앞에서 시스템 설정 → 일반 → 로그인 항목 및 확장 프로그램 → 네트워크 확장에서 합니다. macOS가 명령행 대체를 제공하지 않으므로, 승인을 기다리는 중이면 명령이 그렇게 알려줍니다.
승인 화면은 설치 전에 묻고 기다리는 동안 엽니다. 이 맥에 승인된 tapflow 확장([activated enabled])이 없으면 macOS가 승인을 물을 것이므로 대화형 터미널에서는 설치를 시작하기 전에 승인 화면을 열어줄지 묻습니다. 질문에는 필터를 켤 때 맥에 이미 열려 있던 연결이 끊길 수 있다는 내용도 들어 있습니다. SSH 세션도 여기 포함됩니다. 동의하면 systemextensionsctl list에 요청이 waiting for user로 나타나는 즉시 화면을 엽니다. 이미 대기 중인 요청에는 macOS가 승인 창을 다시 띄우지 않으므로 다시 실행할 때는 이 화면이 유일한 안내입니다. 기기 확인은 이 질문 뒤에 합니다. 이 질문에서 Ctrl-C나 Esc를 누르면 아무것도 설치하지 않고 멈춥니다.
승인이 늦어도 같은 실행에서 끝까지 갑니다. 설치는 승인을 2분까지 기다리고 그 안에 켜지면 그대로 끝납니다. 켜지지 않았으면 명령이 최대 2분 더 기다립니다. 그 안에 켜지면 필터를 켜고 실제로 도는지 확인합니다. 미리 묻지 않았다면 이때 화면을 열지 묻습니다. 이미 승인된 확장을 교체할 때처럼 macOS가 묻지 않을 것으로 보인 경우입니다. 켤 때 macOS가 네트워크 콘텐츠 필터링을 허용할지 물으면 허용하세요.
화면이 열렸다고 말하지 않습니다. 창이 떴는지 명령이 알 방법이 없어서 경로를 함께 보여줍니다. 아무것도 뜨지 않으면 그 경로로 직접 가세요.
명령이 직접 켤 때는 켜기 직전에 기기를 다시 확인합니다. 더 기다린 2분 동안 누군가 시뮬레이터를 부팅했을 수 있기 때문입니다. 찾으면 필터를 켜지 않고 멈추며 필터가 꺼진 상태라면 그것도 알려줍니다. --ignore-running-devices를 줬다면 다시 확인하지 않습니다. 처음 2분 안에 승인되면 확장이 스스로 필터를 켜므로 기기 확인은 설치를 시작할 때의 한 번뿐입니다.
대화형 터미널이 아니면 묻지 않습니다. stdin과 stdout이 모두 터미널이어야 대화형으로 봅니다. 이때와 제안을 거절했을 때는 처음 2분 안에 직접 승인하지 않는 한 승인 대기 상태로 끝납니다. 거절한 제안은 다시 묻지 않습니다. 더 기다린 2분 안에 켜지지 않았을 때도 같습니다. 그러면 승인한 뒤 명령을 다시 실행하라고 안내하고 다시 실행하면 필터가 켜집니다.
자기가 싣고 온 것보다 새 필터는 교체하지 않고 거부합니다. /Applications의 앱은 맥 전역에 하나인데 각 설치는 자기 의존성 기준으로 판단하므로, 옛 체크아웃이 새 에이전트가 기대는 필터를 덮어쓰는 일을 막습니다.
기기를 쓰고 있으면 거부합니다. 필터를 교체하는 동안 맥의 새 연결이 끊기는데, 그 영향을 받는 사람이 명령을 실행한 사람과 같으리라는 보장이 없습니다. 부팅된 시뮬레이터, 붙어 있는 에뮬레이터, :4000에서 서비스 중인 릴레이가 모두 여기 해당합니다. 무엇을 찾았는지 알려주고 멈춥니다.
tapflow migrate net-filter --ignore-running-devices이러면 그래도 교체합니다. 이 옵션은 net-filter 것입니다. tapflow migrate data-dir은 무시하지 않고 거부합니다.
필터를 먼저 껐다가 끝나면 다시 켭니다. 콘텐츠 필터는 시뮬레이터 것만이 아니라 맥의 모든 새 연결 앞에 있습니다. 필터가 켜져 있는 상태에서 멈추면 macOS는 검사받지 않은 트래픽을 흘려보내는 대신 전부 막습니다. 새 연결은 즉시 No route to host로 실패합니다. 필터를 먼저 경로에서 빼면 그 상태가 생기지 않습니다.
앱을 /Applications로 복사하기 전에 끕니다. 확장을 활성화하기 전만이 아닙니다. 두 단계 모두 필터를 멈추기 때문입니다. 앱을 복사하면 macOS가 알아서 필터 세션을 다시 시작합니다. 복사가 끝나면 방금 복사한 바이너리로 한 번 더 끕니다. 활성화를 막는 관문은 그쪽입니다.
명령이 도중에 실패하면 필터가 꺼진 채로 남았는지 알려줍니다. 그 상태에서 맥의 네트워크는 정상이고 iOS 네트워크 제어만 안 됩니다. 명령을 다시 돌리면 켜집니다.
필터가 실제로 돌기 시작했는지 확인한 뒤에 성공을 말합니다. 확장을 설치할 때 macOS가 답하는 것은 "거절하지 않았다"이지 "동작한다"가 아닙니다. 설정은 그 뒤에 필터에게 전달되고 아무것도 돌아오지 않습니다. 그래서 최대 30초까지 지켜보다가 필터가 나타나면 바로 끝냅니다. tapflow setup ios가 필터를 설치할 때도 같습니다.
나타나지 않으면 그렇게 말하고 0이 아닌 코드로 종료합니다. 설정은 켜져 있는데 아무도 답하지 않는 상태이기 때문입니다. 대개는 아직 기동 중이고 잠시 뒤 tapflow doctor ios가 정상이라고 답합니다. 맥의 새 연결이 멈췄다면 문제 해결을 보세요. 해법은 --off로 필터를 경로에서 빼는 것입니다.
끝나고 tapflow doctor ios로 맥이 어떤 상태가 됐는지 확인하세요.