grdev.elevenlabs-cli 0.3.7

ElevenLabs

ElevenLabs is a command-line tool that turns a Markdown script into AI narration, one audio clip per paragraph, using the ElevenLabs API.

The core idea is a content-addressed cache: each paragraph's audio is keyed by its content and voice settings, not its position. Edit one paragraph — even split it into two — and every other clip is reused from cache, so you never re-pay for narration that didn't change.

Related

• Project page — install and usage
• YouTube — <PENDING>

Documentation

• Spec
• Architecture

Requirements

• .NET SDK 10.0
• An ElevenLabs API key

Install

ElevenLabs is published as a global dotnet tool:

dotnet tool install --global grdev.elevenlabs-cli

Then run it as elevenlabs. For local development from source, use scripts/install-dev-pc.ps1.

Usage

elevenlabs --script .\script.md

Or, from source without installing:

dotnet run --project .\src\ElevenLabs\ElevenLabs.csproj -- --script .\script.md

Options:

Voice configuration (voice id + settings) is read from YAML frontmatter at the top of the script — see the spec.

Two bare-word commands stand alongside the flags:

elevenlabs version   # what this build is: version, commit and build time
elevenlabs skill     # this tool's agent guide, on stdout

Driving it from an agent

The tool carries its own agent guide. Installing it is two commands:

dotnet tool install --global grdev.elevenlabs-cli
elevenlabs skill > ~/.claude/skills/elevenlabs/SKILL.md

elevenlabs skill prints a ready-to-use skill file — the script frontmatter, the two-layer cache, the --dry-run cost preview and the failure modes an agent needs to handle. It is the same file this repository versions at skills/elevenlabs/SKILL.md, embedded in the build so a machine with only the package can still produce it.

Every run is non-interactive, except the first one on a new machine, which writes an empty API-key template and stops — pasting the key in is a step only a human can take.

API key

ElevenLabs reads the ElevenLabs key from, in order:

1. apiKey in the script frontmatter (use for one-offs only).
2. %USERPROFILE%\.grdev.elevenlabs-cli\api-key.json → { "apiKey": "sk_..." } (recommended).

Run elevenlabs once without a key and it writes that file as a template for you to paste into.

Never commit a key in frontmatter if the script lives in a repo.

Output

One MP3 per paragraph, named NN - first five words.mp3, in sequence. Audio is meant to be finalized before editing; sequential numbering makes (re-)placement on a timeline obvious.

Versioning

Versions are computed by Nerdbank.GitVersioning from version.json plus the git height — there is no hardcoded version anywhere. version.json holds the major.minor; the patch is the number of commits since that value last changed, so every commit bumps the patch automatically.

Install the CLI once:

dotnet tool install --global nbgv

Viewing the version

nbgv get-version                    # full summary for HEAD
nbgv get-version -v SimpleVersion   # just x.y.z, for scripts
nbgv get-version -f json            # everything, as JSON

Setting the version

The patch bumps on its own with every commit. To change the major or minor, hand-edit the version field in version.json and commit it — the patch count restarts from there:

"version": "1.3"

Do not run nbgv set-version. It rewrites version.json from scratch and silently drops the publicReleaseRefSpec and cloudBuild settings this repo relies on. Never add a <Version> element to Directory.Build.props or a .csproj either — it would override the computed version.

Releases

A build from release/production is a public release and gets a clean version (1.3.4). Every other branch is a prerelease and gets a commit-id suffix (1.3.4-g1a2b3c4). Pushing to release/production triggers the publish workflow.