Insights
AI가 자동으로 큐레이션·번역·정리하는 기술 동향 피드입니다.
ElevenLabs CLI는 플랫폼의 모든 API 엔드포인트에 접근할 수 있는 커맨드라인 인터페이스입니다. 이 도구는 'Agents as Code' 기능을 제공하여, 로컬 설정 파일에서 대화형 AI 에이전트를 관리하고 개발하는 것을 지원합니다.
AI 자동 생성 콘텐츠
본 콘텐츠는 GitHub Codex tools의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.
원문 바로가기hero
ElevenLabs 플랫폼용 커맨드라인 인터페이스(CLI).
이 CLI는 두 가지 기능을 수행합니다:
elevenlabs <resource> <method>)로 사용 가능합니다.brew install elevenlabs/tap/elevenlabs
scoop bucket add elevenlabs https://github.com/elevenlabs/scoop-bucket
scoop install elevenlabs
npm install -g @elevenlabs/cli
이 명령어는 얇은 런처(thin launcher)를 통해 동일한 바이너리를 설치하며, 사용자의 플랫폼에 맞는 빌드를 자동으로 선택합니다. 전역으로 설치하지 않고 한 번 실행하려면 npx @elevenlabs/cli <command>를 사용하십시오.
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/elevenlabs/cli/releases/latest/download/elevenlabs-cli-installer.sh | sh
powershell -ExecutionPolicy ByPass -c "irm https://github.com/elevenlabs/cli/releases/latest/download/elevenlabs-cli-installer.ps1 | iex"
Rust 툴체인(toolchain)을 설치한 후 다음 단계를 따릅니다:
git clone https://github.com/elevenlabs/cli.git
cd cli
cargo build --release
생성된 바이너리 파일은 ./target/release/elevenlabs에 위치합니다. 이 파일을 어디서든 elevenlabs로 실행하려면, cargo를 사용하여 설치해야 합니다. 이는 해당 파일을 ~/.cargo/bin 디렉터리로 복사해 줍니다:
cargo install --path .
모든 요청은 ElevenLabs API 키로 인증되며, xi-api-key 헤더를 통해 전송됩니다. 환경 변수에 설정하세요:
export ELEVENLABS_API_KEY=xi-...
작업 디렉터리에 .env 파일을 두면 자동으로 로드되므로, 여기에 ELEVENLABS_API_KEY=xi-...를 넣는 것도 가능합니다. 이는 키를 특정 프로젝트에 한정하는 데 유용합니다.
일회성 호출의 경우, 명령별로 직접 전달할 수 있습니다:
elevenlabs user get --xi-api-key xi-...
사용 가능한 명령어 목록을 확인하세요:
elevenlabs --help
API 엔드포인트를 호출합니다:
elevenlabs <리소스> <메서드>
특정 리소스의 사용 가능한 메서드를 보려면 elevenlabs <리소스> --help를 실행하세요.
파일 경로를 지정하거나 플레이어를 찾을 필요 없이, 텍스트를 음성으로 변환하여 재생합니다:
elevenlabs say "this came from the terminal"
echo "build finished" | elevenlabs say # 또는: elevenlabs say -
음성(voice), 모델(model), 오디오 형식(audio format) 및 플레이어는 저장된 기본값으로 설정되며, 각 항목은 실행 시마다 재정의할 수 있습니다:
elevenlabs say config # 현재 기본값 표시
elevenlabs say config voice 21m00Tcm4TlvDq8ikWAM
elevenlabs say config model eleven_multilingual_v2
...
기본 설정은 data residency와 함께 ~/.elevenlabs/config.json에 저장됩니다. 기본적으로 say 명령어는 가장 표현력이 뛰어난 모델인 eleven_v4를 사용하며, (v3의 경우) [audio tags] 같은 elevenlabs say "[whispers] it worked"와 같이 단어라기보다는 전달 방식(delivery)으로 읽는 유일한 계열입니다. 오디오 형식은 --output-format 또는 --output 파일 이름이 지정하지 않는 한 플레이어를 따릅니다.
재생은 장치에 설치된 어떤 플레이어도 사용하며, 특히 다운로드가 완료되기 전에 오디오가 시작되도록 stdin을 읽는 플레이어(예: ffplay, mpv, afplay (macOS), paplay/aplay (Linux), Media.SoundPlayer (Windows))를 선호합니다. 만약 해당 플레이어가 없다면 ffmpeg 또는 mpv를 설치하거나, --player 옵션을 사용하여 직접 지정할 수 있습니다.
config는 하위 명령어(subcommand)이므로, 이 정확한 단어를 말하려면elevenlabs say -- config가 필요합니다.
Flows의 이미지, 비디오 및 텍스트-음성 변환 생성 작업과 템플릿 실행은 백그라운드에서 완료됩니다. create는 즉시 status: pending 상태로 반환됩니다. create-and-wait는 create와 동일한 플래그를 사용하며, 결과가 completed 또는 failed가 될 때까지 폴링(polling)하여 그 결과를 출력합니다 (결과는 get과 동일한 JSON 형식입니다):
elevenlabs flows image create-and-wait \
--json '{"model_id": "bytedance-seedream-5-lite", "prompt": "a corgi on a beach""}'
...
이 명령어는 서버의 Retry-After 헤더가 요청하는 시간만큼, 최소 --min-poll-interval(기본값 3초)보다 짧지 않게 대기합니다. 진행 상황은 stderr가 터미널인 경우 또는 --debug 플래그를 사용할 때 stderr에 기록됩니다. stdout에는 최종 결과만 담기 때문에, --format, --query 및 파이프(|)의 동작은 get 명령어와 동일하게 작동합니다.
failed**는 다른 결과와 마찬가지로 출력되며, 명령어는 1을 반환하며 종료됩니다.--wait-timeout <초>**는 지정된 시간이 지나면 포기합니다(기본값: 무기한 대기). 이 경우, reason이 waitTimeout인 오류와 함께 1을 반환하며 종료되며, 재개할 수 있는 id와 get 명령어를 전달받습니다. 작업은 서버에서 계속 실행됩니다.--dry-run**은 create 시와 마찬가지로 생성 요청만 출력하고 아무것도 전송하지 않습니다.운영 환경에서는 프로세스를 열어두는 것보다 create 시에 webhook을 설정하고 웹훅 이벤트를 처리하는 것을 선호합니다.
로컬 설정 파일에서 대화형 AI 에이전트(Conversational AI agents)를 관리할 수 있습니다. elevenlabs agents init은 프로젝트의 골격(scaffolds)을 만듭니다. 에이전트 구성(agent configs)은 디스크에 JSON 형태로 존재하며 ElevenLabs와 동기화됩니다. 가져온 구성(Pulled configs)은 원시 와이어 JSON(raw wire JSON)으로 저장되고, 변경 없이 다시 푸시되므로 손실 없이 왕복(round-trip losslessly)이 가능합니다.
your_project/
├── agents.json # 에이전트 레지스트리: id + 브랜치 매핑 → 구성 경로
├── tools.json # 도구 레지스트리
...
# 새 프로젝트 골격 만들기 (경로를 전달하거나, 기존 프로젝트 재설정에는 --override 사용)
elevenlabs agents init [path] [--override]
...
elevenlabs agents는 두 종류의 명령어를 포함하고 있으며, 어떤 것을 사용 중인지 아는 것이 도움이 됩니다:
| 워크플로우 명령어 (Workflow commands) | API 명령어 (API commands) | |
|---|---|---|
| 무엇을 | init, add, status, push, pull, test, templates, widget embed | create, get, list, update, delete, duplicate, run_tests, 그리고 branches, tools, tests, conversations 같은 하위 그룹 |
| ... |
API 명령어들이 기본 이름(primitive names)을 소유하므로, 워크플로우는 API가 가지고 있지 않은 동사만 추가합니다. 알아두면 좋은 두 가지 결과가 있습니다:
agents list는 워크스페이스 내 API 에이전트 목록입니다. 로컬에서 구성된 항목의 경우, agents status를 사용하십시오.agents delete --agent-id <id>는 원격으로 삭제합니다(API 명령어). 이는 로컬 구성 파일이나 해당 agents.json 항목을 제거하지 않으므로, 사용자가 직접 삭제해야 합니다.v0에서 마이그레이션하기 (@elevenlabs/cli): v0의 agents list는 로컬 설정을 보여주었고, agents delete <id>는 위치 인자(positional)를 사용하며 로컬에서 정리했습니다. v1에서는 두 이름 모두 API 표면(API surface)에 속합니다. 로컬 뷰에는 agents status를 사용하고, 삭제에는 --agent-id를 사용하세요. 또한, agents widget가 API 하위 그룹이 되었기 때문에 v0의 agents widget <id>는 이제 agents widget embed <id>로 변경되었습니다.
에이전트가 참조하는 웹훅 및 클라이언트 도구를 관리합니다. 도구는 tools.json에 추적되며, 설정은 tool_configs/ 아래에 있습니다.
# 웹훅 또는 클라이언트 도구를 생성하고 업로드한 다음 tools.json에 등록합니다
elevenlabs tools add <name> [--type webhook|client] [--config-path <path>]
...
에이전트 테스트를 관리하며, 설정은 test_configs/ 아래의 tests.json에 추적됩니다. 이를 에이전트의 platform_settings.testing.attached_tests에 연결하고 elevenlabs agents test <agent_id>로 실행합니다.
# 템플릿에서 테스트를 생성하고, 업로드한 다음 tests.json에 등록합니다
elevenlabs tests add <name> [--template basic-llm|tool|conversation-flow|customer-service]
elevenlabs tests templates list
...
tests push는 또한 추적되지 않은(untracked) 설정을 **자동으로 발견(auto-discovers)**합니다. 이는 --config-dir을 재귀적으로 스캔하여 테스트처럼 보이는 .json 파일(chat_history 배열 또는 success_condition 문자열)을 찾고, 푸시하기 전에 tests.json에 등록하므로, 인덱스를 수동으로 편집할 필요 없이 설정을 넣고 푸시할 수 있습니다.
agents add를 위한 사전 구축된 시작 구성입니다. elevenlabs agents templates list로 목록을 확인할 수 있으며 ( agents templates show <template>로 하나씩 검사할 수 있습니다):
| 템플릿 | 설명 |
|---|---|
default | 사용 가능한 모든 필드와 합리적인 기본값으로 구성된 완전한 설정 |
| ... |
요청이 라우팅되는 지역을 선택합니다. 이 설정은 ~/.elevenlabs/config.json에 저장되며 모든 명령어에 적용됩니다:
elevenlabs residency # 현재 리전 및 기본 URL 표시
elevenlabs residency eu-residency # 리전 전환
| 리전 | 기본 URL |
|---|---|
global (기본값) | https://api.elevenlabs.io |
| ... |
필요에 따라 일회성 오버라이드가 필요한 경우, --base-url과 ELEVENLABS_BASE_URL이 우선권을 가집니다. 또한 리전은 agents widget에서 방출되는 server-location 속성을 설정합니다.
프로젝트에 ElevenLabs UI 컴포넌트를 설치하세요 (shadcn에 위임되므로 Node.js/npm이 필요합니다):
elevenlabs components add # 모든 컴포넌트
elevenlabs components add conversation-bar
모든 API 리소스는 서브커맨드 형태로 나타납니다 (예: elevenlabs <리소스> <메서드>). 사용 가능한 메서드를 보려면 elevenlabs <리소스> --help를 실행하세요.
요청 매개변수는 플래그 또는 JSON 형태로 제공합니다:
elevenlabs <리소스> <메서드> --json '{"key": "value"}'
전체 명령어 참조는 reference.md를 참조하세요.
이 플래그들은 모든 작업에서 사용할 수 있습니다:
| 플래그 | 설명 |
|---|---|
--dry-run | 요청을 로컬에서 유효성 검사하고 전송하지 않고 HTTP 요청을 출력합니다. |
| ... |
| 변수 | 설명 |
|---|---|
ELEVENLABS_BASE_URL | API 기본 URL을 오버라이드합니다. |
| ... |
표준 환경 변수(HTTPS_PROXY / HTTP_PROXY / NO_PROXY / SSL_CERT_FILE)도 지원됩니다.
대부분의 elevenlabs 트래픽은 AI 에이전트에서 발생합니다. 두 가지 선택적 입력(optional inputs)은 에이전트가 자신이 무엇을 하고 있고, 무엇을 할 수 없는지 말할 수 있게 해주며, 이것이 다음에 어떤 명령어를 구축해야 하는지 알려줍니다. 둘 다 옵트인(opt-in) 방식이며, 이들이 없어도 CLI는 동일하게 작동합니다.
--intent — 이 명령어가 실행되는 이유. X-Agent-Intent 요청 헤더로 전송됩니다.
elevenlabs voices search --intent "pick a narrator voice for an audiobook"
플래그(flag)가 유일한 입력값입니다. 전체 작업에 걸쳐 의도를 설정하는 환경 변수는 없습니다. 명령마다 새로운 문장을 사용하는 것은 의도적입니다. 순서대로 읽어보면, 일련의 명령어들이 호출자가 어떤 과정을 거쳤는지 보여주는데, 이는 단 하나의 작업 전반 문자열로는 불가능합니다.
거부된 값(아래 참조)은 stderr에서 경고를 보내지만 헤더는 전송하지 않으며, 명령어는 여전히 실행됩니다. 텔레메트리(telemetry)가 요청 실패의 원인이 되어서는 안 됩니다.
elevenlabs feedback missing-capability — CLI가 수행할 수 없는 무언가가 필요했을 때 사용합니다. 여기에 첨부할 요청이 없기 때문에 자체 명령어를 갖습니다:
elevenlabs feedback missing-capability \
"no way to batch-render a script to separate files per speaker"
데이터가 아닌 *목표(goal)*를 설명하십시오. 리소스 ID(agent_01jz…)와 프로젝트 상대 경로는 괜찮지만, 이름, 고객 콘텐츠, 분석 저장소에 넣고 싶지 않은 모든 것은 안 됩니다.