Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -80,7 +80,7 @@ another environment (internal testing only):
```sh
reply profile add dev \
--authority https://oauth.dev.replyapp.io \
--api-base https://api.dev.reply.io/v3
--api-base https://api.dev.reply.io
reply --profile dev auth login
```

Expand All @@ -89,7 +89,7 @@ Any field left off is inherited from the default (prod). Profiles live in

```jsonc
// ~/.config/reply/config.json
{ "profiles": { "dev": { "authority": "https://…", "api_base": "https://…/v3" } } }
{ "profiles": { "dev": { "authority": "https://…", "api_base": "https://…" } } }
```

## Packages: public vs internal
Expand Down
58 changes: 54 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -196,6 +196,14 @@ prints JSON (indented; compact with `--json`) and says what happened in a stable
| `reply sequence pause <id>` | → `paused` |
| `reply sequence start <id> [--expect-contacts N]` | → `started` / `already_active` |
| `reply contact-list add-contact <list-id> <contact> [--refuse-opted-out]` | → `added` |
| `reply contact-list create --name - [--shared]` | make an empty list of a name → `created` |
| `reply contact-list get <list-id>` · `reply contact-list delete <list-id>` | the list as Reply holds it · → `deleted` |
| `reply contact-list contacts <list-id> [--live-data-only] [--limit] [--offset]` | one page of the people on a list, oldest first |
| `reply live-data preview (--filters … [--max-per-company N] \| --job-id …) [--wait-seconds N]` | how many people and companies the filters match, and up to ten of them → `done` / `pending` |
| `reply live-data start --filters … --count N [--list-id N]… [--max-per-company N] [--with-phones]` | a search that adds the people it finds and puts them on the lists → `started` |
| `reply live-data get <id>` · `reply live-data list` | a search's status and counts · the team's searches, newest first |
| `reply live-data pause <id>` · `resume <id>` · `delete <id>` | → `paused` · `resumed` / `finished` · `deleted` |
| `reply live-data filter-values <kind> [--search …]` | values Reply suggests for industries, departments, seniorities, locations or job titles |
| `reply contact find --contact -` | the id of the contact under an email or a LinkedIn URL, or null; never creates one |
| `reply contact get <id>` | the contact as Reply holds it |
| `reply contact update (<id> \| <contact>) --fields -` | change some fields and custom fields; null clears one → `updated` |
Expand Down Expand Up @@ -447,9 +455,51 @@ reply schedule list --json
# "reply_status":"isDefaultForCurrentUser"}]}
```

`inbox reply`, `sequence create` and the five direct sends are the work commands that are not safe to
re-run. On exit 3 (outcome unknown) a reply or a send may already have gone, and running it again may
send it twice, unless the hint says nothing was sent. A direct send's exit 3 comes from a lost
Live Data finds people Reply does not hold yet. `reply live-data preview` sizes an audience before
anything is spent: how many people and companies the filters match, and up to ten of them. Nothing is
saved or charged. Reply works a preview out as a background job, which the command reads every two
seconds for up to `--wait-seconds` (default 120). Reading it needs the key's `other:read` scope. When
the wait runs out first the answer is `pending` with the `job_id`, and `--job-id` goes on waiting.
The filters are Reply's own object, as the API documents it, passed on untouched; the
`filter-values` lists are suggestions, not a vocabulary Reply checks.

A search adds the people it finds as contacts and puts them on the lists named, so make a list first
and read the people off it:

```sh
echo '{"name":"Audience 12"}' | reply contact-list create --name - --json
# {"status":"created","list_id":77,"name":"Audience 12","is_shared":false}
echo '{"jobTitles":[{"value":"CTO","type":"include"}]}' | reply live-data start --filters - --count 25 --list-id 77 --json
# {"status":"started","search_id":901}
reply live-data get 901 --json # status, contactsFound, usedCredits, lists
reply contact-list contacts 77 --limit 1000 --offset 0 --json # the people found so far, oldest first
```

`contact-list contacts` reads oldest first by the date a contact was added, equal dates by contact id,
highest first, an order that holds from page to page. A search adds each batch at the end of it, so for a
list one search fills, the number of people already read is a cursor that only moves forward: pass it
as `--offset`. A person Reply already holds is skipped by the search, not put on the list.

Reply refuses a start (`live_data.search_in_progress`) while an unfinished search of the same team has
the same filters, running or paused; the lists, the count, people per company and phones don't count,
and searches with different filters run side by side. That refusal holds only while the first search
is unfinished: one that already finished or was deleted no longer blocks, so after exit 3 a second
`live-data start` may start, and charge for, a second search. Look in `live-data list` first, where a
search shows its lists. A `--list-id` the account does not have or cannot reach is `contact-list.not_found`,
and nothing starts. `pause` applies to a running
search, `resume` to a paused one (`live_data.invalid_status` otherwise, Reply's detail naming the
status), and a resume without the credits for one contact is `live_data.insufficient_credits`. A
search paused by the plan's contact limit stays paused while its owner has no room for another
contact: that resume is `live_data.contact_limit_reached`. A resume answers `finished`, with Reply's `search_status`,
when the search already had everything it was asked for.
`live_data.service_failed` is Reply's search service failing: nothing changed, and the call can be
made again. Read a search's final counts before `live-data delete`: a deleted search answers
`live_data.not_found`. The contacts it added stay.

`inbox reply`, `sequence create`, `live-data start` and the five direct sends are the work commands that
are not safe to re-run. On exit 3 (outcome unknown) a reply or a send may already have gone, and running
it again may send it twice, unless the hint says nothing was sent; a search may already have started
(above). A direct send's exit 3 comes from a lost
answer, a 5xx, or a 400 to the send whose JSON carries neither a `code` nor `errors[]`, which is
Reply failing while it made the send. On a LinkedIn send, a 400 `directLinkedIn.unknown` is the
same: Reply failed while making the send or could not map the provider's answer, and its code is
Expand All @@ -470,7 +520,7 @@ Reply refused the add. `reply.invalid_request` means Reply didn't accept a field

**Exit codes.** `0` done · `1` failed, and the main effect did not happen · `2` usage error, nothing
sent · `3` **outcome unknown**: a write may have happened and no answer came back. Re-running the
same command is safe, except `inbox reply`, `sequence create` and the direct sends (above): each of
same command is safe, except `inbox reply`, `sequence create`, `live-data start` and the direct sends (above): each of
the others checks or relies on Reply's own state rather than repeating an effect blindly.

**Retries.** Reads are retried on errors. A write is retried only when it can't have reached Reply:
Expand Down
13 changes: 8 additions & 5 deletions skills/reply-adapter/reply-cli/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ description: >
Use when executing any Reply.io operation from a shell, setting up authentication,
or when another Reply skill needs commands executed.
metadata:
version: 1.3.1
version: 1.3.2
pack: reply-adapter
category: execution
maturity: reviewed
Expand Down Expand Up @@ -145,10 +145,10 @@ exit codes with their error `code` slugs.
- `Not authenticated` → run the auth setup above.
- `TEAM_REQUIRED` / `TEAM_NOT_ACCESSIBLE` / `USER_REQUIRED` / `USER_NOT_FOUND` → see
`reply-auth` skill; the CLI's stderr guidance shows the exact fix.
- Discrete domain commands (e.g. `reply sequences list`) are **not available yet**. The command
groups are `auth`, `profile`, `team`, `api`, `skills` and `install` — nothing else exists.
Don't invent one: reach the operation through `reply api`, using the endpoint mapping in
`reply-operations-mapping`.
- Work commands exist for the most common operations (`sequence`, `contact-list`, `live-data`,
`contact`, `inbox`, `account`, `schedule`, `direct-send`); `reply --help` lists them and each
command's `--help` gives its result and error codes. Don't invent one: reach any other operation
through `reply api`, using the endpoint mapping in `reply-operations-mapping`.

## Safety

Expand All @@ -165,6 +165,9 @@ explicit confirmation its Safety section requires.

## Changelog

- 1.3.2 (2026-11-06): *Failure modes* no longer says the work commands don't exist: it names the groups
(`sequence`, `contact-list`, `live-data`, `contact`, `inbox`, `account`, `schedule`, `direct-send`) and
keeps `reply api` for every other operation.
- 1.3.1 (2026-11-05): `reply api` says that a 429 naming a `reference` or saying a daily or weekly
limit was reached is never resent and comes back at once as the refusal it is.
- 1.3.0 (2026-08-10): said plainly that reaching the whole API is not reaching the whole job — the
Expand Down
33 changes: 22 additions & 11 deletions skills/reply-adapter/reply-operations-mapping/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ description: >
interpreting in business terms, or when you need to know whether Reply can do a thing at all
before promising it to a user.
metadata:
version: 2.3.0
version: 2.3.1
pack: reply-adapter
category: execution
maturity: draft
Expand Down Expand Up @@ -261,18 +261,23 @@ them wrong:
and the AI-SDR cluster are documented Beta or Coming soon. That belongs in the sentence where
the user chooses the route, before they commit to it — not in a caveat after the work. Fetch
the doc page and confirm the endpoint is callable, exactly as with any other surface.
3. **One Live Data search runs per team at a time.** This is a Reply fact and it belongs nowhere
else. An agent that does not know it will plan several searches in parallel and stall, or read
the refusal as a failure and retry it. Plan searches in series, and if one is already running,
the honest report is that the queue is occupied and by what.
3. **One unfinished search per filter set.** Reply refuses a start while an unfinished search of
the same team has the same filters, running or paused; searches with different filters run side
by side, and the target lists don't count. This is a Reply fact and it belongs nowhere else. An
agent that does not know it will read the refusal as a failure and retry it. Before running the
same filters again, let the earlier search finish, or delete it once its final counts are read;
a resumed search is unfinished again and still holds its filters.

Build the filter from the typeahead values — departments, industries, job titles, locations,
seniorities — rather than guessing accepted ones. Check the existing searches before starting a
near-identical one: a repeat spends again and returns a different world. Whatever comes back then
enters the normal path — `contact.create` or `import.apply` into a named list, with the same
mapping, dedupe policy and approval gate as any other import. Start can optionally drop the found
people straight into a sequence; treat that as `campaign.enroll` and hold it to the enrolment
gate rather than letting it ride along.
near-identical one: a repeat spends again and returns a different world. A start adds the people it
finds as contacts and puts them on the lists it names itself, so nothing it finds goes through
`contact.create` or `import.apply`: hold the start to the approval gate of an import before it
runs, and read the people back off its list. Start can optionally drop the found people straight
into a sequence; treat that as `campaign.enroll` and hold it to the enrolment gate rather than
letting it ride along. With reply-cli these are `reply live-data preview`, `start`, `get`, `list`,
`pause`, `resume`, `delete` and `filter-values`, and `reply contact-list contacts` reads a list's
people back.

**Contact enrichment is documented as available late August 2026 and is not callable today.**
`contact.enrich`, `company.enrich` and `phone_number.verify` are `absent` for that reason. Say
Expand Down Expand Up @@ -388,7 +393,8 @@ says — never let it disappear from the report because nothing was called.
what *this credential* may do is `capability.list`, and here that is answered by an
`insufficient_scope` refusal rather than by a listing.
- **Parallelising measurement** reads and hitting `429`, then retrying harder.
- **Planning two Live Data searches at once.** One runs per team at a time; the second stalls.
- **Running the same Live Data filters twice at once.** The second start is refused while the first
search is unfinished, running or paused; searches with different filters run side by side.
- **Starting a Live Data search without previewing it.** Start spends the user's allowance; the
mistake is only visible once it is already paid for.
- **Presenting a beta surface as settled**, or a *coming soon* one as callable. Contact enrichment
Expand Down Expand Up @@ -424,6 +430,11 @@ those as irreversible with no window and say so before acting rather than after.

## Changelog

- 2.3.1 (2026-11-06): Live Data's limit stated as Reply enforces it: one unfinished search per filter
set, not one per team; searches with different filters run side by side, and only an earlier
search that finished or was deleted frees its filters. A start puts the people it finds on its
lists itself, so nothing goes through `contact.create` or `import.apply`; the reply-cli commands
are named.
- 2.3.0 (2026-10-30): `message.send` in the fulfilment register says that a message composed as a
template goes by the same command and that Reply fills it in, before anything goes or when it
goes, and points to reply-api's *Templates* for the rest.
Expand Down
6 changes: 4 additions & 2 deletions src/__tests__/operations/commands.test.ts
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
import {describe, it, expect} from 'vitest';
import type {Command} from 'commander';
import {sequence_command, contact_list_command, contact_command, inbox_command, account_command, schedule_command,
direct_send_command} from '../../operations/commands';
direct_send_command, live_data_command} from '../../operations/commands';

const sub = (parent: Command, name: string): Command=>{
const found = parent.commands.find(c=>c.name() === name);
Expand All @@ -21,7 +21,9 @@ describe('operations/commands', ()=>{
it('names the commands in Reply\'s words', ()=>{
expect(sequence_command.commands.map(c=>c.name())).toEqual(
['list', 'create', 'get', 'contacts', 'stats', 'add-contact', 'remove-contact', 'pause', 'start']);
expect(contact_list_command.commands.map(c=>c.name())).toEqual(['add-contact']);
expect(contact_list_command.commands.map(c=>c.name())).toEqual(['create', 'get', 'delete', 'contacts', 'add-contact']);
expect(live_data_command.commands.map(c=>c.name())).toEqual(
['preview', 'start', 'get', 'list', 'pause', 'resume', 'delete', 'filter-values']);
expect(contact_command.commands.map(c=>c.name())).toEqual(['find', 'get', 'update', 'delete', 'opt-out',
'send-email', 'linkedin-connect', 'linkedin-message', 'linkedin-inmail', 'linkedin-voice']);
expect(inbox_command.commands.map(c=>c.name())).toEqual(['list', 'changes', 'get', 'reply', 'categories', 'categorize', 'mark-read', 'mark-unread']);
Expand Down
Loading
Loading