elv

An agent-first ElevenLabs CLI. One JSON envelope per command, with the published REST API behind it.

Independent project; not affiliated with or endorsed by ElevenLabs.

Why this exists

Agents need predictable inputs, small outputs, and a way to discover unfamiliar API operations without writing a new wrapper each time.

The vendored October 7, 2026 OpenAPI document contains 407 operations; elv compiles 406 of them and deliberately skips one deprecated signed-URL route whose replacement is available. Each command returns one JSON envelope and an exit code an agent can branch on before parsing the result.

What is this?

Speech, transcription, dialogue, music, sound effects, image/video generation, assets, dubbing, voices, agents, and workspace operations share one runner. Named WebSocket clients handle realtime sessions. API coverage distinguishes the published contract from live provider verification.

Commands are non-interactive. Audio and large payloads go to disk, with paths in files[]; stdout contains one JSON envelope. Humans can use it too, but the design target is an agent branching on exit codes and reading small results.

If you're an agent reading this

Route yourself by what your human actually asked for.

| Your situation | Where to go | | --- | --- | | They sent you to figure out what this is | The What is this? section above, then AGENTS.md for the contract | | They want you to install and set this up on this machine | docs/agent-setup.md, start to finish | | They want you to actually use it | AGENTS.md for the protocol, and the shipped skill at skills/elv/SKILL.md |

Features

The generic runner, elv call <operation_id> --json '{...}', can invoke all 406 operations compiled from the pinned OpenAPI document. Aliases build workflow inputs. http, ws, and wait provide raw REST, scripted WebSockets, and polling; known routes inherit registry or protocol metadata.

Discovery commands expose operation inputs and spec provenance. Destructive and outbound operations require --yes; configured credit ceilings block unbounded generation before network access. --dry-run validates locally without spending credits.

Install

Requires Node 22 or newer. npm installs the elv command globally.

npm install -g eleven-agent-cli
elv config doctor

To build and link from source:

git clone https://github.com/treygoff24/elv.git
cd elv
npm ci
npm run build
npm link            # gives you a global `elv`
elv config doctor

Or skip the link and invoke the built file directly:

node dist/cli.js config doctor

Fresh-machine installation is covered in docs/agent-setup.md. It includes configuration, verification, and troubleshooting.

Quickstart

# 1. Point elv at your account (sent as the xi-api-key header; never as a CLI arg).
export ELEVENLABS_API_KEY=your_key_here

# 2. Confirm the environment is healthy.
elv config doctor

# 3. Find an operation.
elv ops search "text to speech"

# 4. Preview a call without spending credits.
elv tts --voice-id JBFqnCBsd6RMkjVDRZzb --text "Hello from elv." \
  --model eleven_flash_v2_5 --dry-run

# 5. Run it for real.
elv tts --voice-id JBFqnCBsd6RMkjVDRZzb --text "Hello from elv." \
  --model eleven_flash_v2_5 --out out.mp3

Usage

Discovery

Start with the bounded machine-readable service map, then search the vendored OpenAPI registry and copy a runnable example:

elv capabilities
elv ops get compose_detailed_stream
elv ops search "text to speech"
elv ops get text_to_speech_full
elv ops schema text_to_speech_full --example
elv spec status

--example prints a runnable elv call skeleton. elv spec diff compiles the current provider document and reports drift without writing the cache; elv spec update installs the validated registry transactionally. elv <command> --help lists that command's own flags.

Aliases

The sixteen aliases build workflow inputs for the same runner as call.

| Alias | Purpose | | --- | --- | | tts | Text-to-speech (voice id or name, text or file, optional stream and timestamps) | | stt | Transcription, transcript editing, configured-webhook delivery, and env-sourced single-use tokens | | music | Music generation, detailed SSE audio and metadata, and Music Finetunes | | sfx | Text-to-sound-effects generation | | voice-change | Speech-to-speech voice conversion | | voice-isolate | Background-noise removal | | dubbing | Dubbing create, get, and audio workflows | | dubbing-project | Dubbing v2 source and target transcript editing, including atomic bulk updates | | voices | Voice list/filter, accents, search, get, clone, and confirmed replication | | agents | Lifecycle, Procedures, tests, deployment history, merge proposals, tickets, and RAG diagnostics | | models | List the models visible to the authenticated account from /v1/models | | history | Generated-audio history list, audio, delete | | usage | Subscription balance or date-range character stats | | workspace | List members and create or list service accounts | | flows | Image, video, speech, and template-run generation, with optional waiting | | assets | Reusable media upload, list, get, and delete workflows |

elv tts --voice-id JBFqnCBsd6RMkjVDRZzb --text "Hello from elv." --out ./out
elv voices list
elv usage --from 2026-06-01 --to 2026-06-25
elv dubbing get --id abc123
elv agents tests create --json-file test.json
elv agents procedures list --agent-id AGENT_ID --branch-id BRANCH_ID
elv voices accents --language en
elv workspace members list
elv music finetunes list --limit 10

agents simulate remains as a compatibility alias but calls an operation ElevenLabs marks deprecated. New automation should use agents tests create followed by agents tests run.

Published template and agent review workflows use the same runner:

elv flows templates list --search narration
elv flows templates get --template-id TEMPLATE_ID
elv flows templates runs create --template-id TEMPLATE_ID \
  --json-file inputs.json --wait --dry-run
elv agents merge-proposals list --agent-id AGENT_ID
elv agents deployments list --agent-id AGENT_ID
elv agents test-runs cancel --invocation-id INVOCATION_ID --dry-run
elv agents tickets list --agent-id AGENT_ID --priority urgent high --sort-by priority

Template-run bodies include inputs, with port values discovered from the template. Runs poll status until completed or failed; timeout hints retain both template and run IDs. A configured credit ceiling blocks unbounded template generation. Proposal merge, ticket merge, and test invocation cancellation require --yes after preview. Proposal merge defaults to archiving the source branch; use JSON {"archive_source_branch":false} to retain it.

TTS accepts --json/--json-file, --voice-settings/--voice-settings-file, and individual stability, similarity, style, speed, and speaker boost flags. Flags override settings objects, which override body settings. Explicit models override profile defaults; omitted fields leave API defaults in effect.

--out narration.wav --timestamps names audio and its sidecar. Completed files may report measured duration, sample rate, bit rate, channels, and codec. Partial or unsupported audio omits unavailable measurements; returned bytes may differ from requested formats.

Music Finetunes training uses repeatable --file inputs, subject to provider entitlement, charges, and ownership/copyright rules:

elv music finetunes create --name "Live Jazz" --primary-genre jazz \
  --file take-1.wav --file take-2.wav --model music_v2 --dry-run
elv music --prompt "A warm jazz trio" --finetune-id FINETUNE_ID --out track.mp3
elv music finetunes update --finetune-id FINETUNE_ID --json '{"visibility":"workspace"}'
elv music finetunes delete --finetune-id FINETUNE_ID --yes

For asynchronous STT, configure a workspace webhook first, then pass boolean --webhook and optionally --webhook-id. A single-use Scribe token is read from an environment variable so its value never enters argv:

elv stt --file note.m4a --model scribe_v2 --webhook --webhook-id WEBHOOK_ID
elv stt --file note.m4a --model scribe_v2 --token-env SCRIBE_TOKEN

The generic runner

Use elv call <operation_id> for operations without aliases. Generic --json takes buckets (path, query, body); aliases take body JSON directly. --path key=value supplies path parameters. Inspect shapes with elv ops schema <operation_id> --example.

# Discover a generation model's input contract before spending credits.
elv ops schema create_image_generation --example
elv flows image create --json-file image-request.json --dry-run
elv flows image create --json-file image-request.json --wait
elv assets upload --file reference.png
elv agents tickets list --agent-id AGENT --status open
elv agents conversations summary --conversation-id CONVERSATION

Flows generation costs depend on the selected model and options. A configured credit ceiling blocks these operations when no defensible estimate is available, even with --yes. Completed generations and Assets carry signed content URLs: full responses go to private sensitive: true files, while redacted IDs, status, and cursors remain available for polling and pagination.

elv call text_to_speech_full \
  --json '{"path":{"voice_id":"JBFqnCBsd6RMkjVDRZzb"},"body":{"text":"Hello.","model_id":"eleven_v3"}}' \
  --out ./out

List aliases and call/http accept --limit <n>, --save-json <path>, and --all (requires --save-json or --out). Large pages spill to disk while retaining the next-page command inline. --fields <csv> projects list aliases to smaller results:

elv voices list --fields voice_id,name
elv view response.json --path 'voices[].name' --limit 10

Escape hatches

When an endpoint is missing from the registry, still in beta, or needs a raw path, drop down to the primitives.

# Arbitrary REST against the configured base URL.
elv http GET /v1/user
elv http POST /v1/text-to-speech/JBFqnCBsd6RMkjVDRZzb \
  --body-json '{"text":"Hi","model_id":"eleven_v3"}' --out ./out

# Scripted WebSocket session (catalog name, configured-host path, or raw wss:// URL).
elv ws --list
elv ws tts-realtime --query voice_id=VOICE --query model_id=eleven_flash_v2_5 \
  --send script.ndjson --out ./session

# Realtime STT accepts send_audio_file actions and published query fields.
elv ws stt-realtime --query entity_detection=true \
  --send transcribe.ndjson --out ./session --dry-run

# Conversation monitoring is receive-only without --send; outbound controls require --yes.
elv ws convai-monitor --query conversation_id=CONVERSATION_ID --out ./monitor

# Poll an operation until a status field resolves.
elv wait --operation get_dubbed_metadata \
  --json '{"path":{"dubbing_id":"abc"}}' \
  --status-path '$.data.status' \
  --success 'dubbed' --failure 'failed' \
  --interval-ms 2000 --timeout-ms 600000

The catalog covers TTS and dialogue (single and multiple contexts), STT, agents, and conversation monitoring. Dialogue defaults to eleven_v4_turbo with one voice; eleven_v4 accepts up to ten. Multi-context audio is saved separately. Realtime protocol details cover initialization, model rules, and terminal events.

Use --token-env TOKEN_VARIABLE for single-use authentication against the configured API host, or --url-env URL_VARIABLE for signed URLs on any host. Neither secret enters argv. Raw URLs do not receive profile credentials. STT scripts wrap PCM bytes in JSON:

{"type":"send_audio_file","path":"audio.pcm","sample_rate":16000,"commit":true}

send_binary_file is reserved for unknown raw protocols. Agent audio without a known output_format becomes audio.bin with a warning. Peer closes may report close codes and reasons; CLI teardown omits them. Agent queue timeout 4300 adds recovery guidance.

--duplex accepts wrapped NDJSON actions on stdin and emits redacted events synchronously on stderr. Keep draining stderr or the process blocks. Stdout still contains one final envelope. Send protocol flush/end controls and await final events before closing stdin; EOF closes the transport. Dynamic session costs cannot be bounded, so configured ceilings block these sessions. Outbound agent/monitor actions require --yes; monitoring without --send is receive-only.

Music detailed streaming

For non-streaming audio plus composition metadata, use elv call compose_detailed --json-file request.json --out ./song. The CLI splits the multipart response into audio and JSON files. Always use the returned files[].path: existing files are preserved, collisions get distinct names, and credential files receive a .sensitive marker even with an explicit output filename. Multi-file operations require an output directory.

Output uses hard links where supported and exclusive create elsewhere, preserving existing files. The release gate is verified on Linux with Node 22 and 26.

elv music detailed-stream decodes Server-Sent Events into audio and metadata NDJSON files, returning both paths in files[].

elv music detailed-stream --prompt "A tense string quartet" --model music_v2 \
  --timestamps --out ./music-session

If a paid stream becomes malformed after valid data, the error envelope keeps any completed audio and events as partial: true files rather than discarding them.

Configuration and auth

Set ELEVENLABS_API_KEY and elv sends it as the xi-api-key header. Never pass the key as a CLI argument. STT single-use tokens likewise use --token-env ENV_NAME, never the token value. Request credentials are redacted from envelopes and logs. Provider responses that create a token, signed URL, API key, or similar credential are deliberately written to a mode 0600 file instead of returned inline; the envelope marks that file sensitive: true.

export ELEVENLABS_API_KEY=your_key_here
elv config get
elv config doctor

elv config doctor checks local configuration, key presence, registry cache, output-directory access, and Node version. Add --online to check provider reachability and account credits. Key presence alone does not establish successful authentication.

Named profiles select an output directory, model, credit ceiling, endpoint, and key environment variable. Store endpoint and key selection in your trusted user config, or select a trusted file explicitly with ELV_CONFIG. Use --profile <name> or ELV_PROFILE to select a profile.

An implicitly discovered .elv/config.json cannot contain base_url or api_key_env: either field causes the whole file to be refused. Project workflow settings can overlay trusted defaults, and project budgets may lower a trusted ceiling but cannot raise or erase it. Explicit --max-credits and ELV_MAX_CREDITS override those budget limits. See setup and profile rules.

--base-url or ELEVENLABS_BASE_URL overrides the endpoint; ELEVENLABS_API_RESIDENCY (us, eu, in, sg) selects a residency host.

Paths follow the XDG base directories, with the historical home-relative path as the fallback and an ELV_* override always winning:

| What | Override | Default | | ---- | -------- | ------- | | Config | ELV_CONFIG (an exact file) | $XDG_CONFIG_HOME/elv/config.json, else ~/.config/elv/config.json | | Registry cache | ELV_CACHE_DIR | $XDG_CACHE_HOME/elv, else ~/.cache/elv | | Output | --out per command, then ELV_OUTPUT_DIR, then a profile's output_dir | $XDG_DATA_HOME/elv/out, else ~/.local/share/elv/out |

Generated files live in a data directory so cache clearing preserves your audio. Older ~/.cache/elv/out files stay there. Run elv config get to see resolved paths.

Models

elv models list reports account-visible /v1/models results, which can omit service-specific IDs. Alias --model values pass through as strings. A profile model applies only to TTS REST and named TTS WebSockets when none is supplied.

Prefer Flash over deprecated Turbo, scribe_v2 over scribe_v1, and select music_v2_5 explicitly: the Music API schema still defaults to deprecated music_v1. Dialogue WebSockets default to eleven_v4_turbo. Model IDs and deprecations record the October 7 references and account limits.

Safety and budget

Destructive operations (DELETE), outbound calls and messages, cross-residency voice replication, API-key mutation, and member changes all require --yes. Reads are never gated.

elv call delete_voice --path voice_id=VOICE_ID --yes

Credit-consuming calls can be capped before they run. With --max-credits (or ELV_MAX_CREDITS, or a profile default), elv estimates supported operations and fails with exit 5 before touching the network when the estimate exceeds the ceiling. It also fails closed for generation operations and STT or agent WebSocket sessions whose cost cannot be bounded. A raw or non-generation operation with unknown cost reports unknown_unbounded; its ceiling is not a guarantee.

Legacy speech estimates are pre-flight guards; charged-credit response headers are the billing evidence when available. Music generation and v4 speech report music_cost_unknown or v4_cost_unknown and fail closed under ceilings. Published USD prices do not establish universal credit bounds.

stt --transcript-edit INSTRUCTION returns an edited transcript alongside the original. Instructions are limited to 2,000 Unicode characters and exclude entity detection, entity redaction, and multi-channel transcription. Editing adds 30% to base cost with minimum ten-second billing; the CLI reports transcript_edit_cost_unknown and fails closed when a credit ceiling is configured. An edit failure preserves the successful original transcript.

Before dry-run, confirmation, budget checks, or network access, file-emitting commands verify that --out, --save-json, or the configured default output directory is writable; invalid_out_target exits 2 with a replacement-target hint. Speech-to-text likewise fails before network access unless exactly one media source is supplied: stt --file PATH, generic --file file=PATH, body.source_url, or body.cloud_storage_url.

elv tts --voice-id VOICE --text "Long script..." --max-credits 500 --out ./out

--dry-run validates the request and returns a redacted preview without calling the network. It runs before the --yes and budget gates, and the envelope reports would_require_yes, would_exceed_budget, and the budget policy. One caution: do not dry-run a secret-create operation with a real secret value, because input redaction is keyed on field names and may echo a secret passed in an innocuously named body field. The full agent protocol is in AGENTS.md.

elv view refuses to render files marked as sensitive provider responses. Read one directly only when you intend to reveal the credential, then protect or delete it as you would any API key.

The envelope contract

Stdout is always a single JSON object: a SuccessEnvelope or an ErrorEnvelope, both carrying v: 1 and ok: true or ok: false. A success envelope can include data, data_summary, files[], cost, http, warnings, and hints[]. An error envelope carries a normalized error (type, code, message) plus optional retry guidance and hints[] with a suggested next command. Binary and oversized payloads are written to disk and referenced as files[] entries with a path, MIME type, byte count, and sha256. The full type definitions live in src/core/types.ts.

Exit codes

Branch on the exit code before parsing anything.

| Code | Meaning | | --- | --- | | 0 | Success | | 2 | Input or validation (bad parameters, local pre-flight) | | 3 | Auth or permission | | 4 | Confirmation required: add --yes | | 5 | Budget ceiling: raise --max-credits or lower the op cost | | 6 | Out of credits at the provider | | 7 | Transient or retryable error, retries exhausted | | 8 | Provider error (other 4xx/5xx) | | 9 | Not found (404, unknown operation_id) |

Troubleshooting

| Failure | Next step | | --- | --- | | Exit 2, invalid input or output | Inspect elv <command> --help, elv ops schema <id>, or choose a writable --out | | Exit 3, auth or permission | Run elv config doctor --online; check the key's endpoint permissions | | Exit 4, confirmation | Preview with --dry-run, then add --yes when intended | | Exit 5, credit ceiling | Reduce the request or deliberately raise the ceiling; unknown costs remain unbounded | | Source changes have no effect | Rebuild; packed installs also need reinstalling. npm run verify:install reports drift |

Setup troubleshooting covers registry caches, output paths, and installation checks. A successful doctor does not establish access to every endpoint or paid-generation behavior.

Development

Run the repository gate:

npm run gate

scripts/gate.sh runs format check, lint, typecheck, build, tests, and offline smoke, stopping on failure. npm run format applies the formatter; ELV_TEST_MAX_WORKERS=<n> sets the test worker ceiling.

Two checks reach past the source tree. npm run smoke:pack installs an npm pack tarball offline into a throwaway prefix and smokes it, which is what proves dependencies is complete. npm run verify:install compares your build against the globally installed copy and reports the drift; see AGENTS.md for both.

Contributing

Contributions are welcome. See CONTRIBUTING.md for the workflow and conventions, and SECURITY.md for how to report a vulnerability.

License

MIT. See LICENSE.