wonda-cli
개요
터미널에서 이미지, 비디오, 음악, 오디오를 생성하고 LinkedIn, Reddit, X/Twitter 리서치 및 자동화를 위한 Wonda CLI 사용하기
워크플로
name: wonda-cli description: 터미널에서 이미지, 비디오, 음악, 오디오를 생성하고 LinkedIn, Reddit, X/Twitter 리서치 및 자동화를 위한 Wonda CLI 사용하기
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 "Hello world" \
--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, 이유를 명시할 수 있을 때마다 `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 <경로>— 출력을 파일로 다운로드 (--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 자동화 브라우저 (wonda wab)
Wonda 자동화 브라우저(WAB)는 플랫폼이 자동화로 식별할 수 없도록 강화된 프리미엄 스텔스 안티디텍트 브라우저입니다. wonda wab은 안티디텍트 Chromium 스택(감지되지 않는 Playwright 포크)을 위한 하나의 명령어입니다. 두 가지 측면이 있습니다:
- 인증된 세션. LinkedIn, X, Reddit 등에서 로그인된 세션을 유지하는 페르소나당 하나의 지속적인 헤드풀 Chromium입니다. CLI는 필요에 따라 이를 시작하고, 유휴 상태로 두며, 명령어가
--via wab으로 실행될 때마다 플랫폼 읽기/쓰기를 이를 통해 라우팅합니다. 쿠키는 페르소나의 Chromium 프로필에 있으며~/.wonda/config.json에 없습니다. - 익명 캡처.
wonda wab record <url>(및wonda brand extract)는 새로운 지문, 페르소나 없음, 쿠키 없음으로 임시 Chromium을 구동합니다. 아래record블록을 참조하세요.
멘탈 모델: 계정(플랫폼당 하나의 ID)이 있습니다. 각 플랫폼 명령어는 플랫 JSON 저장소(--via cookies, 빠름, Chromium 없음) 또는 계정의 페르소나(--via wab, 라이브 안티디텍트 Chromium)를 통해 해당 계정의 쿠키로 라우팅됩니다. 페르소나는 하나의 지문 아래 여러 계정을 보유할 수 있는 Chromium 봉투입니다. 거의 모든 경우 페르소나는 au