Wonda CLI
Wonda CLI는 터미널 기반 에이전트를 위한 콘텐츠 제작 도구 키트입니다. 이미지, 비디오, 음악, 오디오를 생성하고, 미디어를 편집 및 합성하며, 소셜 플랫폼에 게시하고, LinkedIn, Reddit, X/Twitter 전반에서 리서치 및 자동화를 수행하는 데 사용하세요.
설치
wonda가 PATH에서 발견되지 않으면 먼저 설치하세요. 권장 설치는 서명된 데스크톱 설치 프로그램(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또는 첫 실행 브라우저 핸드오프로 릴레이를 페어링합니다. 이는 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는 유료 전용입니다: 모든 제품 표면(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: 프로비저닝, 예약 실행, 스트리밍 로그인) 및 안티디텍트/섀도우밴 보호, 제한 없음, 미국 계정 생성이 포함됩니다. |
| 플래그 지정 (계정별 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일 만료: 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는 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)
1Password는 로컬 WAB 프로필에 포함되어 있습니다. WAB는 공식 안정적인 1Password 브라우저 확장 프로그램을 다운로드하고, 게시자 서명을 확인하며, 첫 번째 설정 시 도구 모음에 고정합니다. wonda wab show <persona>로 WAB를 연 다음 1Password를 클릭하여 로그인하세요. 각 persona는 자체 1Password 세션을 유지합니다. 데스크톱 앱에서 WAB를 추가 브라우저로 승인해야 할 수 있습니다. 확장 프로그램에 직접 로그인해도 작동합니다. 캐시된 확장 프로그램 파일은 오프라인에서도 작동합니다. WAB는 persona가 시작될 때 하루에 최대 한 번 캐시된 확장 프로그램의 업데이트를 확인합니다(실패한 확인 포함). Chromium 버전을 변경하면 다른 호환성 확인이 트리거됩니다. 확장 프로그램이 한 번도 성공적으로 설치된 적이 없으면 각 시작 시 설치를 다시 시도합니다. 이미 실행 중인 브라우저는 다음 시작 시 확장 프로그램 업데이트를 적용합니다. 시작 및 wab install은 7일 이상 된 사용되지 않는 캐시 버전을 제거합니다. 실행 중인 WAB 프로세스에서 사용하는 버전은 유지됩니다. 번들 확장 프로그램을 건너뛰려면 WAB를 시작하기 전에 WAB_ONEPASSWORD=0을 설정하세요. 익명 캡처, 스크래치 세션 및 클라우드 트윈은 확장 프로그램을 로드하지 않습니다. 쉼표가 포함된 Wonda 데이터 경로는 경고와 함께 1Password를 건너뜁니다.