Metadata-Version: 2.5
Name: sarvam-voice-agents-cli
Version: 1.0.1
Summary: Build, test, deploy and run Sarvam voice agents from the terminal
Author-email: Sarvam <sarvam@sarvam.ai>
Requires-Python: >=3.11
Requires-Dist: click>=8.1
Requires-Dist: httpx>=0.28
Requires-Dist: mcp<3,>=2
Description-Content-Type: text/markdown

# 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](https://agents.sarvam.ai) to confirm your workspace is set up.

## Installation

The CLI needs Python 3.11 or newer.

Install it with [pipx](https://pipx.pypa.io) so it gets its own environment:

```bash
pipx install sarvam-voice-agents-cli
```

Or with uv:

```bash
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:

```bash
sarvam --version
```

## Get started

**1. Log in**

```bash
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**

```bash
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.

```bash
sarvam chat <agent-id>
```

Send a few turns, then exit:

```bash
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.

```bash
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:

```bash
sarvam agents pull <agent-id> --version 3
```

To create an agent, pass `--name` and leave off `--agent-id`.

```bash
sarvam agents push agent.json --name "Support bot"
```

### Add knowledge base

```bash
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

```bash
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:

```bash
sarvam login --email bot@yourcompany.com
sarvam export-session
```

Store that output as the `SARVAM_SESSION_TOKEN` secret.

In GitHub Actions:

```yaml
- 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](#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`:

```markdown
## 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](https://docs.sarvam.ai/voice-agents/mcp) 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>`.
