Private beta. The Cradle Calls CLI is available only to organisations that Cradle has added to the private beta. If your organisation hasn't been added, signing in will tell you it isn't in the beta yet. To join, ask your Cradle contact or email help@cradle.io. Features may change before general release.

What the Cradle Calls CLI does

The Cradle Calls CLI (cradle-calls) gives you, and an AI assistant working for you, read-only access to your Cradle calls from the command line. You can ask your assistant things like "what did I promise on the phone today?" or "how many calls did the team miss last week?" without opening Cradle.

Admins can also ask about how their teams answer calls, for example:

"Which office is missing the most calls?"
"Why is the Sales team missing calls?"
"Did last week's routing change help?"

The CLI comes with instructions (skills) for these questions. See Help with missed calls (admins) below.

It can:

List your calls for a day or date range, with who was on them and how they went.
Read a call's AI summary, and the transcript of your part of the call.
Download the audio of your part of a recorded call, as a file.
Find calls by phone number, contact, CRM contact or HubSpot record, and see which CRMs a call was logged to.
Run your call reports, with the same numbers as the Cradle web app.
For admins: show who was rung and didn't answer, when calls are missed, how long callers wait, each person's presence when calls rang them, and how each team's calls are routed.

It can't change, delete or send anything in Cradle.

Who can see what

Everyone sees only their own call content: calls you answered or placed, and voicemails left for you. On a transferred call, you only get your own part.
Admins can also list every call in the organisation and run organisation, team and number reports, but don't see the content of calls they weren't on.
Admins can choose to give one token access to the organisation's calls: transcripts, summaries, recording details and recording audio, each chosen separately. This needs an explicit confirmation, must be limited to specific IP addresses, and lasts up to 30 days. Only turn it on if you've thought through who could read your organisation's conversations with it.
Call transcripts follow your organisation's transcription setting.

What you need

Your organisation added to the private beta.
A computer with Node.js 20 or later, where you or your assistant will run the CLI. That can be your own computer, or a server or container where an always-on assistant runs (see Setting up an always-on assistant below).
Your usual Cradle sign-in (Google or Microsoft).

Install and sign in

Install the CLI:

npm install -g https://reporting-api.cradle.io/cli/download/cradle-calls.tgz

Sign in:
```
cradle-calls login
```
Your browser opens a Cradle sign-in page. Sign in, read and accept the Cradle Calls CLI Private Beta Terms, and choose Create token.
On that page, add the IP addresses the CLI will be used from (see the next section). Use my current address fills in the one you're on.
The CLI saves your token securely on that computer (in its keychain where available) and doesn't show it. Check it worked:
```
cradle-calls whoami
```
If you're connecting an AI assistant, give it the CLI's instruction files (skills). List them:
```
cradle-calls skill --list
```
Then save each one where your assistant loads its skills or instructions. cradle-calls skill prints the main one, and cradle-calls skill <name> prints each of the others, for example:
```
cradle-calls skill > cradle-calls.md
cradle-calls skill cradle-answer-rates > cradle-answer-rates.md
cradle-calls skill cradle-missed-calls > cradle-missed-calls.md
cradle-calls skill cradle-routing-trial > cradle-routing-trial.md
```
Save them again after you update the CLI, so your assistant has the current versions.

To install a fixed version instead of the latest one, see Pinning a version below.

Setting up an always-on assistant

Use these steps if your assistant runs on a server, a home server or in a container, rather than on the computer you use every day. These machines usually have no web browser and no keychain, and may be rebuilt from scratch, so the CLI is set up a little differently:

you sign in on your own computer, then send the token straight to the assistant's machine, so nobody sees or copies it
the token is kept in a file that only the assistant can read, on storage that survives a rebuild.

1. Install the CLI when the machine or image is built

Install a fixed version and check it before installing, so every rebuild gets exactly the same CLI. For example, in a container build file:

ARG CRADLE_CALLS_VERSION=26.6.0
ARG CRADLE_CALLS_SHA256=c57917fd7bdbbe386c1f076c7d6ef7d62adf79432d2724c0e43ea5850feee9bc
RUN curl -fsSLo /tmp/cc.tgz https://reporting-api.cradle.io/cli/download/cradle-calls-${CRADLE_CALLS_VERSION}.tgz \
 && echo "${CRADLE_CALLS_SHA256}  /tmp/cc.tgz" | sha256sum -c - \
 && npm install -g /tmp/cc.tgz && rm /tmp/cc.tgz

If the check fails, the download isn't the file you expected, and nothing is installed. See Pinning a version for where these values come from.

2. Choose where the token is kept

Point the CLI at storage that survives a rebuild, and that only the assistant's user account can read. Set one of these on the assistant's machine or container:

Setting	What it does
`CRADLE_CALLS_TOKEN_FILE`	The file the token is read from and saved to. Use this for a mounted secret, for example `/run/secrets/cradle_calls`.
`CRADLE_CALLS_CONFIG_DIR`	The folder the CLI keeps its sign-in and settings in, for example a folder on a mounted volume.

The CLI refuses to use a token file that other users on the machine can read, and tells you how to fix it. Don't put the token in an environment variable or a .env file. Other processes on the machine can read those.

3. Sign in on your computer and send the token across

On your own computer, where the browser sign-in works, run this, using the public IP address of the network the assistant runs on:

cradle-calls login --print --ip <assistant's public IP address> \
  | ssh <user>@<assistant's machine> 'cradle-calls token import'

If the assistant runs in a container on that machine, run token import inside the container instead, for example docker exec -i <container> cradle-calls token import.

On the sign-in page:

Accept the Beta Terms.
Name the token after the assistant, for example "assistant server", so you can recognise it later.
Keep the IP address that's already filled in. It's the assistant's address, not your computer's.
Leave organisation-wide access off unless you've decided the assistant needs it.

token import only reads the token from the connection, never from typing or pasting, and refuses if it's run by hand. It checks the token with Cradle before saving it and never shows it. To renew the token before it expires, run the same command again.

4. Check it

On the assistant's machine, run cradle-calls whoami. Check that:

token_source is file
token.ip_allowlist lists only the assistant's address
org_content is empty, unless you chose organisation-wide access.

token.expires_at shows when the token expires. Tokens last 90 days (30 with organisation-wide access). It's a good idea to have your assistant remind you 14 days before.

5. Limit what the assistant can run

Let the assistant run list, get, reports and whoami on its own. Only you should run login, logout, token import and tokens revoke. Decide where call content may go, for example only to you, and tell your assistant. Don't let it store transcripts in files, code repositories or logs.

Running the CLI on your own servers, containers and private package stores is covered by the Beta Terms, as long as only your people and your assistant can reach it.

Pinning a version

Every released version of the CLI stays available at its own address, and its contents never change. https://reporting-api.cradle.io/cli/download/latest.json lists every available version, newest first, each with its download address and SHA-256 checksum. To upgrade a pinned install, take the new version number and checksum from there.

Keep your access safe

A CLI token can read call transcripts, summaries, recording audio and CRM details. In the wrong hands it could be used to extract highly sensitive information, so protecting it is critical.

Restrict it to your static IP address, and only that address.
Using an AI assistant? Restrict it to the network your assistant runs on, and only that network, ideally the place you normally work from.
Never share a token or paste it into a chat, email or file.
Revoke it straight away if you think it's been exposed: cradle-calls logout on that computer, or ask an admin to revoke it.
Treat downloaded recordings as your customers' conversations. Keep audio files somewhere secure, share them only with people who need them, use them only with tools and services your organisation has approved, and delete them when you've finished with them.

Admins can limit every token in the organisation to set IP addresses, and see and revoke any token, on the CLI access page: https://reporting-api.cradle.io/cli/access

Common tasks

You want to	Run
See today's calls	`cradle-calls list --since today`
Read a call with its transcript	`cradle-calls get <call id> --transcript`
Find calls with a phone number	`cradle-calls list --since 30d --number +6421000000`
Find calls with a HubSpot contact	`cradle-calls list --since 30d --crm hubspot --crm-id <contact id>`
Find calls not yet logged to a CRM	`cradle-calls list --since 7d --crm-logged none`
See your numbers for the week	`cradle-calls reports get overview --since 7d`
See every report you can run	`cradle-calls reports list`
Compare every team's answer rate (admins)	`cradle-calls reports get teams --since 7d`
See who was rung and didn't answer, when calls are missed and how long callers waited (admins)	`cradle-calls reports get diagnose --team "<team>" --since 7d`
See each person's presence when calls rang them, a week at most (admins)	`cradle-calls reports get presence --team "<team>" --since 6d`
See how a team's calls are routed now (admins)	`cradle-calls reports get routing --team "<team>"`
Check your token's expiry and IP addresses	`cradle-calls whoami`
Download a call's recording audio	`cradle-calls audio <call id> --out <folder>`
Sign out and revoke your token	`cradle-calls logout`

Searches and reports cover up to 93 days at a time; the presence report covers a week at most. Leave out --team to run diagnose, presence or routing for the whole organisation. Team and organisation reports need an admin.

Help with missed calls (admins)

Three skills come with the CLI for admins who want to know how well their teams answer calls. Your assistant uses them when you ask the right kind of question:

Skill	What it does
`cradle-answer-rates`	Compares every team's answer rate with a typical benchmark for your kind of business, and shows whether it's getting better or worse.
`cradle-missed-calls`	For one team: how its calls are routed, who is rung and doesn't answer, their presence when calls rang them, how long callers wait, when misses happen, missed calls nobody has returned, and what to change in the admin portal.
`cradle-routing-trial`	Compares a team's calls before and after a routing change, such as a new ring order or ring time.

The skills only read reports. Any change is yours to make in the admin portal. For the same advice without the CLI, see Finding out why calls are missed (/knowledge/why-calls-are-missed).

Troubleshooting

"Your organisation isn't in the Cradle Calls CLI private beta yet." Your organisation hasn't been added. Contact help@cradle.io.
"Not signed in": run cradle-calls login again. On an assistant's machine, it names the token file it looked for. Send a new token with token import.
"can be read by other users": the token file's permissions are too open. Run the chmod 600 command shown.
"token import reads a token from a pipe, never the keyboard": send the token from cradle-calls login --print on your own computer, as in step 3 of Setting up an always-on assistant.
"ip_not_allowed": you're on an address that isn't on your token's or your organisation's list. Sign in again from an allowed address, or ask an admin to update the list.
"forbidden": you've asked for something your access doesn't cover, such as a colleague's call content or an organisation report as a non-admin.
"rate_limited": wait the number of seconds shown, then try again.

Using the Cradle API from your own systems

For a system rather than a person, such as a reporting warehouse or an integration, an admin can create an organisation API key instead of a CLI token. The CLI accepts these keys too. See Getting started with the Cradle API (/knowledge/cradle-api-private-beta) and Creating and managing Cradle API keys (/knowledge/cradle-api-keys).

Terms

Use of the CLI is subject to the Cradle Calls CLI Private Beta Terms (https://reporting-api.cradle.io/cli/terms), which add to Cradle's Terms of Use, Data Processing Agreement and Privacy Policy. You're responsible for keeping your tokens secure, including any loss of a token or breach resulting from one.

Questions? Email help@cradle.io, Monday to Friday, 8:30 am to 5:00 pm New Zealand time.