Sarvam Voice Agents CLI
The Sarvam Voice Agents CLI brings Sarvam voice agents to your terminal: agents, evals, knowledge bases, telephony, campaigns, analytics and more. Manage agent configuration as code, run evaluations in CI, and give AI coding agents such as Claude Code, Cursor or Codex direct access to your workspace.
The CLI is a thin client. Every command runs on the hosted Sarvam server with your own login, so it can do exactly what your account can do, and nothing more.
Who it's for: engineering teams that work in version control, automate their releases, or build with AI coding agents.
What the CLI does
| Group | What you can do |
|---|---|
agents |
Build, edit, version and talk to agents; configure voicemail, silence nudges, and API tools |
evals |
Define test suites and scenarios, run them, and read the results |
kb |
Create knowledge bases, upload files, and inspect what an agent retrieves |
telephony |
Connect providers, onboard numbers, run inbound deployments, and place test calls |
campaigns |
Create outbound campaigns and upload their cohorts |
experiments |
Split traffic across committed versions of one agent |
integrations |
Connect third-party tool servers and bind them to agents |
secrets |
Manage the workspace secret store (names and ids) |
analytics |
Pull reports and insights, and trace a single interaction |
boards |
Build custom boards: widgets, filters, layouts and schedules |
Run sarvam <group> --help to list that group's commands. The list matches your workspace and shows only the commands your plan includes.
Before you begin
- You will need a Sarvam account with access to Voice Agents. Sign in once at agents.sarvam.ai to confirm your workspace is set up.
Installation
The CLI needs Python 3.11 or newer.
Install it with pipx so it gets its own environment:
pipx install sarvam-voice-agents-cli
Or with uv:
uv tool install sarvam-voice-agents-cli
Plain pip install sarvam-voice-agents-cli also works inside a virtual environment.
The package installs one command, sarvam. Check it:
sarvam --version
Get started
1. Log in
sarvam login
The CLI prints the URL and the device code, then opens your browser. Approve the code and it stores the session. A browser login lasts 24 hours. On a machine without a browser, add --no-open to skip opening one.
2. Verify
sarvam status
sarvam orgs
sarvam agents list
status shows who you are acting as, and until when. orgs lists the orgs and workspaces this login can reach. agents list shows the agents in the current workspace.
Common flows
Talk to an agent
Leave the conversation open. Type /exit or press Ctrl-D to end it.
sarvam chat <agent-id>
Send a few turns, then exit:
sarvam chat <agent-id> -m "Hi" -m "What are your hours?"
--version selects a committed version.
Keep agent configuration in git
pull writes an agent's draft to a JSON file. push applies a file back to that draft.
sarvam agents pull <agent-id> -f agent.json
sarvam agents push agent.json --agent-id <agent-id> --dry-run
sarvam agents push agent.json --agent-id <agent-id> --commit "Tighten the greeting"
Edit agent.json, then push it. Only your edits are sent, so the file from pull changes nothing until you edit it. Set a field to null to remove it. To change a list, send the whole list.
Change the prompt with a flag, not inside agent.json. --prompt-append adds text at the end. --prompt-edits replaces exact phrases from a JSON file. --prompt-scope sets where: global, state, or state:<name>.
--dry-run runs every check and writes nothing. --commit "<message>" commits a version after the write. If a change was not applied, or the config has validation issues, the command exits 2 and does not commit.
Read a committed version:
sarvam agents pull <agent-id> --version 3
To create an agent, pass --name and leave off --agent-id.
sarvam agents push agent.json --name "Support bot"
Add knowledge base
sarvam kb upload <kb-id> faq.md pricing.csv
This uploads local text files, such as Markdown, text, CSV, JSON, and HTML, and waits for each file to be ingested. --wait-seconds defaults to 60.
Run evals
sarvam evals run --kind suite \
--app-id <agent-id> \
--app-version 3 \
--test-suite-id <suite-id> \
--wait
--wait polls until the run finishes. --timeout defaults to 1800 seconds. The command exits 7 when any scenario failed. Ctrl-C stops the wait. The run continues on the server.
Use it in CI
A browser login expires after 24 hours. A pipeline needs a session that renews itself.
On your machine, log in as a user and print the session token:
sarvam login --email bot@yourcompany.com
sarvam export-session
Store that output as the SARVAM_SESSION_TOKEN secret.
In GitHub Actions:
- run: pipx install sarvam-voice-agents-cli
- run: |
sarvam evals run --kind suite \
--app-id "$AGENT_ID" \
--app-version "$VERSION" \
--test-suite-id "$SUITE_ID" \
--wait -o json
env:
SARVAM_SESSION_TOKEN: ${{ secrets.SARVAM_SESSION_TOKEN }}
The step fails with exit code 7 when any scenario failed, so a prompt change that breaks a suite stops the pipeline.
Keep the token secret. An exported session token is the bot user's whole identity while the session lives. Keep it in your CI secret store, never in the repository. Use a dedicated bot user.
Use it from AI coding agents
Claude Code, Cursor, Codex, and Gemini CLI can run sarvam like any other command.
- The result is the only thing on stdout. Notes, progress, and errors go to stderr. A terminal shows a table. Piped output is JSON.
-o jsonforces JSON. - Exit codes name the failure. See Exit codes.
sarvam --helpworks before login and offline.sarvam <group> --helpandsarvam toolslist what this workspace can run.- A command that changes something asks for confirmation.
-yanswers yes.pushcan take--dry-runfirst. - You log in once. The agent uses that session.
Add this to your repository's AGENTS.md or CLAUDE.md:
## Voice agents
Use the `sarvam` CLI to manage our voice agents.
- Pass `-o json` and read the result from stdout.
- Run `sarvam <group> --help` before using a command for the first time.
- Before any change, run it with `--dry-run` and show me the result. Add `-y` only after I approve.
- Exit code 3 means I need to run `sarvam login`. Stop and tell me.
- Never print or ask for secret values.
CLI or MCP. Use the MCP server when your assistant connects to tool servers. Use the CLI when the agent has a shell, in CI, or when you want each step as a command you can review and replay. Both reach the same server and act with the same permissions.
Logging in
| Option | Use it for |
|---|---|
| (none) | Print the URL and device code, then open a browser. Lasts 24 hours. |
--no-open |
Skip opening a browser. The URL and code are still printed. |
--email <address> |
A bot user with a password. Prompts for it, or reads stdin with --password-stdin. Renews itself. |
--session-token <token> |
A token from sarvam export-session. @file or @- reads it. Renews itself. |
--org <id-or-slug>, --workspace <id> |
Scope an --email or --session-token login to one org or workspace |
Sessions
| Command | What it does |
|---|---|
sarvam sessions |
List stored sessions. * marks the one commands use. |
sarvam use <handle> |
Make a session the default |
sarvam logout |
Forget the current session. Pass a handle to forget that one. |
Sessions are stored in ~/.sarvam/. Keep that folder private. Each session stays tied to the org and workspace it logged in to.
Environment variables
| Variable | What it sets |
|---|---|
SARVAM_SESSION_TOKEN |
A session token for non-interactive use, such as CI |
SARVAM_SESSION |
The stored session handle to act as |
SARVAM_ORG, SARVAM_WORKSPACE |
The org and workspace for a SARVAM_SESSION_TOKEN login |
Exit codes
| Code | Meaning |
|---|---|
0 |
Success |
1 |
Another error |
2 |
Bad input, or a change that was not applied |
3 |
Not logged in, the session expired, or more than one session and none chosen |
4 |
Not found |
5 |
Forbidden |
6 |
Conflict |
7 |
The eval run finished with failures |
Errors go to stderr as error [<code>]: <detail>.
Metadata
Release files for sarvam-voice-agents-cli 1.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| sarvam_voice_agents_cli-1.0.0.tar.gz | 34.5 kB | Without provenance | Details for sarvam_voice_agents_cli-1.0.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| sarvam_voice_agents_cli-1.0.0-py3-none-any.whl | Python 3 | none | any | Details for sarvam_voice_agents_cli-1.0.0-py3-none-any.whl |
Total release size: 77.6 kB
Release files / sarvam_voice_agents_cli-1.0.0.tar.gz
| Download URL | sarvam_voice_agents_cli-1.0.0.tar.gz |
|---|---|
| Size | 34.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
93a9437f636eaa5f17f0191ecc8c88c2a1e5e85bbf1ea64ac57a32e0de66e1a2
|
|
BLAKE2b-256 checksum How to use checksums |
efa34522092dea02533a90006869eea5cc33d98761da9646b3a8a4ce7e38870b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.11
|
Release files / sarvam_voice_agents_cli-1.0.0-py3-none-any.whl
| Download URL | sarvam_voice_agents_cli-1.0.0-py3-none-any.whl |
|---|---|
| Size | 43.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
c32a620f5a8fb693cc449d769017ac2e33b774aee7a7cddb59d4da1e3ec2ba6d
|
|
BLAKE2b-256 checksum How to use checksums |
5ae9d9b770bab183ac7444c212ca2ec3e4c5c48c867d447b6fd31e2c84edcb2c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.11
|
Security for sarvam-voice-agents-cli 1.0.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.