Wonda CLI
Wonda CLI는 터미널 기반 에이전트를 위한 콘텐츠 제작 도구 키트입니다. 이미지, 비디오, 음악, 오디오를 생성하고, 미디어를 편집 및 합성하며, 소셜 플랫폼에 게시하고, LinkedIn, Reddit, X/Twitter에서 리서치 및 자동화를 수행할 수 있습니다.
설치
PATH에서 wonda를 찾을 수 없으면 먼저 설치하세요. 권장 설치는 서명된 데스크톱 설치 프로그램(CLI + 트레이 아이콘 + 항상 켜져 있는 릴레이, 추가 단계 불필요)입니다: macOS brew install --cask degausai/tap/wonda-app (또는 릴리스의 wonda-macos.pkg), Windows winget/wonda-windows-setup.exe. 아래 CLI 전용 채널은 모든 곳에서 작동하며 나중에 wonda app install로 데스크톱 앱을 추가할 수 있습니다.
# npm
npm i -g @degausai/wonda
# Homebrew
brew tap degausai/tap && brew install wonda
설정
- 인증:
wonda auth login(브라우저 열림, 권장) 또는WONDA_API_KEY환경 변수 설정 - 확인:
wonda auth check
OAuth 커넥터 인증
Claude 웹 및 Cowork 커넥터는 CLI API 키 필드 대신 Wonda의 OAuth 2.1 흐름을 사용합니다. 커넥터는 브라우저에서 Wonda를 통해 로그인하고, 요청된 계정 액세스 권한을 부여하며, Wonda API 리소스에 바인딩된 OAuth 토큰을 받습니다. 서버는 해당 토큰을 Wonda 내부에서만 계정의 내부 API 키로 교환하므로, 에이전트와 커넥터 호스트는 sk_... 키를 절대 볼 수 없습니다. CLI 및 로컬 stdio MCP 경로의 경우 계속 wonda auth login 또는 WONDA_API_KEY를 사용하세요.
Claude Cowork 로컬 릴레이
Claude Cowork(데스크톱 앱)은 호스트에서 로컬 MCP 서버를 실행하므로 .mcpb 번들이나 로컬 stdio wonda-mcp 구성을 직접 로드할 수 있으며, WAB 쓰기도 포함됩니다(2026-07-07 확인). Claude 웹은 불가능합니다. Wonda 로컬 릴레이는 대체 경로입니다: 원격 커넥터(웹 또는 Cowork)가 로컬 MCP 구성 없이 사용자 자신의 Mac 및 가정용 IP에서 액션을 실행할 수 있게 합니다.
- 로그인한 상태에서
https://wonda.sh/download를 열고 공증된 Mac 패키지를 설치합니다. wonda relay pair또는 최초 실행 브라우저 핸드오프로 릴레이를 페어링합니다. 이는 기존cli-auth흐름을 사용하며, macOS 키체인에 저장된 릴레이 범위의wrelay_...자격 증명을 사용합니다. 사용자에게 API 키나 장치 코드를 붙여넣도록 요청하지 마세요.https://wonda.sh/setup을 열고, 헤드풀 로컬 WAB를 통해 LinkedIn, X, Reddit을 연결한 후, Claude에서 Wonda 커넥터를 한 번 승인합니다.
엔진 정책은 auto | my_machine | cloud입니다. auto는 로컬 릴레이가 온라인일 때 사용하고, 그렇지 않으면 클라우드를 사용합니다. my_machine은 자동으로 대체(fallback)해서는 안 됩니다: 릴레이가 오프라인인 경우 클라우드로 전환할지 묻습니다.
조직 및 지출 컨텍스트
Wondercat 조직은 자체 시트와 청구 체계를 가진 공유 지갑입니다. 구성원은 컨텍스트를 전환하여 개인 크레딧 대신 조직 지갑에서 지출할 수 있습니다.
wonda organizations list(별칭:wonda orgs list,wonda org list) — 자신이 속한 모든 조직과 각 조직에서의 역할 및 시트 요금제를 확인합니다.wonda use --org <slug>— 이 머신에 대한 고정 조직 컨텍스트입니다. 모든 요청에X-Wonda-Org를 설정하고, 보유, 청구 및wonda balance는 조직 지갑을 통해 처리됩니다.wonda use --personal— 개인 컨텍스트로 돌아갑니다.wonda usage— 특정 기간(--month 2026-05또는--from/--to; 기본값은 현재 월, UTC)에 대한 지출 전용 사용 요약(총계 + 모델별 + 프로젝트별 세분화)입니다.--project <name>은 보고서를 하나의 프로젝트로 제한합니다. 조직 컨텍스트에서는 구성원별 세분화를 포함한 조직 전체 사용량을 보고합니다(관리자/소유자 역할 필요). 관리자는 웹의 조직 페이지에서 전체 Excel 보고서를 다운로드할 수도 있습니다.
프로젝트 (지출 태깅)
프로젝트는 모니터링을 위해 지출을 명명된 작업 스트림에 귀속시킵니다. 에이전트는 작업 시작 시 활성 프로젝트를 확인하고(wonda use가 출력), 운영자가 프로젝트별로 지출을 모니터링할 때 작업별로 하나를 설정해야 합니다.
wonda use --project <name>— 고정: 이후 모든 청구에 프로젝트가 포함됩니다(wonda usage, API 및 조직 Excel 보고서에서).wonda use --no-project는 태깅을 중지합니다. 조직/개인 컨텍스트 전환은 프로젝트를 자동으로 지웁니다(프로젝트는 범위별로 적용됨).- 모든 명령에
--project <name>— 해당 호출에 대한 일회성 재정의입니다. wonda project list|create|delete— 활성 범위에서 레지스트리를 관리합니다. 조직 프로젝트는 조직 관리자/소유자만 생성할 수 있고, 개인 프로젝트는 셀프 서비스입니다. 존재하지 않는 이름에 대한 태깅은unknown_project오류와 함께 실패합니다(새 버킷이 자동 생성되지 않으므로 오타가 모니터링 데이터를 분할할 수 없음).
wonda topup는 컨텍스트와 관계없이 항상 개인 지갑을 충전합니다. 조직 지갑 충전(및 자동 충전 구성)은 관리자 전용이며 웹의 /organizations/<slug>에서 수행됩니다. 구성원이 조직 크레딧을 모두 소진하면 오류 메시지가 관리자에게 문의하거나 개인 컨텍스트로 전환하도록 안내하며, CLI에서 조직 지갑을 충전할 수 없습니다.
조직 내 역할은 시트 요금제와 별개입니다.
- 소유자: 원래 생성자입니다. 강등되거나 추방될 수 없습니다. 조직 페이지에서 다른 구성원에게 소유권을 이전할 수 있습니다(드문 경우).
- 관리자: 초대(단일 또는 대량 붙여넣기), 추방, 역할 변경, 시트 변경, 충전, 자동 충전 구성, 월별 한도 변경을 수행할 수 있습니다.
- 사용자: 조직 지갑 내에서만 지출할 수 있습니다(관리자가 설정한 경우 구성원별 월별 한도 적용).
유료 조직 시트(WONDA / WONDA_PREMIUM)는 조직 컨텍스트에 있는 동안 개인 유료 요금제와 동일한 유료 기능 액세스(스킬 등)를 부여합니다. wonda use --personal은 사용자의 개인 계정 요금제로 대체됩니다.
액세스 등급
Wonda는 유료 전용입니다: 모든 제품 영역(API 호출, 로컬 플랫폼 읽기, 브라우저 자동화, 미디어 합성, 파일 편집, 진단, 생성, 게시, 스크래핑, 분석, 스킬, 릴레이 운영, 클라우드 트윈 포함)에는 유료 요금제가 필요합니다. 제품 명령이 작업을 수행하기 전에 CLI는 Wonda에 대해 실시간 권한 확인을 수행합니다. 액세스를 확인할 수 없으면 확인에 실패하고 닫힙니다. 새 계정은 구독할 때까지 제품 액세스 권한이 없으며, 양수 크레딧 잔액이 요금제를 대체하지 않습니다.
| 등급 | 액세스 |
|---|---|
| 익명 (로그인 안 함) | 제품 액세스 권한 없음. 인증, 구성, 가격, 조직 검색/선택, 셸 완성, 로컬 종료 명령은 사용자가 구독, 복구 또는 백그라운드 서비스를 중지할 수 있도록 계속 사용 가능합니다. wonda auth login을 실행한 다음 구독하세요. |
| 무료 (로그인됨, 유료 요금제 없음) | 제품 액세스 권한 없음. https://wonda.sh/account에서 구독하여 제품을 사용하세요. |
WONDA ($19.99/월, "Pro") | 클라우드 트윈을 제외한 모든 기능: 생성(image/generate, video/generate, ...), 미디어 업로드/다운로드, 게시, 스크래핑, 분석, 비디오 분석, 스킬(wonda skill install/list/get), 전환, 클리핑, 이메일, reddit/linkedin 계정 생성, 스타일, 브랜드. |
WONDA_PREMIUM ($49.99/월, "Premium") | WONDA의 모든 기능 및 클라우드 트윈(wonda twin: 프로비저닝, 예약 실행, 스트리밍 로그인) 포함, 안티디텍트/섀도우밴 보호, 제한 없음, US 계정 생성. |
| 플래그됨 (계정별 PostHog 킬 스위치) | 유료 요금제에 포함되지만 계정별 플래그로 게이트 가능: wonda reddit signup (redditAccountCreationEnabled), wonda email (emailServerApiEnabled), 공개 LinkedIn 프로필 강화 (linkedinProfileEnrichmentEnabled). |
명령이 403(paid_plan_required)을 반환하면 https://wonda.sh/account에서 구독하세요.
이는 로컬 stdio MCP 경로에도 적용됩니다. MCP는 동일한 CLI를 실행하기 때문입니다. 플랫폼 쿠키와 데이터는 장치에 남아 있지만, 명령은 먼저 GET /api/v1/auth/access에서 성공적인 유료 액세스 결정을 받아야 합니다. 릴레이 전용 설치는 해당 권한 확인을 위해 범위가 지정된 wrelay_... 자격 증명을 사용할 수 있습니다. 범위가 지정된 자격 증명은 여전히 일반 계정 API를 호출할 수 없습니다.
음성 복제
10초 이상의 오디오 클립에서 음성을 복제하고 TTS에서 사용합니다. 하드 제한: 계정당 복제된 음성 20개. 비용: 복제당 $1.50.
# 로컬 파일에서 복제 (먼저 미디어 라이브러리에 자동 업로드됨)
wonda voice create "Andu" --file ./sample.mp3 --description "내 목소리"
# 기존 wonda 미디어에서 복제
wonda voice create "Brand" --media-id <uuid>
# 선택적 소스 오디오 전처리
wonda voice create "Clean" --file ./raw.wav --noise-reduction --normalize-volume
# 복제된 음성 목록 (각 행은 isExpired 및 expiresInDays 보고)
wonda voice list
# 하나의 음성
wonda voice get <voice-id>
# 이름/설명 변경 (로컬 전용, 제공자 호출 없음)
wonda voice update <voice-id> --name "새 이름" --description "..."
# 삭제
wonda voice delete <voice-id>
TTS에서 복제된 음성 사용: voice get의 providerVoiceId를 /audio/speech에 voiceId로 전달합니다.
wonda audio speech "Hello world" \
--model minimax-speech-2-8-hd \
--params '{"voiceId":"<providerVoiceId>"}'
7일 만료: TTS에서 7일 동안 사용되지 않은 복제된 음성은 자동으로 만료됩니다. 복제된 음성으로 TTS를 실행하면 만료가 자동으로 갱신됩니다. 유휴 음성이 만료되면 다시 복제해야 합니다($1.50 다시 지불).
자격 증명 볼트
외부 플랫폼(Instagram, TikTok, Twitter 등)에서 생성된 로그인을 유지하여 다음 실행 시 재사용할 수 있습니다. 비밀번호는 서버 측 키로 AES-256-GCM 암호화되며 get 시에만 복호화됩니다.
# 생성
wonda credentials create --website instagram.com --username myhandle \
--email [email protected] --password-stdin <<< "hunter2" \
--metadata '{"signup_source":"wonda-email"}'
# 목록 (비밀번호 생략)
wonda credentials list --website instagram.com
# 복호화된 비밀번호를 포함한 전체 레코드 가져오기
wonda credentials get <id>
# 필드 업데이트 (--password-stdin으로 교체, --username ""로 지우기)
wonda credentials update <id> --username newhandle
# 삭제
wonda credentials delete <id>
# 가져오기 + 사용 이유 기록을 한 번에 수행 - GET이 아닌 POST,
# 이유와 함께 'used' 이벤트를 기록하기 때문입니다.
# 이유를 설명할 수 있을 때마다 `get`보다 이 방법을 선호하세요.
wonda credentials use <id> --reason "instagram 가입 흐름"
# 감사용 최근 이벤트 보기 (생성/사용/교체/업데이트)
wonda credentials events <id>
필드: website (필수 — insta와 같은 입력은 instagram.com으로 정규화됨), username, email, password (필수), metadata (임의 JSON). username / email 중 하나는 반드시 있어야 합니다. (website, username)당 여러 레코드가 허용되며, 필요하면 측에서 중복을 제거하세요.
이벤트 로그: 모든 credentials get/use, create, 비밀번호 교체 및 기타 업데이트는 자격 증명에 이벤트로 기록됩니다(행위자: cli | web | system). 감사에는 credentials events <id> 또는 웹 UI의 기록 아이콘을 사용하세요. 이벤트 로그는 추가 전용이며 자격 증명 삭제 시 함께 삭제됩니다.
전역 출력 플래그
모든 명령은 다음 출력 제어 플래그를 지원합니다.
--json— JSON 출력 강제 (stdout이 파이프될 때 자동 활성화됨)--quiet— 기본 식별자(작업 ID, 미디어 ID 등)만 출력 — 스크립팅에 이상적-o <path>— 출력을 파일로 다운로드 (--wait암시)--fields status,outputs— 특정 JSON 필드 선택--jq '.outputs[0].media.url'— jq 표현식으로 JSON 출력 필터링
CLI 공지 및 지원 중단 경고
모든 명령에서 CLI는 GET /api/v1/updates를 폴링합니다(익명, ~/.wonda/state.json에 1시간 캐시). 활성 공지(지원 중단 알림, 사고 헤드업, 업그레이드 프롬프트)를 확인합니다. 메시지는 stderr에만 출력되므로 stdout/JSON은 파이핑을 위해 깨끗하게 유지됩니다.
요청별 지원 중단 힌트는 표준 Warning: 299 - "<message>" HTTP 헤더로 도착하며 CLI의 HTTP 클라이언트에 의해 [deprecated METHOD /path] <message>로 stderr에 표시됩니다.
두 채널을 모두 WONDA_QUIET=1 (환경 변수) 또는 --quiet (플래그)로 음소거합니다. 네트워크 확인만 비활성화하려면 WONDA_NO_UPDATE_CHECK=1을 사용하세요.
WAB / Wonda Automation Browser (wonda wab)
Wonda Automation Browser(WAB)는 프리미엄 스텔스 안티디텍트 브라우저로, 플랫폼이 자동화로 식별할 수 없도록 강화되었습니다. wonda wab는 안티디텍트 Chromium 스택(감지되지 않는 Playwright 포크)을 위한 단일 명령어입니다. 두 가지 모드가 있습니다.
- 인증된 세션. 페르소나당 하나의 지속적인 헤드풀 Chromium으로 LinkedIn, X, Reddit 등의 로그인 세션을 유지합니다. CLI는 필요 시 실행하고, 유휴 시간이 지나면 종료하며, 명령이
--via wab으로 실행될 때마다 이를 통해 플랫폼 읽기/쓰기를 라우팅합니다. 쿠키는 페르소나의 Chromium 프로필에 저장되며~/.wonda/config.json에는 저장되지 않습니다. - 익명 캡처.
wonda wab record <url>(및wonda brand extract)는 새로운 지문, 페르소나 없음, 쿠키 없이 임시 Chromium을 구동합니다. 아래record블록을 참조하세요.
멘탈 모델: 계정이 있습니다(플랫폼당 하나의 신원). 각 플랫폼 명령은 플랫 JSON 저장소(--via cookies, 빠름, Chromium 불필요) 또는 계정의 페르소나(--via wab, 실시간 안티디텍트 Chromium)를 통해 해당 계정의 쿠키로 라우팅됩니다. 페르소나는 하나의 지문 아래 여러 계정을 보유할 수 있는 Chromium 봉투입니다.
…
[번역을 위해 잘림]