Wonda CLI
Wonda CLI는 터미널 기반 에이전트를 위한 콘텐츠 제작 도구 모음입니다. 이미지, 비디오, 음악, 오디오를 생성하고, 미디어를 편집/구성하며, 소셜 플랫폼에 게시하고, LinkedIn, Reddit, X/Twitter에서 리서치 및 자동화를 수행할 수 있습니다.
설치
wonda가 PATH에 없으면 먼저 설치하세요:
# 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또는 최초 실행 브라우저 핸드오프로 릴레이를 페어링합니다. 이는 macOS 키체인에 저장된wrelay_...범위의 자격 증명과 함께 기존cli-auth흐름을 사용합니다. 사용자에게 API 키나 장치 코드를 붙여넣도록 요청하지 마세요.https://wonda.sh/setup을 열고, 헤드풀 로컬 WAB를 통해 LinkedIn, X, Reddit을 연결한 후, Claude에서 Wonda 커넥터를 한 번 승인합니다.
엔진 정책은 auto | my_machine | cloud입니다. auto는 로컬 릴레이가 온라인일 때 사용하고, 그렇지 않으면 클라우드를 사용합니다. my_machine은 자동으로 대체되지 않아야 합니다: 릴레이가 오프라인이면 클라우드로 전환할지 물어보세요.
조직 및 지출 컨텍스트
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는 유료 전용입니다: 모든 제품 표면(생성, 미디어, 게시, 스크래핑, 분석, 스킬, 클라우드 트윈)에는 유료 요금제가 필요합니다. 신규 계정은 크레딧이나 제품 액세스 없이 가입 후 사용 가능합니다.
| 등급 | 액세스 |
|---|---|
| 익명 (임시 계정, 로그인 불필요) | 제품 액세스 없음. CLI는 최초 실행 시 임시 계정을 생성하지만, 아래 로컬 명령과 인증/결제 엔드포인트에만 접근할 수 있습니다. 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: 프로비저닝, 예약 실행, 스트리밍 로그인)과 안티디텍트/섀도밴 보호, 제한 없음, 미국 계정 생성. |
| 플래그됨 (계정별 PostHog 킬 스위치) | 유료 요금제에 포함되지만 계정별 플래그로 제어 가능: wonda reddit signup (redditAccountCreationEnabled), wonda email (emailServerApiEnabled), 공개 LinkedIn 프로필 강화 (linkedinProfileEnrichmentEnabled). |
| 로컬 (API 호출 없음, 크레딧 없음, 요금제 없음) | 요금제 없이 머신에서 완전히 로컬로 실행: wonda brand extract <url> (--save 제외), wonda compose motion/wonda compose text, wonda wab record <url>, 로컬 파일에 대한 wonda edit ... ffmpeg 기본 변환, wonda doctor. Chromium 기반 명령은 일회성 wonda wab install이 필요합니다. |
명령이 403 (paid_plan_required)을 반환하면 https://wonda.sh/account에서 구독하세요.
음성 복제
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 "안녕하세요" \
--model minimax-speech-2-8-hd \
--params '{"voiceId":"<providerVoiceId>"}'
7일 만료: 7일 이내에 TTS에서 사용되지 않은 복제된 음성은 자동으로 만료됩니다. 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는 활성 공지사항(지원 중단 알림, 인 incident 주의보, 업그레이드 프롬프트)을 위해 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을 사용할 때마다 플랫폼 읽기/쓰기를 이를 통해 라우팅합니다. 쿠키는~/.wonda/config.json이 아닌 페르소나의 Chromium 프로필에 저장됩니다. - 익명 캡처.
wonda wab record <url>(및wonda brand extract)는 새로운 지문, 페르소나 없음, 쿠키 없이 임시 Chromium을 구동합니다. 아래record블록을 참조하세요.
멘탈 모델: 계정이 있습니다(플랫폼당 하나의 ID). 각 플랫폼 명령은 평면 JSON 저장소(--via cookies, 빠름, Chromium 없음) 또는 계정의 페르소나(--via wab, 실시간 안티디텍트 Chromium)를 통해 해당 계정의 쿠키로 라우팅됩니다. 페르소나는 하나의 지문 아래 여러 계정을 보유할 수 있는 Chromium 봉투입니다. 거의 모든 경우 페르소나는 첫 --via wab 사용 시 계정 이름으로 자동 생성되므로 페르소나 이름을 입력할 필요가 없습니다.
로컬 wonda.mcpb 데스크톱 확장은 Claude Desktop 또는 Claude Code에서 이 동일한 로컬 WAB 경로를 사용합니다: 플랫폼 쿠키는 기기에 남고, 읽기는 로컬 쿠키를 사용하며, 쓰기는 로컬 WAB를 사용합니다. Claude 웹 및 Cowork는 대신 원격 MCP 커넥터가 필요합니다.