CLI

Everything the interface does, Voxagent also exposes over its API — and the API describes itself well enough that a generic client turns it into a command line. Nothing to keep updated: the command list comes from the server and follows the API on its own.

Install

We use Restish. It reads the API description at startup and builds the commands from it.

brew install rest-sh/tap/restish

Other systems — see rest.sh. This page assumes Restish 2.x; check with restish --version.

Connect

One command, once:

restish api connect voxagent https://api.voxagent.ru \
  --spec https://api.voxagent.ru/swagger/cli/swagger.json

It fetches the description, works out where to sign in and saves everything itself. You should see it report the API, the auth scheme and the number of commands found:

Discovered SpeakNode CLI
This API declares 2 auth scheme(s):
  OAuth2   oauth2 authorizationCode   … operations
Connected API "voxagent" (… operations discovered)

The client id, the sign-in address and the scopes all come from the server.

Reconnecting later — after the API gained new commands, for instance — takes --replace:

restish api connect voxagent https://api.voxagent.ru \
  --spec https://api.voxagent.ru/swagger/cli/swagger.json --replace

Signing in

There is no separate login command. The first command that needs authorisation starts the sign-in by itself:

1. You run a command — say restish voxagent get-users-me.
2. A browser window opens on the usual Voxagent sign-in page.
3. You sign in. The page says it can be closed.
4. The command completes and prints its result.

Behind that, Restish listens on localhost:8484 for the callback — which is why you configure nothing and paste nothing.

The token is remembered. Later commands run without asking; when it expires it is refreshed silently. You sign in again only after signing out, or after a long gap with no activity.

Using it

Commands follow the API: the HTTP method plus the path.

restish voxagent get-users-me
restish voxagent get-agents
restish voxagent get-agents-id 3e4666bf-d5e5-4aa7-b8ce-cefe41c7568a

Path arguments go in order, after the command. To see everything:

restish voxagent --help              # all commands, grouped by area
restish voxagent get-agents --help   # arguments, request and response shape

Reading the output

By default you get the whole JSON response. That is a lot for a list, so pick the fields you want and ask for a table. The projection is jq:

restish voxagent get-agents \
  -f '.body.agents[] | {title, id, is_published}' -o table

┌──────────────────┬──────────────────────────────────────┬──────────────┐
│ title            │ id                                   │ is_published │
├──────────────────┼──────────────────────────────────────┼──────────────┤
│ Sales assistant  │ 3e4666bf-d5e5-4aa7-b8ce-cefe41c7568a │ true         │
│ Support line     │ 91ab2c7d-1f03-4e55-9c18-7a2be4d0c911 │ false        │
└──────────────────┴──────────────────────────────────────┴──────────────┘

Mind the shape of the response: a list usually arrives inside a field, not at the top level — body.agents, body.sessions, body.tools. restish voxagent <command> --help shows it.

restish voxagent get-sessions \
  -f '.body.sessions[] | {agent_title, status, duration_seconds}' -o table

A single field needs no jq:

restish voxagent get-agents -f 'body.agents[].title'

Output formats: json (default), yaml, table.

Sending data

The request body comes from a file or from standard input:

restish voxagent post-analytics-conversations-search <request.json
echo '{"page": 1, "page_size": 20}' | restish voxagent post-analytics-conversations-search

--help on the command prints a ready example of the body.

What you can and cannot reach

The CLI acts as you: your account, your space, your permissions. It cannot see a space you have no access to, and it cannot do anything the interface would refuse.

Administrative endpoints are deliberately absent — they are not in the command list at all.

If something goes wrong