Command reference - Ringee Documentation

Add --json to any command for raw, machine-readable output.

ringee [--json] <group> <command> [args] [options]

Phone numbers are E.164 (+14155552671). Datetimes are ISO-8601 with an offset (2026-05-23T14:30:00-04:00).

Every command at a glance

Read looks, never changes anything · Write creates or updates a record · Sensitive spends money or mints a shareable link · Destructive removes access or data

Command	Type	Guard
`contacts search`	Read	—
`contacts get`	Read	—
`contacts by-outcome`	Read	—
`contacts create`	Write	—
`contacts update`	Write	—
`contacts delete`	Destructive	`--confirm-phone` + `--yes`
`leads search`	Read	—
`leads reveal`	Sensitive	`--yes`
`leads import`	Write	—
`sessions create`	Sensitive	`--yes`
`sessions get`	Read	—
`sessions update`	Write	—
`sessions revoke`	Destructive	`--yes`
`calls list`	Read	—
`outcomes log`	Write	—
`callbacks create`	Write	—
`callbacks list`	Read	—
`meetings schedule`	Write	—
`campaigns list` / `campaigns get`	Read	—
`campaigns status`	Write	org admin
`campaigns leads`	Read	—
`campaigns add-lead` / `campaigns import-leads`	Write	org admin
`campaigns delete-lead`	Destructive	`--yes` + org admin
`campaigns analytics`	Read	—
`analytics calls` / `analytics day`	Read	—
`dnc list`	Read	—
`dnc add`	Write	—
`dnc remove`	Destructive	`--yes`
`pipelines list` / `pipelines results`	Read	admin policy
`voice-agents list`	Read	organization
`voice-agents call`	Sensitive	`--yes` + organization
`voice-agents call-result`	Read	organization
`config show` / `config check`	Read	—
`tools` / `flow` / `prompt`	Read	works offline

Contacts

`contacts search`

ringee contacts search <query...>

Search by name, phone, email or company.

Option	Description
`-p, --page <n>`	Page number
`-l, --limit <n>`	Page size, max 50

ringee contacts search acme
ringee contacts search "ada lovelace" --limit 5

`contacts get`

ringee contacts get <contactId>

Full details for one contact, including recent calls, notes and meetings.

`contacts by-outcome`

ringee contacts by-outcome <outcomes...>

Find contacts whose calls reached given outcomes — useful for deriving an ICP from closed business.

Option	Description
`--match <any\|last>`	`any` matches any call; `last` only the most recent
`--include-unreachable`	Include `doNotCall` and `unsubscribed` contacts
`-p, --page <n>`	Page number
`-l, --limit <n>`	Page size, max 50

ringee contacts by-outcome sale interested --match last

Valid outcomes: meeting_booked, sale, interested, follow_up, callback_scheduled, not_interested, no_answer, voicemail, wrong_number, gatekeeper.

`contacts create`

Option	Description
`--phone <e164>`	Required. Must be unique in the workspace
`--name <name>`	Display name
`--first <firstName>` / `--last <lastName>`	Name parts
`--email <email>`	Email
`--title <jobTitle>`	Job title
`--company <organization>`	Company name
`--note <note>`	Initial note

ringee contacts create --phone +14155552671 --name "Ada Lovelace" --company "Babbage Engines"

`contacts update`

ringee contacts update <contactId>

Accepts --phone, --name, --first, --last, --email, --title, --company. Only the flags you pass change.

`contacts delete`

ringee contacts delete <contactId>

Destructive

Destructive. Requires both --confirm-phone matching the stored number and --yes.

ringee contacts get <contactId>          # verify the number first
ringee contacts delete <contactId> --confirm-phone +14155552671 --yes

Leads

Prospecting uses your connected enrichment provider. These commands never spend Ringee calling credits.

`leads search`

Returns a jobId you pass to reveal and import.

Option	Description
`--provider <name>`	`apollo` or `prospeo`. Auto-selected when omitted
`--keywords <text>`	Free-text keywords
`--title <t>`	Job title (repeatable or comma-separated)
`--seniority <s>`	Seniority (repeatable)
`--department <d>`	Department (repeatable)
`--industry <i>`	Industry (repeatable)
`--country <c>` / `--city <c>`	Person location (repeatable)
`--company <name>` / `--domain <d>`	Company filters (repeatable)
`--has-email` / `--has-phone`	Only candidates with that field
`--page <n>` / `--per-page <n>`	Pagination, max 25 per page

ringee leads search --title "VP Sales" --country US --industry Software

`leads reveal`

ringee leads reveal <jobId> <externalId>

Sensitive Spends provider credits Unlocks email — and optionally phone — and upserts a Ringee contact.

Option	Description
`--phone`	Also reveal a mobile phone (extra provider credits)
`-y, --yes`	Required. Confirms the credit spend

`leads import`

ringee leads import <jobId> <externalIds...>

Bulk-imports candidates as contacts, deduplicated by phone number. Does not reveal hidden emails or phones.

Call sessions

`sessions create`

Sensitive Mints a magic link someone can open to dial through a queue without logging in.

Option	Description
`--contact <id>`	Contact in the queue (repeatable)
`--phone <e164>`	Raw phone in the queue (repeatable)
`--title <title>`	Session title
`--campaign <campaignId>`	Attribute calls to a campaign
`--max-calls <n>`	Auto-complete after N calls
`-y, --yes`	Required. Confirms minting a shareable link

ringee sessions create --contact <id> --contact <id> --title "Tue outbound" --yes

The join URL is printed once and cannot be re-fetched. Share it only with someone authorized to call on the workspace’s behalf.

`sessions get`

ringee sessions get <callSessionId>

Status and progress. Never prints the raw token.

`sessions update`

ringee sessions update <callSessionId>

Option	Description
`--title <title>`	New title
`--campaign <campaignId>`	Set a campaign, or `null` to detach
`--expires <minutes>`	Extend validity

`sessions revoke`

ringee sessions revoke <callSessionId>

Destructive

Destructive. Requires --yes. The link stops working immediately; call history is preserved.

Calls and follow-ups

`calls list`

Full call detail, newest first.

Option	Description
`--contact <contactId>`	Filter to one contact
`--outcome <outcomes...>`	Filter by logged outcome
`--status <statuses...>`	Filter by status, e.g. `completed`
`--from <iso>` / `--to <iso>`	Created-at range
`--full`	Print the full transcription instead of a preview
`-p, --page <n>` / `-l, --limit <n>`	Pagination, max 50

ringee calls list --outcome sale --from 2026-05-01T00:00:00Z --full

`outcomes log`

ringee outcomes log <callId> <outcome>

Option	Description
`--note <note>`	Free-text follow-up note

`callbacks create`

ringee callbacks create <contactId> <scheduledAt>

Option	Description
`--call <callId>`	Source call id
`--note <note>`	Free-text note

ringee callbacks create <contactId> 2026-05-24T10:00:00-04:00 --note "Asked for Monday"

`callbacks list`

ringee callbacks list

Lists callbacks soonest first, with the contact and originating campaign.

Option	Description
`--status <status>`	`scheduled`, `due`, `in_progress`, `completed`, `missed` or `cancelled`
`-p, --page <n>` / `-l, --limit <n>`	Pagination, max 50

`meetings schedule`

ringee meetings schedule <contactId> <scheduledAt>

Option	Description
`--title <title>`	Meeting title
`--duration <minutes>`	Defaults to 30
`--location <location>`	Address or video URL
`--email <attendeeEmail>`	Send an external calendar invitation when connected
`--call <callId>`	Source call; also sets its outcome to `meeting_booked`
`--notes <notes>`	Notes

Campaigns

Campaign commands require an active organization workspace. Every write is restricted to organization admins.

`campaigns list`

ringee campaigns list

Option	Description
`-s, --search <text>`	Filter by name or description
`--status <status>`	`draft`, `active`, `paused` or `completed`
`-p, --page <n>` / `-l, --limit <n>`	Pagination, max 50

`campaigns get`

ringee campaigns get <campaignId>

Returns the campaign configuration, lead count, dialer mode, attempts, retry delay, wrap-up time and working hours.

`campaigns status`

ringee campaigns status <campaignId> <status>

The server accepts only these transitions:

draft → active
active → paused or completed
paused → active or completed
completed is terminal

Activating a campaign also requires at least one lead, one configured disposition and a usable outbound number.

`campaigns leads`

ringee campaigns leads <campaignId>

Option	Description
`--status <status>`	`pending`, `queued`, `locked`, `dialing`, `in_call`, `wrap_up`, `dispositioned`, `scheduled`, `completed`, `exhausted`, `dnc`, `called` or `dead`
`-p, --page <n>` / `-l, --limit <n>`	Pagination, max 50

`campaigns add-lead`

ringee campaigns add-lead <campaignId> --phone <e164> --name <name>

Reuses an existing contact with the same phone number when one exists.

Option	Description
`--phone <e164>`	Required. Lead phone number
`--name <name>`	Required. Lead name
`--email <email>`	Email
`--company <company>`	Company
`--title <jobTitle>`	Job title
`--state <state>`	State or region
`--website <website>`	Website

`campaigns import-leads`

ringee campaigns import-leads <campaignId> <file>

The file must contain a non-empty JSON array with at most 200 entries:

[
  {
    "name": "Ada Lovelace",
    "phone": "+14155552671",
    "email": "ada@example.com",
    "company": "Analytical Engines",
    "jobTitle": "Founder",
    "state": "CA",
    "website": "https://example.com"
  }
]

`campaigns delete-lead`

ringee campaigns delete-lead <campaignId> <leadId> --yes

Destructive. Removes the lead, its call attempts and its campaign callbacks. The underlying contact is preserved. A lead that is locked, dialing, in a call or wrapping up cannot be removed.

`campaigns analytics`

ringee campaigns analytics <campaignId>

Option	Description
`--from <iso>` / `--to <iso>`	Reporting window
`--no-agents`	Skip the per-agent breakdown
`--hourly`	Include the hourly call-volume histogram

The result includes attempts, connections, conversions, rates, handle time, dispositions and lead status totals.

Analytics

`analytics calls`

ringee analytics calls

Reads the same call-performance data shown on the dashboard overview.

Option	Description
`-r, --range <range>`	`today`, `yesterday`, `7d`, `30d`, `this_month` or `last_month`
`--from <iso>` / `--to <iso>`	Custom reporting window
`--campaign <campaignId\|none>`	One campaign, or only calls outside campaigns
`--outcome <outcome>`	Restrict every metric to one outcome
`--scope <scope>`	`personal` or `organization`
`--member <userId>`	One member; organization admins only
`--include <blocks...>`	Any of `kpis`, `funnel`, `by-outcome`, `over-time`, `best-time-of-day`, `agents`

If --include is omitted, Ringee computes kpis, funnel and by-outcome.

ringee analytics calls --range 30d --campaign none
ringee analytics calls --scope organization --include kpis agents

`analytics day`

ringee analytics day <YYYY-MM-DD>

Returns calls, callbacks and meetings for one calendar day.

Option	Description
`--offset <utcOffset>`	Day boundary offset, for example `-04:00`; defaults to UTC
`--campaign <campaignId\|none>`	One campaign, or calls outside campaigns
`--outcome <outcomes...>`	Include only these call outcomes
`--no-callbacks`	Skip callbacks
`--no-meetings`	Skip meetings
`-l, --limit <n>`	Maximum calls returned, default 50 and max 100

Do-not-call list

`dnc list`

ringee dnc list

Option	Description
`-s, --search <fragment>`	Filter by phone-number fragment
`-p, --page <n>` / `-l, --limit <n>`	Pagination, max 50

`dnc add`

ringee dnc add <phoneNumbers...>

Adds one or more E.164 numbers to the workspace suppression list. Every future Ringee dial surface, including AI Voice Agents, checks this list before calling.

Option	Description
`--reason <reason>`	Why the numbers were suppressed

`dnc remove`

ringee dnc remove <phoneNumber> --yes

Destructive compliance change. Releasing a number makes it callable again. Verify the entry with dnc list and remove it only when the person has asked to be callable.

AI pipelines

Pipeline reads follow the admin policy: freelancers can read their personal context; inside an organization, the caller must be an organization admin.

`pipelines list`

ringee pipelines list

Lists the available pipelines, enabled contexts, pending actions and newly eligible calls.

`pipelines results`

ringee pipelines results <pipeline> [context]

<pipeline> is one of follow_up_recommendations, script_optimization or objection_intelligence. Choose exactly one analysis context:

Option	Description
`--campaign <campaignId>`	Calls attributed to one campaign
`--org`	Organization calls outside campaigns; the default in an organization
`--personal`	Personal calls in a freelancer workspace
`--status <status>`	`pending` (default), `completed`, `dismissed` or `snoozed` actions

ringee pipelines results objection_intelligence --org
ringee pipelines results follow_up_recommendations --campaign <campaignId> --status pending

AI Voice Agents

These commands require an active organization workspace. A voice-agent call runs server-side; the CLI can exit while the conversation continues.

`voice-agents list`

ringee voice-agents list

Lists agents, their type and status, required variables, default caller number and usable Ringee caller-number ids.

`voice-agents call`

ringee voice-agents call <agentId> --to <phone> --var <name=value> --yes

This starts a real outbound phone call and spends Ringee credits. --yes is required.

Option	Description
`--to <phone>`	Required. Destination in E.164
`--from <numberId>`	Ringee phone-number id to call from; otherwise use the agent default or the sole eligible number
`--var <name=value>`	Dynamic conversation variable; repeatable and values may contain `=`
`--external-id <id>`	Your id, returned later under `metadata.external_id`
`-y, --yes`	Required. Confirm the real, billed call

ringee voice-agents call <agentId> \
  --to +14155552671 \
  --var first_name=Ada \
  --var appointment_date=2026-09-10 \
  --var appointment_time=14:00 \
  --yes

`voice-agents call-result`

ringee voice-agents call-result <callId>

Read the current status and, once analysis is ready, the outcome, summary, sentiment, extracted data and metadata. Poll deliberately; retrying voice-agents call starts another call. See AI Voice Agents from the CLI for the end-to-end workflow and type-specific variables.

Config and knowledge

Command	Description
`ringee config show`	Resolved connection, token masked
`ringee config check`	Connect and list every tool the server exposes
`ringee tools`	The agent capability catalog with sensitivity tags
`ringee flow`	The outbound sales flow, step by step
`ringee prompt`	The shared agent system prompt

tools, flow and prompt need no connection — they print the shared knowledge from @ringee-io/agent, which is handy when briefing your own agent.

Global options

Option	Description
`--json`	Raw JSON instead of formatted text
`-v, --version`	Print the version
`--help`	Help for any command or subcommand

Next steps

Drive it from an agent

Use the CLI as an agent’s Ringee interface

​Every command at a glance

​Contacts

​contacts search

​contacts get

​contacts by-outcome

​contacts create

​contacts update

​contacts delete

​Leads

​leads search

​leads reveal

​leads import

​Call sessions

​sessions create

​sessions get

​sessions update

​sessions revoke

​Calls and follow-ups

​calls list

​outcomes log

​callbacks create

​callbacks list

​meetings schedule

​Campaigns

​campaigns list

​campaigns get

​campaigns status

​campaigns leads

​campaigns add-lead

​campaigns import-leads

​campaigns delete-lead

​campaigns analytics

​Analytics

​analytics calls

​analytics day

​Do-not-call list

​dnc list

​dnc add

​dnc remove

​AI pipelines

​pipelines list

​pipelines results

​AI Voice Agents

​voice-agents list

​voice-agents call

​voice-agents call-result

​Config and knowledge

​Global options

​Next steps

Drive it from an agent

Every command at a glance

Contacts

`contacts search`

`contacts get`

`contacts by-outcome`

`contacts create`

`contacts update`

`contacts delete`

Leads

`leads search`

`leads reveal`

`leads import`

Call sessions

`sessions create`

`sessions get`

`sessions update`

`sessions revoke`

Calls and follow-ups

`calls list`

`outcomes log`

`callbacks create`

`callbacks list`

`meetings schedule`

Campaigns

`campaigns list`

`campaigns get`

`campaigns status`

`campaigns leads`

`campaigns add-lead`

`campaigns import-leads`

`campaigns delete-lead`

`campaigns analytics`

Analytics

`analytics calls`

`analytics day`

Do-not-call list

`dnc list`

`dnc add`

`dnc remove`

AI pipelines

`pipelines list`

`pipelines results`

AI Voice Agents

`voice-agents list`

`voice-agents call`

`voice-agents call-result`

Config and knowledge

Global options

Next steps