Skip to main content

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 json forces JSON.
  • Exit codes name the failure. See Exit codes.
  • sarvam --help works before login and offline. sarvam <group> --help and sarvam tools list what this workspace can run.
  • A command that changes something asks for confirmation. -y answers yes. push can take --dry-run first.
  • 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)

Source distribution for sarvam-voice-agents-cli 1.0.0
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)

Table of built distributions (wheels) for sarvam-voice-agents-cli 1.0.0
File Interpreter ABI Platform Actions
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.

Release history Release notifications | RSS feed

This release

1.0.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page