CLI

Everything the interface does, Speaknode 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 speaknode https://test.api.speaknode.com \
  --spec https://test.api.speaknode.com/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 "speaknode" (… 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 speaknode https://test.api.speaknode.com \
  --spec https://test.api.speaknode.com/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 speaknode get-users-me.
2. A browser window opens on the usual Speaknode 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 speaknode get-users-me
restish speaknode get-agents
restish speaknode get-agents-id 3e4666bf-d5e5-4aa7-b8ce-cefe41c7568a

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

restish speaknode --help              # all commands, grouped by area
restish speaknode 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 speaknode 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 speaknode <command> --help shows it.

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

A single field needs no jq:

restish speaknode 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 speaknode post-analytics-conversations-search <request.json
echo '{"page": 1, "page_size": 20}' | restish speaknode 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