# Command line

Sphoro Voice from a terminal: sign in once, then create agents, place calls, read transcripts and tail a live call's events. It is the fastest way to answer "did that work" without writing anything.

## Getting it

> **The CLI is a single binary, provided with your account rather than published to a package manager.** [Ask us](https://voice.sphoro.com/docs/support) for the build for your platform. Everything it does is also on this API, so nothing here is CLI-only — if you would rather not add a binary, the curl on every page of this site does the same things.

## Signing in

**Shell**

```bash
sphoro-voice login              # asks for the key, saves it with 0600 permissions
sphoro-voice whoami             # which account and which scopes
sphoro-voice doctor             # why nothing works
```

`doctor` is the one worth knowing about. It checks the credential, the base URL, the scopes and reachability, and tells you which of them is the problem — which is otherwise a half-hour of guessing between an expired key and a firewall.

## Agents

**Shell**

```bash
sphoro-voice agents list
sphoro-voice agents get agt_9f2c1a7d4b6e803f
sphoro-voice agents create -f agent.json
sphoro-voice agents update agt_9f2c1a7d4b6e803f -f patch.json
sphoro-voice agents delete agt_9f2c1a7d4b6e803f
```

`-f` takes the same JSON body the API takes, so an agent can live in your repository as a file and be applied like configuration. See [agent reference](https://voice.sphoro.com/docs/agents).

## Calls

**Shell**

```bash
sphoro-voice calls start --agent agt_9f2c… --to +919876543210 --var first_name=Priya
sphoro-voice calls list --agent agt_9f2c…
sphoro-voice calls get call_8b21f4c9a07e3d15
sphoro-voice calls transcript call_8b21f4c9a07e3d15
sphoro-voice calls end call_8b21f4c9a07e3d15
```

`--var` repeats, once per [variable](https://voice.sphoro.com/docs/variables). A real call asks for confirmation first unless you pass `-y` — which is deliberate, because the thing on the other end of a typo is somebody's telephone.

## Following a call as it happens

**Shell**

```bash
sphoro-voice events tail call_8b21f4c9a07e3d15
```

One line per event: transcript lines, tool calls, flow moves, keypresses and the ending. This is the single most useful debugging command in the tool — most "why did it do that" questions are answered by watching one call go past.

## Knowledge bases

**Shell**

```bash
sphoro-voice kb list
sphoro-voice kb get kb_1e5ba0d984f7665b
sphoro-voice kb search kb_1e5ba0d984f7665b "what happens if I cancel the day before"
```

`kb search` is how you check what the agent will actually retrieve, before a caller does it for you. See [knowledge base](https://voice.sphoro.com/docs/knowledge-base).

## Output and scripting

| Flag | Does |
| --- | --- |
| `-o table` | Human-readable. The default. |
| `-o json` | The raw API response, for piping into `jq`. |
| `-q` | Bare identifiers, one per line, for piping into the next command. |
| `-y` | Skip the confirmation before a real call or a delete. |
| `--base-url` | Point at a different deployment. |

**Shell**

```bash
# Every transcript from one agent's calls, into files.
sphoro-voice calls list --agent agt_9f2c… -q \
  | while read -r id; do
      sphoro-voice calls transcript "$id" -o json > "transcripts/$id.json"
    done
```

## Environment

| Variable | Does |
| --- | --- |
| `SPHORO_VOICE_API_KEY` | The credential. Wins over the saved login, which is what makes the CLI usable in CI without a login step. |
| `SPHORO_VOICE_BASE_URL` | The deployment to talk to. |

## Exit codes

| Code | Means |
| --- | --- |
| `0` | It worked. |
| `1` | The platform said no — read the message, and see [the error table](https://voice.sphoro.com/docs/authentication). |
| `2` | You asked for something it does not do. A usage error. |

Which means a script can distinguish "the call failed" from "I spelled the flag wrong", and should.