Every Sarvam AI model on your terminal — translate, speak, transcribe, chat, and extract documents in 22 Indian languages, with a local history that compounds
Sarvam AI's official SDKs and MCP server are great for code, but nothing offers offline capability: no local history of translations, TTS generations, transcriptions, or chat threads. sarvam-pp-cli adds a local SQLite store, voice auditioning, conversation resume, batch job retry/report, pronunciation spot-checks, subtitle export, and a doc-ai extraction schema library — all with --json, --dry-run, and typed exit codes for agents and scripts.
Created by @SomSamantray (Som Samantray).
Contributors: @cathrynlavery (Cathryn Lavery).
Authentication
Authentication uses the Sarvam AI API subscription key (sk_ format). Set it with export SARVAM_API_KEY=sk_... or sarvam-pp-cli auth set-token. The key goes in the api-subscription-key header (or Authorization: Bearer). Note: an invalid key returns HTTP 403 with invalid_api_key_error, not 401 — treat 403 as the auth-failure signal. The separate Voice Agents platform (apps.sarvam.ai) uses a different X-API-Key system and is out of scope for this CLI.
Quick Start
# Verify the CLI is installed and configured
sarvam-pp-cli doctor --dry-run
# First translation — the core workflow
sarvam-pp-cli translate --input "Hello, how are you?" --source-language-code en-IN --target-language-code hi-IN
# Generate speech audio
sarvam-pp-cli text-to-speech text-to-speech --text "नमस्ते, स्वागत है" --language-code hi-IN --speaker shubh
# Ask the multilingual chat model
sarvam-pp-cli chat --messages '[{"role":"user","content":"What is Sarvam AI?"}]' --model sarvam-105b
# Search past work offline
sarvam-pp-cli search "नमस्ते" --json
Unique Features
These capabilities aren't available in any other tool for this API.
Speech workflow
-
voices preview — Generate one sample sentence across every TTS speaker and hear them all side by side
Use when choosing a TTS voice for a new language or prompt set without burning manual API calls
sarvam-pp-cli voices preview --lang hi-IN --sample "नमस्ते, स्वागत है" --speakers shubh,ritu,priya --output ./voices
-
pron-check — Verify a term's TTS pronunciation via a speech round-trip (TTS then STT)
Use to confirm a pronunciation dictionary edit took effect before shipping IVR prompts
sarvam-pp-cli pron-check "SarvamPay" --lang hi-IN
Local state that compounds
-
chat resume — Continue a past chat thread from local history with full context
Use to continue an assistant session without losing context. New chats save the request messages and reply in your local SQLite database; older response-only records can resume from the last reply but cannot recover earlier prompts. This command sends a new paid chat request.
sarvam-pp-cli chat resume 20260814_2d09e061 "what was our conclusion?"
Completed text-only streamed chats can also be resumed. JSON output includes structured results.id, results.choices, and results.usage, plus the full SSE response in results.stream. Only the first text choice is saved for resume. Incomplete streams and streamed tool calls are not saved because their full context cannot be reconstructed safely. Successful text-to-speech requests save their request text in local history. Audio data is not copied into SQLite.
-
subs — Emit .srt/.vtt subtitles from timestamped transcriptions in local history
Use to turn a timestamped transcription into subtitles without a throwaway script. Saved subtitles are private to your local account by default.
sarvam-pp-cli subs --from last --format srt --output subtitles.srt
Job orchestration
-
stt-job retry — Re-run only the failed files of a batch STT job with one command
Use when a batch job partially fails and you need to reprocess just the failures
sarvam-pp-cli stt-job retry 20260707_9f1c2b3a-4d5e-6f70-8a9b-c0d1e2f3a4b5 --failed-only --dir ./audio/
Retry checks every pending input file before creating a replacement job. It saves progress in private local state, scoped to the selected client profile when one is active, so a rerun resumes the same job and does not require files already uploaded. After a confirmed start, rerunning reports the existing job. If creation succeeded but saving its ID failed, or if the start request's outcome is unknown, check the replacement job with Sarvam and reconcile the checkpoint shown in the error before rerunning.
-
stt-job report — Per-file digest of a batch STT job with typed exit codes for cron alerting
Use in cron to alert when a batch transcription job degrades
sarvam-pp-cli stt-job report 20260707_9f1c2b3a-4d5e-6f70-8a9b-c0d1e2f3a4b5 --json
Document intelligence
-
docai schema list — Save, list, and diff doc-ai extraction schemas locally
Use to version extraction schemas so schema changes never silently break extraction runs
sarvam-pp-cli docai schema list
-
docai batch — Run a saved extraction schema over a folder of documents with job pacing
Use for weekly batch document extraction (KYC, invoices) without writing orchestration code
sarvam-pp-cli docai batch --schema invoice-v1 --dir ./docs/ --out ./results/
Recipes
Translate a support reply
sarvam-pp-cli translate --input "Your EMI of Rs. 3000 is pending" --source-language-code en-IN --target-language-code hi-IN --mode formal
Translate a single message with formal tone for customer communications
Audition voices for a new prompt set
sarvam-pp-cli voices preview --lang hi-IN --sample "नमस्ते, स्वागत है" --speakers shubh,ritu,priya
Hear 3 voices on the same sample before committing to a speaker
Subtitle a promo video
sarvam-pp-cli subs --from last --format srt --output subtitles.srt
Turn the last timestamped transcription into SRT subtitles
Reprocess failed batch files
sarvam-pp-cli stt-job retry 20260707_9f1c2b3a-4d5e-6f70-8a9b-c0d1e2f3a4b5 --failed-only --dir ./audio/
Re-run only the files that failed in a batch transcription job
Check a pronunciation dictionary
sarvam-pp-cli pron-check "SarvamPay" --lang hi-IN --dict p_5cb7faa6
Verify a custom pronunciation actually changed how the term sounds
Extract fields from a folder of documents
sarvam-pp-cli docai batch --schema invoice-v1 --dir ./docs/ --out ./results/
Run a saved extraction schema over every document with pacing
Continue a past chat session
sarvam-pp-cli chat resume 20260814_2d09e061 "what was our conclusion?"
Pick up an assistant conversation where it left off, with full context
Usage
Run sarvam-pp-cli --help for the full command reference and flag list.
For export --output, the parent directory must be writable. The CLI writes an
owner-only temporary file there and replaces the destination after the export
completes, so a failed request leaves the previous file intact.
Paths & environment variables
This CLI separates local files into four path kinds:
| Kind | Contents |
|---|
config | User-editable settings such as config.toml and saved profiles |
data | Durable local data: credentials.toml, data.db, cookies, browser-session proof files, and other auth sidecars |
state | Runtime state such as persisted queries, jobs, and teach.log |
cache | Regenerable HTTP/cache files |
Each kind resolves independently. The ladder is:
- Per-kind env var:
SARVAM_CONFIG_DIR, SARVAM_DATA_DIR, SARVAM_STATE_DIR, or SARVAM_CACHE_DIR
--home <dir> for this invocation
SARVAM_HOME for a flat relocated root
- XDG env vars:
XDG_CONFIG_HOME, XDG_DATA_HOME, XDG_STATE_HOME, XDG_CACHE_HOME
- Platform defaults matching existing installs
For containers and agent sandboxes, prefer a single relocated root:
export SARVAM_HOME=/srv/sarvam
sarvam-pp-cli doctor
Under SARVAM_HOME=/srv/sarvam, the four dirs resolve to /srv/sarvam/config, /srv/sarvam/data, /srv/sarvam/state, and /srv/sarvam/cache.
MCP servers do not receive CLI flags from the host. Put relocation in the host env block:
{
"mcpServers": {
"sarvam": {
"command": "sarvam-pp-mcp",
"env": {
"SARVAM_HOME": "/srv/sarvam"
}
}
}
}
Precedence matters in fleets: an ambient per-kind variable such as SARVAM_DATA_DIR overrides an explicit --home for that kind. Use SARVAM_HOME or the per-kind variables for durable fleet relocation; treat --home as the weaker per-invocation lever.
Relocation is one-way. Unsetting SARVAM_HOME does not move files back to platform defaults, and doctor cannot find credentials left under a former root. Move the files manually before unsetting relocation variables.
Existing installs keep working because the platform-default rung matches the legacy layout. On the first auth write, stored secrets leave config.toml and are consolidated into credentials.toml under the data directory. Run sarvam-pp-cli doctor --fail-on warn to check path and credential-location warnings in automation.
Commands
chat
Manage chat
sarvam-pp-cli chat - Creates a model response for the given chat conversation. Serves sarvam-105b and sarvam-105b-conversations models. Supports streaming via server-sent events, tool calling, and structured outputs.
doc-ai
Manage doc ai
sarvam-pp-cli doc-ai digitise - Creates and starts a digitisation job from files or pre-uploaded handles. Converts documents to machine-readable text with layout awareness. Runs asynchronously; poll status until terminal.
sarvam-pp-cli doc-ai download-url - Returns a presigned URL to download the output of a completed doc-ai job.
sarvam-pp-cli doc-ai extract - Creates and starts an extract job from files or pre-uploaded handles. Extract pulls structured fields out of documents according to a schema. Exactly one of file and upload_ids must be provided; exactly one of schema and config_id is required. Runs asynchronously.
sarvam-pp-cli doc-ai results - Fetches the results of a completed doc-ai job, including extracted fields and annotations with confidence scores.
sarvam-pp-cli doc-ai status - Polls the status of a doc-ai job until a terminal status (completed, partially_completed, failed, rejected).
sarvam-pp-cli doc-ai upload - Creates a presigned URL to upload a document for doc-ai processing.
models
Manage models
sarvam-pp-cli models - Lists the model IDs this deployment currently serves. A model is only served where its backend is configured, so the list is environment-specific — fetch it rather than hardcoding IDs.
speech-to-text
Manage speech to text
sarvam-pp-cli speech-to-text speech-to-text - Transcribes speech to text in multiple Indian languages and English. Accepts an audio file via multipart form-data. Supports transcribe, translate, verbatim, translit, and codemix modes.
sarvam-pp-cli speech-to-text stt-job-download - Returns presigned download URLs for the output files of a completed batch speech-to-text job.
sarvam-pp-cli speech-to-text stt-job-initiate - Creates a new speech-to-text bulk job and returns a job UUID and storage details for processing multiple audio files.
sarvam-pp-cli speech-to-text stt-job-start - Starts processing a speech-to-text bulk job after all audio files have been uploaded.
sarvam-pp-cli speech-to-text stt-job-status - Returns the status of a batch speech-to-text job including per-file details and download information.
sarvam-pp-cli speech-to-text stt-job-upload - Generates presigned upload URLs for audio files that will be processed in a speech-to-text bulk job.
text-lid
Manage text lid
sarvam-pp-cli text-lid - Identifies the language (e.g. hi-IN) and script (e.g. Devanagari) of the input text, supporting 10+ Indian languages and English.
text-to-speech
Manage text to speech
sarvam-pp-cli text-to-speech create-pronunciation-dictionary - Uploads a .json file to create a new pronunciation dictionary. Only supported by bulbul:v3. The returned dictionary_id can be passed as dict_id in text-to-speech requests.
sarvam-pp-cli text-to-speech delete-pronunciation-dictionary - Deletes a pronunciation dictionary by ID.
sarvam-pp-cli text-to-speech get-pronunciation-dictionary - Fetches a single pronunciation dictionary by ID.
sarvam-pp-cli text-to-speech list-pronunciation-dictionaries - Lists all pronunciation dictionaries for the user. Dictionaries define custom word pronunciations used by bulbul:v3 TTS.
sarvam-pp-cli text-to-speech stream - Converts the input text into a streamed spoken audio response using the specified output codec (e.g. MP3). Returns binary audio.
sarvam-pp-cli text-to-speech text-to-speech - Converts text into spoken audio. The output is a base64-encoded audio string (WAV by default) that must be decoded before use. Supports bulbul:v2 and bulbul:v3 models with 30+ voices.
sarvam-pp-cli text-to-speech update-pronunciation-dictionary - Updates an existing pronunciation dictionary with a new JSON file.
translate
Manage translate
sarvam-pp-cli translate - Converts text from one language to another while preserving meaning. Supports 22 Indic languages plus English.
transliterate
Manage transliterate
sarvam-pp-cli transliterate - Transliterates text from one script to another (e.g. Devanagari to Latin) while keeping the same language and pronunciation.
Self-learning loop
This CLI caches per-question discovery so repeat queries skip the walk and structurally similar queries get answered via entity substitution. The loop also self-captures: every invocation is journaled locally, and failed-flag corrections plus fresh teaches surface as candidates on the next recall for confirm/reject judgment. Agents call recall before discovery and fire teach & after answering. See the ## Automatic learning section in SKILL.md for the full protocol.
sarvam-pp-cli recall <query> - Look up cached resources for a query before running discovery
sarvam-pp-cli teach - Record a query -> resource mapping (silent on success, safe to background with &)
sarvam-pp-cli learnings list - Inspect taught rows
sarvam-pp-cli learnings forget <query> - Undo a teach
sarvam-pp-cli learnings candidates - List auto-captured candidates awaiting confirm/reject
sarvam-pp-cli learnings stats - Local loop metrics: recall hit rate, teach-to-reuse, playbook resolution, candidate counts
sarvam-pp-cli teach-pattern - Install a query/resource template up front
sarvam-pp-cli teach-lookup - Add an entity mapping (e.g. country code, team alias) for pattern substitution
Pass --no-learn or set SARVAM_NO_LEARN=true to disable the loop for deterministic flows.
The local store's schema version stamp is one-way: once this version of sarvam-pp-cli opens the database, older binaries refuse it with a version error — upgrade the binary rather than downgrading.
Output Formats
# Human-readable table (default in terminal, JSON when piped)
sarvam-pp-cli models
# JSON for scripting and agents
sarvam-pp-cli models --json
# Filter to specific fields
sarvam-pp-cli models --json --select created,id,object
# Dry run — show the request without sending
sarvam-pp-cli models --dry-run
# Agent mode — JSON + compact + no prompts in one flag
sarvam-pp-cli models --agent
Agent Usage
This CLI is designed for AI agent consumption:
- Non-interactive - never prompts, every input is a flag
- Pipeable -
--json output to stdout, errors to stderr
- Filterable -
--select <field>[,<field>...] returns only fields you need
- Previewable -
--dry-run shows the request without sending
- Explicit retries - add
--idempotent to create retries and add --ignore-missing to delete retries when a no-op success is acceptable
- Confirmable -
--yes for explicit confirmation of destructive actions
- Piped input - write commands can accept structured input when their help lists
--stdin
- Offline-friendly - sync/search commands can use the local SQLite store when available
- Agent-safe by default - no colors or formatting unless
--human-friendly is set
Exit codes: 0 success, 2 usage error, 3 not found, 4 auth error, 5 API error, 7 rate limited, 10 config error.
Health Check
sarvam-pp-cli doctor
Verifies configuration, credentials, and connectivity to the API.
Configuration
Run sarvam-pp-cli doctor to see the resolved config, data, state, and cache directories. The platform-default config path is ~/.config/sarvam-ai-pp-cli/config.toml; --home, SARVAM_HOME, and per-kind env vars can relocate it.
Static request headers can be configured under headers; per-command header overrides take precedence.
Environment variables:
| Name | Kind | Required | Description |
|---|
SARVAM_API_KEY | per_call | Yes | Set to your API credential. |
agentcookie (optional)
If you use agentcookie to sync secrets across machines, this CLI auto-adopts agentcookie-managed credentials with no extra setup. When the daemon writes to this CLI's config, sarvam-pp-cli doctor reports agentcookie: detected and auth-status labels the source as agentcookie. Skip this section if you don't use agentcookie - the CLI works the same as any other.
Troubleshooting
Authentication errors (exit code 4)
- Run
sarvam-pp-cli doctor to check credentials
- Verify the environment variable is set:
echo $SARVAM_API_KEY
Not found errors (exit code 3)
- Check the resource ID is correct
- Run the
list command to see available items
API-specific
- HTTP 403 invalid_api_key_error — The key is invalid or expired — not a 401. Re-run
sarvam-pp-cli auth set-token with a fresh key from the Sarvam dashboard.
- TTS pitch/loudness rejected on bulbul:v3 — pitch and loudness are bulbul:v2-only. Use
--model bulbul:v2 or drop those flags.
- Chat returns content: null with only reasoning — Set
--max-tokens explicitly — hidden reasoning can consume the token budget before content.
- Translate rejects >1000 chars — mayura:v1 caps at 1000 chars. Use
--model sarvam-translate:v1 for up to 2000 chars.
- Rate limit 429 — Sarvam uses token-bucket limits (translate 60/min, TTS 60/min, chat 40/min on sarvam-105b). Add pacing or retry with backoff.
Sources & Inspiration
This CLI was built by studying these projects and resources:
Generated by CLI Printing Press