@sortlist/cli 0.60.0 → 0.61.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/index.js.map +1 -1
- package/package.json +1 -1
- package/skills/sortlist-cli/SKILL.md +139 -561
- package/skills/sortlist-cli/references/atlas.md +197 -0
- package/skills/sortlist-cli/references/billing-and-permissions.md +253 -0
- package/skills/sortlist-cli/references/identity-and-accounts.md +118 -0
- package/skills/sortlist-cli/references/outreach.md +126 -0
- package/skills/sortlist-cli/references/signals.md +104 -0
- package/skills/sortlist-cli/scripts/quote-reveals.mjs +182 -0
- package/skills/sortlist-go-to-market/SKILL.md +73 -233
- package/skills/sortlist-go-to-market/references/agency-briefing.md +22 -0
- package/skills/sortlist-go-to-market/references/campaigns.md +114 -0
- package/skills/sortlist-go-to-market/references/context-and-brief.md +92 -0
- package/skills/sortlist-go-to-market/references/prospect-list.md +115 -0
- package/skills/sortlist-go-to-market/references/search-state.md +87 -0
- package/skills/sortlist-go-to-market/references/sourcing.md +194 -0
- package/skills/sortlist-go-to-market/scripts/render-prospect-list.mjs +157 -0
|
@@ -1,582 +1,160 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: sortlist-cli
|
|
3
|
-
description:
|
|
4
|
-
user-invocable: true
|
|
3
|
+
description: Use the sl CLI to find and reveal Sortlist organizations and contacts in Atlas, resolve places in Mercator, manage Signals watchers and leads, connect Outreach accounts and perform actions, or manage Hermes companies, applications and billing. Covers live command discovery, identity, company context, costs, permissions and asynchronous results. Use for Sortlist app data or actions and explicit sl/API requests, not unrelated prospecting or generic sales advice.
|
|
5
4
|
---
|
|
6
5
|
|
|
7
6
|
# Sortlist CLI
|
|
8
7
|
|
|
9
|
-
`sl`
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
Hermes's account and company operations are grouped the same way (`sl hermes companies`,
|
|
13
|
-
`sl hermes applications`); their old top-level names (`sl companies`) still work but are not listed. If `sl` is not on `PATH`, do not search the disk for it: say so in one line, give the install
|
|
14
|
-
(`npm install -g @sortlist/cli`, Node 24 or later) and stop.
|
|
8
|
+
`sl` exposes the GraphQL operations the backend tags for the CLI and the current token can see,
|
|
9
|
+
grouped by service: `sl atlas ...`, `sl mercator ...`, `sl signals ...`, `sl outreach ...`,
|
|
10
|
+
`sl hermes ...`. The current command help and schema govern available flags and fields.
|
|
15
11
|
|
|
16
|
-
|
|
17
|
-
|
|
12
|
+
Reach the app through `sl` only. Do not bypass missing commands or access controls with raw
|
|
13
|
+
GraphQL, `curl`, `fetch`, or a bearer token passed to another client. If `sl` is missing from
|
|
14
|
+
`PATH`, explain that it requires Node 24+ and `npm install -g @sortlist/cli`; do not install it
|
|
15
|
+
or change the user's setup unless the task authorizes that.
|
|
18
16
|
|
|
19
|
-
|
|
20
|
-
choose (a next step, which contacts, which dimensions, a paid call, a company, an environment), put
|
|
21
|
-
the choices in one question the user answers by picking:
|
|
17
|
+
## Start with the requested result
|
|
22
18
|
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
emails); a single choice when they exclude each other.
|
|
27
|
-
- The option you would pick first, marked "(Recommended)". A "Nothing for now" option when doing
|
|
28
|
-
nothing is reasonable.
|
|
29
|
-
- Several independent decisions go in one call, up to 4 questions.
|
|
19
|
+
Reuse the brief and session context. A search request authorizes the necessary sourcing work;
|
|
20
|
+
it does not authorize revealing paid dimensions, creating an ongoing watcher or contacting people.
|
|
21
|
+
Do not force a full go-to-market workflow, Signals, or an account connection onto a shortlist task.
|
|
30
22
|
|
|
31
|
-
|
|
32
|
-
|
|
23
|
+
Ask only for information that changes the result or is needed for authorization. Use the host's
|
|
24
|
+
question tool when available and appropriate, following its schema. `AskUserQuestion` is one
|
|
25
|
+
possible tool, not a dependency. If no suitable tool is available, ask a concise question in prose
|
|
26
|
+
and wait when the answer is required. Offer useful choices with their consequences and costs when
|
|
27
|
+
known. Do not request confirmation again for work already covered by a specific approval or bounded
|
|
28
|
+
plan; stop and ask when its scope or ceiling would be exceeded.
|
|
33
29
|
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
30
|
+
Preserve explicit constraints in every command and continuation: target accounts, location meaning,
|
|
31
|
+
roles, channels, fields, budget, exclusions and permitted side effects. For a no-phone task, exclude
|
|
32
|
+
contact and organization phone fields, phone reveal dimensions and phone lookup actions. Use an
|
|
33
|
+
explicit field allowlist and explicit reveal dimensions; never `--reveal all` or a selection depth
|
|
34
|
+
that can bring excluded data back. Phone work remains available when the user requests and authorizes it.
|
|
39
35
|
|
|
40
|
-
##
|
|
36
|
+
## Establish identity and company
|
|
41
37
|
|
|
42
|
-
|
|
43
|
-
sl config show # the endpoint: production unless someone switched it
|
|
44
|
-
sl whoami # person or application, the company it acts for, elevation, scopes
|
|
45
|
-
```
|
|
46
|
-
|
|
47
|
-
**Production (`federation.sortlist.com`) is the default environment.** Use it unless the user
|
|
48
|
-
explicitly asks for another one ("on staging", "on my local stack").
|
|
49
|
-
|
|
50
|
-
- If `sl config show` points elsewhere and the user did not ask for that environment, switch back with
|
|
51
|
-
`sl config use-production` and say so in one line: it also changes the user's own terminal. Then run
|
|
52
|
-
`sl whoami`; if the token is not a production one, log in again as in section 2.
|
|
53
|
-
- When the user asked for local or staging, switch to it the same way, and switch back to production
|
|
54
|
-
once that task is done, saying so.
|
|
55
|
-
- Do not mention the environment when it is production. **Only say where you are when it is not
|
|
56
|
-
production**, e.g. "on staging", since the answer then does not describe real data.
|
|
57
|
-
- Production is real customer data: the paid-call and write rules of section 6 apply there in full.
|
|
58
|
-
|
|
59
|
-
The configuration is shared with the user's own terminal, so it can change between two of your calls:
|
|
60
|
-
the user logging in elsewhere switches the endpoint under you. Check `sl config show` again, silently,
|
|
61
|
-
before every mutation and after any pause, not only once at the start.
|
|
62
|
-
|
|
63
|
-
Output is JSON whenever stdout is not a terminal, which is always the case from a tool call. There is
|
|
64
|
-
no need to pass `--json`.
|
|
65
|
-
|
|
66
|
-
## 2. Identity, scopes and elevation
|
|
67
|
-
|
|
68
|
-
| Command | Scopes requested | Lifetime |
|
|
69
|
-
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------- |
|
|
70
|
-
| `sl login` | `atlas/organization:read`, `atlas/reveal:read`, `outreach/channel_account:read`, `outreach/channel_account:write`, `signals/watcher:read`, `signals/watcher:write` | Refreshed silently |
|
|
71
|
-
| `sl login --elevate=sales` | the above + `atlas/*:read`, `billing/offer:*` | 30 minutes, never refreshed |
|
|
72
|
-
| `sl login --elevate` (admin) | the above + `<service>/*:read` on every service | 30 minutes, never refreshed |
|
|
73
|
-
| `sl login --elevate=superadmin` | the above + `<service>/*:*` on every service | 30 minutes, never refreshed |
|
|
74
|
-
|
|
75
|
-
- A scope is granted only when the user's account holds it, so a scope can be requested and still
|
|
76
|
-
be missing. `sl whoami` shows what was actually granted.
|
|
77
|
-
- **Log in yourself, always with `--no-browser`**: run `sl login --no-browser` (or
|
|
78
|
-
`sl login --elevate --no-browser`, …) **in the background**, read the URL and code it prints, and
|
|
79
|
-
give them to the user in one line ("Approve the login: <url>, code ABCD-EFGH"). The command keeps
|
|
80
|
-
polling until the user approves in their browser, then exits; continue the task once it has. Do not
|
|
81
|
-
ask the user to run the command themselves. Never log in with a browser tab.
|
|
82
|
-
Log out the same way: `sl logout --no-browser` (it only clears the local credentials and skips the
|
|
83
|
-
sign-out page that just says "OK"), or `sl logout --elevated` to drop only an elevation.
|
|
84
|
-
- **Never ask for `--elevate=superadmin` unless the user asked for write access that needs it.** Prefer
|
|
85
|
-
the lowest level that covers the task, and suggest `sl logout --elevated` once it is done.
|
|
86
|
-
- After a login or an elevation the schema changes. `sl schema refresh` rebuilds it at once;
|
|
87
|
-
otherwise the next command picks up the new token by itself.
|
|
88
|
-
|
|
89
|
-
### Acting as an application
|
|
90
|
-
|
|
91
|
-
An application acts for exactly one company and carries no scope by default. It reaches Atlas's
|
|
92
|
-
metered `find-contacts` and `find-organizations` only: Mercator, Signals and Outreach refuse its
|
|
93
|
-
token, and so does every `sl hermes` management command. What it reveals is charged to its company and recorded under
|
|
94
|
-
the application's name on the developer portal's Usage page rather than the person's. Act as one only when the user asks for it.
|
|
95
|
-
|
|
96
|
-
```bash
|
|
97
|
-
sl hermes applications --fields name,slug,company.slug # the applications the user can act as
|
|
98
|
-
sl use application ci # by slug, in the company the user acts for
|
|
99
|
-
sl use application acme/ci # by slug, naming the company
|
|
100
|
-
sl use application <id> # by global id
|
|
101
|
-
sl whoami # kind: application
|
|
102
|
-
sl use me # back to the person
|
|
103
|
-
```
|
|
104
|
-
|
|
105
|
-
- A slug is unique within its company and never changes when the application is renamed, so prefer
|
|
106
|
-
`<company>/<slug>`: it means the same thing whatever company `sl config` holds.
|
|
107
|
-
- The token lasts one lifetime (about an hour) and is not refreshed; `sl use application` again after.
|
|
108
|
-
- While acting as an application, Hermes refuses every `sl hermes` management command: Hermes does
|
|
109
|
-
not accept its own tokens there. Run `sl use me` first, and switch back after.
|
|
110
|
-
- Always end with `sl use me` once the task needing the application is done, and say so: the
|
|
111
|
-
session is shared with the user's terminal.
|
|
112
|
-
|
|
113
|
-
## 3. Which company a call acts for
|
|
114
|
-
|
|
115
|
-
Atlas meters reveals and searches against the company a call acts for. Which one that is, with a
|
|
116
|
-
person's token:
|
|
117
|
-
|
|
118
|
-
| You pass | Any login, elevated or not |
|
|
119
|
-
| -------------------------------------- | --------------------------- |
|
|
120
|
-
| `--company <slug\|id>` on the command | That company, for that call |
|
|
121
|
-
| Nothing, after `sl use company <slug>` | The company chosen there |
|
|
122
|
-
| Nothing | **Your personal company** |
|
|
123
|
-
|
|
124
|
-
So with no `--company` and no company chosen, every reveal Atlas records goes to the personal company, and an elevation
|
|
125
|
-
changes nothing about that. Say so when the user asks who paid; there is nothing to look up.
|
|
126
|
-
Mechanically the CLI looks the personal company up once per command and sends it as the company,
|
|
127
|
-
on every call a person makes without `--company`, so Atlas, Signals and Outreach meter it there. An
|
|
128
|
-
application carries its own company and never gets this fallback.
|
|
129
|
-
|
|
130
|
-
`sl whoami` names the company in effect and its credits and plan (`company` in its output). `sl use company` lists the user's
|
|
131
|
-
companies, with `current: true` on that one, `personal: true` on the personal one, and each one's
|
|
132
|
-
`billing`: credit balance and plan, null when billing could not be read.
|
|
133
|
-
|
|
134
|
-
- **One call for another company:** `--company <slug>`.
|
|
135
|
-
- **Every later call:** `sl use company <slug>`, only once the user chose that company, and say so in
|
|
136
|
-
one line: it also changes the user's own terminal. It refuses a company the user does not belong to.
|
|
137
|
-
`sl use company --personal` goes back to the personal company.
|
|
138
|
-
|
|
139
|
-
## 4. What the CLI offers, and how to read a command
|
|
140
|
-
|
|
141
|
-
The CLI offers an operation only when its subgraph tags it for the CLI. Today that is:
|
|
142
|
-
|
|
143
|
-
| Command | Does |
|
|
144
|
-
| ------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
|
|
145
|
-
| `sl atlas find-organizations` | A page of organizations matching a filter (section 5) |
|
|
146
|
-
| `sl atlas find-contacts` | A page of contacts matching a filter (section 5) |
|
|
147
|
-
| `sl mercator resolve-locations` | Place names to Mercator location ids (section 5, Places) |
|
|
148
|
-
| `sl mercator resolve-by-code` | A country or region by its ISO code |
|
|
149
|
-
| `sl mercator location-subtypes` | The levels a location can have |
|
|
150
|
-
| `sl hermes companies`, `sl hermes company --slug …` | The user's companies, or one with its members, invitations and billing |
|
|
151
|
-
| `sl hermes applications`, `sl hermes application --id …` | The applications the user can act as, or one with its credentials |
|
|
152
|
-
| `sl hermes create-application`, `delete-application` | Register or delete an application (section 6, Writes) |
|
|
153
|
-
| `sl hermes create-application-credential`, `revoke-application-credential` | Mint or revoke a client id and secret (section 6, Writes) |
|
|
154
|
-
| `sl hermes create-company`, `delete-company` | Manage the user's companies (section 6, Writes) |
|
|
155
|
-
| `sl hermes create-company-invitation`, `revoke-company-invitation`, `remove-company-member` | Manage a company's members (section 6, Writes) |
|
|
156
|
-
| `sl hermes company-invitation-preview`, `accept-company-invitation` | Read and redeem an invitation code |
|
|
157
|
-
| `sl hermes change-company-subscription`, `cancel-company-subscription` | Change or end the company's plan (section 6, paid) |
|
|
158
|
-
| `sl hermes create-company-billing-portal-session` | A Stripe URL to manage the card and invoices; the user opens it |
|
|
159
|
-
| `sl hermes user`, `sl hermes users` | Reads of people: `users` is privileged (`hermes/user:read`), `user` answers only privileged callers |
|
|
160
|
-
|
|
161
|
-
A company's credit balance is `sl hermes company --slug <slug> --fields billingCustomer.creditBalance`,
|
|
162
|
-
and its plan `billingCustomer.activeSubscription.plan`; both read what the user's own membership allows.
|
|
163
|
-
|
|
164
|
-
`sl operations` lists what the current token actually has, and marks every operation that requires a
|
|
165
|
-
scope as `privileged: <scopes>` (alternatives joined by `or`); its `--help` opens with the same line.
|
|
166
|
-
Nothing is privileged by name: an operation is privileged exactly when its subgraph declares a scope
|
|
167
|
-
for it, so the marks follow the schema. A user works without any scope, so a privileged operation
|
|
168
|
-
needs one from their role or an elevation (section 2), and the router hides it entirely from a
|
|
169
|
-
token that lacks it, so it can be missing from the list rather than marked. **Whenever you list or
|
|
170
|
-
suggest operations, say which are privileged and what they need.**
|
|
171
|
-
|
|
172
|
-
Signals (`sl signals …`, section 5b) and Outreach (`sl outreach …`, section 5c) have commands too,
|
|
173
|
-
privileged: `signals/watcher:read|write` and `outreach/channel_account:read|write`, which a plain
|
|
174
|
-
`sl login` requests and only some accounts are granted for now. Anything else the app does
|
|
175
|
-
(billing's own ledger and usage history, the reveal ledger) has no command: say so and stop, as the
|
|
176
|
-
rule above says. It is a backend change to tag one more operation, not something to work around.
|
|
177
|
-
|
|
178
|
-
```bash
|
|
179
|
-
sl operations --search find # invocation + owning subgraph
|
|
180
|
-
sl atlas find-contacts --help # its description, arguments and types
|
|
181
|
-
sl schema inspect ContactsFilterInput # an input object or enum used by a flag
|
|
182
|
-
```
|
|
183
|
-
|
|
184
|
-
- Arguments are kebab-case flags (`--organization-filter`). Input objects and lists take JSON:
|
|
185
|
-
`--filter '{"domain":{"in":["google.com"]}}'`.
|
|
186
|
-
- Keep output small: `--fields` takes dotted paths, relative to a record when the result is a page
|
|
187
|
-
(`jobTitle`, `organization.name`, not `contacts.nodes.jobTitle`); the page's `pageInfo` comes along
|
|
188
|
-
on its own. `--total-count` adds the total on other services' lists; never pass it to an Atlas
|
|
189
|
-
command, where counting every match is too slow. In a terminal a table shows a page only as a
|
|
190
|
-
count of its entries, so pass `--json` there; from a tool call the output is JSON already.
|
|
191
|
-
`--exclude` drops heavy fields, and `--depth` controls how deep nested objects are selected
|
|
192
|
-
(default 0) and never selects a deprecated field; name one in `--fields` to get it anyway.
|
|
193
|
-
- A mutation prints the object it returns, and its `--fields` name that object's fields:
|
|
194
|
-
`create-company --fields id,slug`, not `company.id`.
|
|
195
|
-
- Operation descriptions carry the business rules. Read `--help` before a mutation, not after.
|
|
196
|
-
|
|
197
|
-
## 5. Atlas: finding organizations and contacts
|
|
198
|
-
|
|
199
|
-
### What Atlas holds
|
|
200
|
-
|
|
201
|
-
- **Organization**: a company, keyed by its primary `domain` (unique). Name, website, description,
|
|
202
|
-
industry, Mercator `locations`, `companySize` and `annualRevenue` as `[min, max]` ranges, foundedYear,
|
|
203
|
-
LinkedIn, phone, logo, offices, and a `confidenceScore` (0 to 1) merged from its sources.
|
|
204
|
-
- **Contact**: a person at one organization (`contact.organization`). Job title, function and level,
|
|
205
|
-
city, country and Mercator `locations`, `confidenceScore`, `profileCompleteness`. Then the **reach
|
|
206
|
-
fields, which are paid** (see Reveals): name, avatar and career entries (`CONTACT_IDENTITY`),
|
|
207
|
-
`emailAddress` / `emailStatus` / `emailPattern` (`CONTACT_EMAIL_ADDRESS`), `linkedinUrl`
|
|
208
|
-
(`CONTACT_LINKEDIN_URL`), `phone` (`CONTACT_PHONE_NUMBER`).
|
|
209
|
-
|
|
210
|
-
### How a find works
|
|
211
|
-
|
|
212
|
-
`find-organizations` and `find-contacts` are searches: the mutation only answers `{status: "received"}`,
|
|
213
|
-
and the page arrives on a subscription. **Always pass `--wait`.** It subscribes, sends the mutation,
|
|
214
|
-
and prints the page once Atlas has finished filling it.
|
|
38
|
+
Before the first app operation, inspect:
|
|
215
39
|
|
|
216
40
|
```bash
|
|
217
|
-
sl
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
sl atlas find-contacts --organization-filter '{"domain":{"eq":"acme.com"}}' --wait \
|
|
221
|
-
--fields jobTitle,jobLevel
|
|
41
|
+
sl config show
|
|
42
|
+
sl whoami
|
|
222
43
|
```
|
|
223
44
|
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
come back whatever `--fields` names, so `--fields` only lists record fields and the spend report
|
|
247
|
-
always has what it needs.
|
|
248
|
-
|
|
249
|
-
### Filters and sorting
|
|
250
|
-
|
|
251
|
-
- **Scalar operators:** strings take `eq`, `in`, `notEq`, `notIn`, `presence`, `blank`; numbers take
|
|
252
|
-
`eq`, `gt`, `gteq`, `lt`, `lteq`; ranges (`companySize`) take `overlaps`, `containedBy`, `contains`.
|
|
253
|
-
Any of them can add `"allowBlank": true` to also keep rows where the value is missing.
|
|
254
|
-
- **Normalized matching:** `domain` drops the scheme, `www.` and path; `name` drops case, accents,
|
|
255
|
-
punctuation and legal forms (`Sortlist NV/SA` finds `Sortlist`); `linkedinUrl` compares vanity
|
|
256
|
-
slugs; `emailAddress` is trimmed and lowercased. Each is still an exact match after that.
|
|
257
|
-
- **Semantic filters** (`description`, `industry` on organizations, `jobTitle` on contacts): a list
|
|
258
|
-
of `{"queries":[…],"match":"INCLUDED_STRICT"}` entries. Queries inside an entry are OR, several
|
|
259
|
-
entries are AND. `INCLUDED_LOOSE` widens, `EXCLUDED_*` removes. List related terms and translations
|
|
260
|
-
(`["CMO","Marketing Director","Directeur Marketing"]`), one concept per query.
|
|
261
|
-
- **Size (organizations):** `"companySize":{"overlaps":[0,100]}`, or `[1000]` for 1000 and above.
|
|
262
|
-
- **Sorting:** `--sort '[{"field":"CONFIDENCE_SCORE"}]'`, `NAME`, `CREATED_AT`, or by closeness to a
|
|
263
|
-
text with `INDUSTRY_DISTANCE` / `DESCRIPTION_DISTANCE` (and `JOB_TITLE_DISTANCE` on contacts). **A
|
|
264
|
-
distance sort defaults to descending, which puts the least similar first**: always pass
|
|
265
|
-
`"direction":"ASC"`, e.g. `[{"field":"INDUSTRY_DISTANCE","query":"digital marketing agency","direction":"ASC"}]`.
|
|
266
|
-
- `sl schema inspect ContactsFilterInput` / `OrganizationsFilterInput` lists every field.
|
|
267
|
-
|
|
268
|
-
### Places
|
|
269
|
-
|
|
270
|
-
Atlas does not take place names. Every geographic filter is `divisionIds`: Mercator location ids.
|
|
271
|
-
So a search by place is always two steps, **resolve the place in Mercator, then filter Atlas**.
|
|
45
|
+
The normal default environment is production. Respect an
|
|
46
|
+
explicit environment request and verify that the configured endpoint matches it. If the existing
|
|
47
|
+
configuration conflicts with the task, resolve that mismatch before using data or changing state.
|
|
48
|
+
Do not silently switch a configured environment to production. State a non-production environment
|
|
49
|
+
in the result. Environment changes and logins affect the user's terminal too; preserve the original
|
|
50
|
+
configuration and restore a temporary change after the task. Inspect `sl config --help` before using
|
|
51
|
+
environment-switch commands: `use-production`, `use-staging` and `use-local` are dev-build features.
|
|
52
|
+
|
|
53
|
+
With a person's token, company precedence is `--company <slug|id>` for this call, then the saved
|
|
54
|
+
company, then the personal company fallback. With an application's token, the application's company
|
|
55
|
+
is authoritative. Prefer explicit `--company` on task calls so the task does not change the user's
|
|
56
|
+
default. `sl use company` without a value lists companies and billing without selecting one.
|
|
57
|
+
Use `sl use company <slug>` only for an authorized persistent change and say that it affects later
|
|
58
|
+
terminal commands. `--company-id`, when present, identifies the company an operation is about;
|
|
59
|
+
it does not replace `--company`, which identifies the caller's acting and billing context.
|
|
60
|
+
|
|
61
|
+
Verify the intended company before spending, creating a watcher/account or sending. Recheck identity
|
|
62
|
+
and configuration after a pause or an unexpected context change and before consequential writes.
|
|
63
|
+
For login, scopes, application sessions, Hermes management and secrets, read
|
|
64
|
+
[identity-and-accounts.md](references/identity-and-accounts.md).
|
|
65
|
+
|
|
66
|
+
## Discover before constructing commands
|
|
272
67
|
|
|
273
68
|
```bash
|
|
274
|
-
sl
|
|
275
|
-
sl
|
|
276
|
-
|
|
69
|
+
sl operations --search find
|
|
70
|
+
sl atlas find-contacts --help
|
|
71
|
+
sl schema inspect ContactsFilterInput
|
|
72
|
+
sl schema inspect Contact
|
|
277
73
|
```
|
|
278
74
|
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
`--
|
|
304
|
-
`
|
|
305
|
-
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
|
|
314
|
-
|
|
315
|
-
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
|
|
321
|
-
|
|
322
|
-
|
|
323
|
-
|
|
324
|
-
|
|
325
|
-
|
|
326
|
-
|
|
327
|
-
|
|
328
|
-
|
|
329
|
-
|
|
330
|
-
|
|
331
|
-
|
|
332
|
-
|
|
333
|
-
|
|
334
|
-
|
|
335
|
-
|
|
336
|
-
|
|
337
|
-
|
|
338
|
-
|
|
339
|
-
|
|
340
|
-
|
|
341
|
-
|
|
342
|
-
|
|
343
|
-
|
|
344
|
-
|
|
345
|
-
|
|
346
|
-
|
|
347
|
-
|
|
348
|
-
|
|
349
|
-
-
|
|
350
|
-
|
|
351
|
-
|
|
352
|
-
|
|
353
|
-
|
|
354
|
-
|
|
355
|
-
|
|
356
|
-
|
|
357
|
-
|
|
358
|
-
|
|
359
|
-
|
|
360
|
-
|
|
361
|
-
|
|
362
|
-
|
|
363
|
-
|
|
364
|
-
|
|
365
|
-
each billed again (ask first, it spends credits).
|
|
366
|
-
- **Watchers are immutable and shared**: the same input and ICP reuse an existing watcher. To change
|
|
367
|
-
one, create a new one and delete the old. `update-watcher-lead-caps` and `delete-watcher` affect
|
|
368
|
-
every consumer of a shared watcher: check `watchers` first.
|
|
369
|
-
- **When leads arrive** depends on the watcher's provider, not on the definition's `triggers`. Read
|
|
370
|
-
`sl signals watchers --fields id,providerStates.providerSlug,providerStates.nextRunAt`: a
|
|
371
|
-
`nextRunAt` means a scheduled provider, which `trigger-watcher` runs at once; null means the
|
|
372
|
-
provider pushes on its own and `trigger-watcher` does nothing. `linkedin-reactions` lists
|
|
373
|
-
`SCHEDULE` but runs on a pushing provider: its first leads came about 30 minutes after creation.
|
|
374
|
-
Most other definitions deliver over hours or days. Tell the user which, and check back.
|
|
375
|
-
- `--fields` takes a connection's counters next to its rows, e.g.
|
|
376
|
-
`--fields id,events.total,events.discarded,events.observedAt`. `discardReason` and the discarded
|
|
377
|
-
slice need a service-wide read scope (`signals/*:read`): a plain login gets an error for them, not an empty
|
|
378
|
-
value.
|
|
379
|
-
|
|
380
|
-
**Reading leads**
|
|
381
|
-
|
|
382
|
-
```bash
|
|
383
|
-
sl signals watcher-events --filter '{"watcherId":{"eq":"<id>"},"qualifiedAt":{"gt":"<last seen>"}}' \
|
|
384
|
-
--first 20 --fields id,qualifiedAt,occurredAt,payload,contact.node.id
|
|
385
|
-
```
|
|
386
|
-
|
|
387
|
-
- **Never select a contact's reach fields on `watcher-events`** (`contact.node.firstName`,
|
|
388
|
-
`emailAddress`, `phone`, `linkedinUrl`, or a `--depth` that reaches them): with no `reveal:`
|
|
389
|
-
argument the event reveals and charges every reach field selected. Select `contact.node.id`, show
|
|
390
|
-
the leads, then reveal what the user picks with `sl atlas find-contacts --filter
|
|
391
|
-
'{"id":{"in":[…]}}' --reveal … --wait` (section 6).
|
|
392
|
-
- **Don't handle a lead twice.** Read with `--filter '{"acknowledged":{"eq":"UNACKNOWLEDGED"}}'`
|
|
393
|
-
and, once the user has decided about a lead (contacted it or skipped it),
|
|
394
|
-
`sl signals acknowledge-watcher-events --ids '["<event id>",…]'`. Not when it is merely shown.
|
|
395
|
-
- `payload` follows `canonicalEventSchema`: what happened, when, to which company. Quote it; never
|
|
396
|
-
invent a score or a probability.
|
|
397
|
-
- Say "no lead yet" only for a watcher that is `PROVISIONED` and `ACTIVE`. Tell it apart from a
|
|
398
|
-
watcher still provisioning, paused, billing paused, or out of its caps.
|
|
399
|
-
- Each lead costs 20, 50 or 100 credits depending on the definition, charged when delivered.
|
|
400
|
-
- Watchers keep running after the conversation. At the end of a task, list the ones created and ask
|
|
401
|
-
whether to keep them (`delete-watcher --id <id>` stops one).
|
|
402
|
-
|
|
403
|
-
## 5c. Outreach: accounts and actions
|
|
404
|
-
|
|
405
|
-
Outreach sends **one action at a time** from an account it holds for the user: a LinkedIn
|
|
406
|
-
invitation, message, profile visit or lookup, or an email. There are no campaigns or sequences: a
|
|
407
|
-
campaign is a plan the agent holds and runs as single actions (the `sortlist-go-to-market` skill).
|
|
408
|
-
|
|
409
|
-
```bash
|
|
410
|
-
sl outreach outbound-channel-accounts --fields id,channel,provider,status,externalId
|
|
411
|
-
```
|
|
412
|
-
|
|
413
|
-
- Use an account that is `RUNNING`. Connecting a new one needs the account owner: a hosted sign-in
|
|
414
|
-
link (`authenticate-outbound-channel-account`) they open themselves. Email accounts can't be
|
|
415
|
-
connected from the CLI yet.
|
|
416
|
-
- **Connecting LinkedIn from the owner's browser** (provider `LINKEDIN_DIRECT`): the account runs on the
|
|
417
|
-
owner's own browser session. Ask first: it signs Outreach in as them, and the owner must be at the
|
|
418
|
-
computer to sign in.
|
|
419
|
-
1. Create the account, acting for the company that pays:
|
|
420
|
-
`sl outreach create-outbound-channel-account --channel LINKEDIN --provider LINKEDIN_DIRECT
|
|
421
|
-
--external-id <who it is for> --fields channelAccount.id,channelAccount.status`. No webhook is
|
|
422
|
-
needed: events are read with the CLI.
|
|
423
|
-
2. Run `sl outreach connect-linkedin <account id> <country code>` (the owner's country, e.g. `BE`)
|
|
424
|
-
in the background. It opens Chrome, Edge, Brave or Chromium on linkedin.com/login in a fresh
|
|
425
|
-
profile, prints "A browser window is open…", waits up to 10 minutes (`--timeout <minutes>`)
|
|
426
|
-
for the owner to sign in, verification code included, then sends the session to Outreach itself
|
|
427
|
-
and deletes the profile.
|
|
428
|
-
3. As soon as that line appears, tell the owner to sign in in that window. The command ends with
|
|
429
|
-
`Connected: <name> is RUNNING`, or Outreach's refusal (`credentials.rejected`: run it again).
|
|
430
|
-
- **Never read, print or ask for the cookie yourself**, and never ask the owner to paste it: it is
|
|
431
|
-
their whole LinkedIn login. The command is the only path, and it never shows the value.
|
|
432
|
-
- It needs a desktop session on the owner's computer (macOS, Windows or Linux): not over SSH, in a
|
|
433
|
-
headless container or in WSL without a display. A snap or Flatpak Chromium cannot be driven; it
|
|
434
|
-
says so, and `CHROME_PATH` picks another browser.
|
|
435
|
-
- With this provider, acceptances and replies arrive within about 10 minutes (Outreach checks the
|
|
436
|
-
inbox every 10 minutes) instead of at once. A session LinkedIn ends turns the account
|
|
437
|
-
`DISCONNECTED`: run the command again on the same account id.
|
|
438
|
-
- **The company the call that creates the account acts for pays for every LinkedIn action on it**
|
|
439
|
-
(section 3). Create it while acting for the company the user chose.
|
|
440
|
-
- **Find the LinkedIn member id** with a silent lookup (2 credits, nobody is notified):
|
|
441
|
-
`sl outreach perform-outbound-channel-action --channel-account-id <id> --external-id lookup-<slug>
|
|
442
|
-
--action '{"linkedinLookupProfile":{"identifier":"<public identifier>"}}' --wait`. The identifier is
|
|
443
|
-
the **last segment of the profile URL** (`jane-doe-1a2b3c` for `https://www.linkedin.com/in/jane-doe-1a2b3c/`),
|
|
444
|
-
or a member id: never the full URL, which LinkedIn refuses with a 403 (`FAILED`, nothing charged). Its
|
|
445
|
-
`result` carries `member_id` (the `ACoAA…` id every other action takes), `network_distance` (`SELF`
|
|
446
|
-
… `OUT_OF_NETWORK`) and `pending_invitation`. Don't invite a first-degree connection or someone with a
|
|
447
|
-
pending invitation: LinkedIn doesn't always refuse it.
|
|
448
|
-
- **Act**: `--action '{"linkedinInvite":{"memberId":"…","message":"…"}}'` (note 300 characters
|
|
449
|
-
max), `{"linkedinSendMessage":{"memberId":"…","text":"…"}}`, `{"linkedinVisit":{"memberId":"…"}}`,
|
|
450
|
-
`{"linkedinCancelInvitation":{"invitationId":"…"}}`.
|
|
451
|
-
- **Always pass a meaningful `--external-id`** (`<prospect>-step-<n>`): the same id returns the same
|
|
452
|
-
action instead of sending twice. After a timeout, read `outbound-channel-actions` before acting again.
|
|
453
|
-
- A free LinkedIn account gets only a handful of invitations with a note per month: LinkedIn refuses
|
|
454
|
-
more as `not_allowed`. Offer to send without a note rather than retrying.
|
|
455
|
-
- `--wait` follows the action until it settles; its `--fields` then name the result's fields
|
|
456
|
-
(`channelAction.state,channelAction.result`). On a timeout (exit code 5), or without it, read
|
|
457
|
-
`sl outreach outbound-channel-action --id <id> --fields state,error,result`. States: `PENDING`, `EXECUTING`, `COMPLETED`, `FAILED`,
|
|
458
|
-
`CANCELLED`. A failed action is never retried by the gateway.
|
|
459
|
-
- **Refused by billing**: the action is `FAILED` with `error.code` `insufficient_credits` and
|
|
460
|
-
`error.billing_code` saying why (`INSUFFICIENT_CREDITS`, `NO_BILLING_CUSTOMER`,
|
|
461
|
-
`PRODUCT_NOT_BILLED`). LinkedIn was never reached and nothing was charged. `billing_unavailable`
|
|
462
|
-
means billing was down for 24 hours. Stop the plan, report it with the company's balance
|
|
463
|
-
(`sl use company`), and resend only after a new yes, under a new `--external-id`.
|
|
464
|
-
- **Pacing**: 50 invitations and 150 messages a day per LinkedIn member. Actions queue; `scheduledAt`
|
|
465
|
-
says when one will run. `cancel-outbound-channel-actions --channel-account-id <id> --channel-action-ids '[…]'` stops pending ones.
|
|
466
|
-
- **Replies and acceptances**: `sl outreach outbound-channel-events --channel-account-id <id> --fields id,eventType,occurredAt,payload`
|
|
467
|
-
(`invitation.accepted`, `message.received`…), `linkedin-chats`, `linkedin-chat-messages`.
|
|
468
|
-
`--filter '{"acknowledged":{"eq":"UNACKNOWLEDGED"}}'` returns only what is left; acknowledge what was
|
|
469
|
-
acted on with `sl outreach acknowledge-outbound-channel-events --channel-account-id <id> --ids
|
|
470
|
-
'["<event id>",…]'`. Outreach reads only the conversations it is part of: chats it started, and
|
|
471
|
-
people the account invited or is writing to. A message someone sends the account out of the blue
|
|
472
|
-
never appears, so start the conversation with `linkedinSendMessage` first.
|
|
473
|
-
- Costs: invitation or message 5 credits, visit or lookup 2, withdrawal 1. Email is free.
|
|
474
|
-
- Every action reaches a real person in the user's name: section 6 applies to each one.
|
|
475
|
-
|
|
476
|
-
## 6. Paid calls, writes and go-aheads
|
|
477
|
-
|
|
478
|
-
### Which calls are paid
|
|
479
|
-
|
|
480
|
-
| Call | What costs |
|
|
481
|
-
| ------------------------------------------------------- | ------------------------------------------------------------------ |
|
|
482
|
-
| `find-contacts` or `find-organizations` with `--reveal` | Each dimension `REVEALED`, per record, and the lookups it triggers |
|
|
483
|
-
| `find-contacts` that may look further (section 5) | Provider searches on the user's behalf |
|
|
484
|
-
| `find-organizations` by `domain` `eq` Atlas lacks | One domain lookup |
|
|
485
|
-
| `signals create-watcher` | Every lead it delivers: 20, 50 or 100 credits, until deleted |
|
|
486
|
-
| `signals watcher-events` selecting contact reach fields | A reveal per field selected (avoid: section 5b) |
|
|
487
|
-
| `outreach perform-outbound-channel-action` | 1 to 5 credits per LinkedIn action, and a message to a real person |
|
|
488
|
-
| `hermes change-company-subscription` | An upgrade invoices the company's card at once, prorated |
|
|
489
|
-
| `hermes create-application-credential` | Nothing, but it is a write that hands out a secret (see Writes) |
|
|
490
|
-
|
|
491
|
-
Everything else (Mercator, Hermes reads such as `companies` and `applications`, a find without
|
|
492
|
-
`--reveal` that Atlas answers from its database) is free and can be run without asking.
|
|
493
|
-
|
|
494
|
-
### Before a paid call: always ask
|
|
495
|
-
|
|
496
|
-
**Never run a paid call without an explicit yes from the user, every time, even after an earlier
|
|
497
|
-
approval and even for a retry.** Ask with the `AskUserQuestion` tool, so the user picks an answer
|
|
498
|
-
instead of typing one. Never ask in prose.
|
|
499
|
-
|
|
500
|
-
- **Question:** one line, what is bought, the most it can cost in credits, who pays (section 3: the
|
|
501
|
-
`--company`, else the personal company). For example: "Reveal names +
|
|
502
|
-
emails of 10 contacts (up to 20 credits, charged to Personal)?"
|
|
503
|
-
- **Options**, 2 to 4, each a real alternative with its cost in the description:
|
|
504
|
-
- the call as proposed, first, with the exact command in its `preview`;
|
|
505
|
-
- cheaper variants when they exist, each with its own command in `preview`: one dimension only
|
|
506
|
-
("Emails only, up to 10 credits"), fewer records, or a different company;
|
|
507
|
-
- "Don't reveal": continue with what the find without `--reveal` already shows.
|
|
508
|
-
- Mention already-owned records in the question only when there are some ("3 already owned, free").
|
|
509
|
-
Check with a find without `--reveal` beforehand when it matters: their `reveals` say `OWNED`.
|
|
510
|
-
- If the tool is not available, fall back to one line plus the command, and wait.
|
|
511
|
-
|
|
512
|
-
Then wait for the answer and run exactly the option picked. An answer about one call does not cover the
|
|
513
|
-
next one, with one exception: a **bounded plan**. When the user approves a plan that names the exact
|
|
514
|
-
people, the exact dimensions or actions, and a maximum in credits (for example a campaign's first
|
|
515
|
-
step for five named prospects, at most 25 credits), run it without asking again for each call,
|
|
516
|
-
stop at the maximum, and ask again for anything outside it: another person, another field, another
|
|
517
|
-
step, or more credits. A lower actual cost (already owned) needs no new question. A budget alone
|
|
518
|
-
selects nobody: show who and what first.
|
|
519
|
-
|
|
520
|
-
### After a paid call: report the spend
|
|
521
|
-
|
|
522
|
-
Report it from the pages themselves, in two or three lines, no more, starting with the total:
|
|
523
|
-
|
|
524
|
-
```
|
|
525
|
-
Credits used: 19 (11 names, 8 emails) · Personal
|
|
526
|
-
6 contacts already owned, free · 3 emails unavailable
|
|
527
|
-
Free to re-read until 2026-12-23
|
|
528
|
-
```
|
|
529
|
-
|
|
530
|
-
The total is the sum of `credits.used` over every page the task read; the per-dimension split comes
|
|
531
|
-
from `credits.byDimension`, and the owned and unavailable counts from each edge's `reveals`. Leave out
|
|
532
|
-
what is zero. Credits are units, not money: never convert them into an amount. Atlas charges them, and so do
|
|
533
|
-
Signals (per lead) and Outreach (per LinkedIn action).
|
|
534
|
-
|
|
535
|
-
### Writes
|
|
536
|
-
|
|
537
|
-
- **Before any mutation other than a find, show the user the exact command and wait for approval**,
|
|
538
|
-
on every environment.
|
|
539
|
-
- Ask with `AskUserQuestion`, the exact command in the option's `preview`, as for a paid call. These
|
|
540
|
-
cannot be undone, so say so in the question and never batch two of them under one yes:
|
|
541
|
-
`delete-company`, `delete-application`, `remove-company-member` (it also revokes every credential
|
|
542
|
-
that member created), `revoke-application-credential` (new tokens stop at once), and
|
|
543
|
-
`cancel-company-subscription` (ends the plan immediately and forfeits the rest of the period).
|
|
544
|
-
- `create-company-invitation` hands whoever redeems the code full control of the company's
|
|
545
|
-
applications and credentials. Confirm who it is for, and never paste the code anywhere but to the
|
|
546
|
-
user.
|
|
547
|
-
- `accept-company-invitation` joins the user to another company: run
|
|
548
|
-
`company-invitation-preview` first and show what the code is for.
|
|
549
|
-
A code is spent by whoever redeems it, a member of the company included, so never accept one
|
|
550
|
-
meant for someone else.
|
|
551
|
-
- `create-application-credential` returns the client id and the secret, the secret exactly once.
|
|
552
|
-
Hand it to the user to store, and never write it into a file or repeat it later in the
|
|
553
|
-
conversation. The credential's id, which `revoke-application-credential` takes, is listed by
|
|
554
|
-
`sl hermes application --id <application id> --fields credentials.id,credentials.name`.
|
|
555
|
-
- `create-company-billing-portal-session` returns a Stripe URL: give it to the user to open, and do
|
|
556
|
-
not open it yourself. Subscribing to a plan has no command. It happens on the developer portal's
|
|
557
|
-
Billing page.
|
|
558
|
-
- `sl token` prints the bearer token. Never echo it into a reply or a file.
|
|
559
|
-
|
|
560
|
-
## 7. Reading errors
|
|
561
|
-
|
|
562
|
-
| Error | Meaning | What to do |
|
|
563
|
-
| ----------------------------------------------------------------- | ----------------------------------------------------------- | -------------------------------------------------------------------------------------- |
|
|
564
|
-
| `unknown command '<name>'` | Not offered to the CLI, or the token cannot see it | `sl operations`; if it is missing there, check `sl whoami` for a scope or an elevation |
|
|
565
|
-
| `No scope granted for: <services>` (at login) | The account holds none of those scopes | Access granted to the account, not a CLI setting; do not retry |
|
|
566
|
-
| `<service> refused this request: it names no company to act for` | No company could be resolved, not even the personal one | Pass `--company <slug>` |
|
|
567
|
-
| `<service> refused to act for your personal company` | The fallback of section 3 was refused | Pass `--company <slug>` from `sl use company` |
|
|
568
|
-
| `Subgraph http callback status code not ok` (a subscription) | The subgraph refused the subscription; production hides why | Retry with `--company <slug>` |
|
|
569
|
-
| `No result within <n>s` / `The page was still filling` (exit `5`) | Nothing, or not all of it, arrived in time | Run again with a longer `--wait <seconds>`; a search lives one hour |
|
|
570
|
-
| `<service> refused to act for company <x>` | The user is not a member of that company | Pick one from `sl use company` |
|
|
571
|
-
| `INVALID_INTERACTION` with `details.after` expired | The cursor's search expired or belongs to someone else | Start a new search without `after` |
|
|
572
|
-
| `You are not logged in` / `session has expired` | No usable token | Log in again (section 2) |
|
|
573
|
-
| A `sl hermes` management command refused while acting as an app | Hermes does not accept its own tokens for management | `sl use me`, run it, then `sl use application …` again if still needed |
|
|
574
|
-
| `No application "<slug>" in <company>` | No application by that slug in that company | `sl hermes applications` lists them with their companies |
|
|
575
|
-
| `INSUFFICIENT_CREDITS` | Too few credits for the reservation, or no billing account | Fewer records or dimensions; `sl use company` shows each company's credits |
|
|
576
|
-
| Outreach `rate_limited` / account `pausedUntil` | LinkedIn refused; the account is paused | Wait; never resend with a new external id |
|
|
577
|
-
| Outreach `account_disconnected` | The account lost its session | The owner reconnects it; nothing to retry |
|
|
578
|
-
| `Could not reach <endpoint>` | Nothing listening (local stack down) or a network issue | Check `sl config show`; for local, the Docker stack must be running |
|
|
579
|
-
|
|
580
|
-
Exit codes: `1` a GraphQL or business error, `2` no usable session, `3` endpoint unreachable or an HTTP
|
|
581
|
-
failure, `4` the token or the acting company was refused, `5` a subscription or `--wait` timed out.
|
|
582
|
-
Set `SL_DEBUG=1` to print the query, variables and response of a failing call.
|
|
75
|
+
Use `sl operations` for the actual caller's capabilities. Privileged operations show their required
|
|
76
|
+
scopes when visible; a missing operation may be hidden for this token. Do not infer customer access
|
|
77
|
+
from an elevated demo account, a generic command list or an application's success in another service.
|
|
78
|
+
Explain relevant missing scopes rather than promising an unavailable workflow. Read `--help` before
|
|
79
|
+
a mutation and inspect the exact input, enum and output types named there when constructing unfamiliar
|
|
80
|
+
filters or selections. Do not invent fields such as `countryCode`, filters, or recovery flags.
|
|
81
|
+
`sl schema refresh` refreshes discovery after identity or permissions change.
|
|
82
|
+
|
|
83
|
+
Structured input objects and lists are JSON, with kebab-case flags. Output is JSON when stdout is
|
|
84
|
+
not a terminal. Use `--fields` for a small, explicit selection: page fields are relative to a record,
|
|
85
|
+
such as `jobTitle,organization.node.domain`, not `contacts.nodes.jobTitle`. Inspect wrapper types
|
|
86
|
+
on nested relations: `Contact.organization` can be a revealed edge whose record is under `node`.
|
|
87
|
+
Mutation fields refer to the
|
|
88
|
+
returned object, such as `id,slug`, or the subscription result when using `--wait`. Connection
|
|
89
|
+
metadata, page status and reveal reports are included when present. Avoid broad `--depth` selections
|
|
90
|
+
on metered contact relations, especially Signals leads.
|
|
91
|
+
|
|
92
|
+
## Find, verify and continue
|
|
93
|
+
|
|
94
|
+
Read [atlas.md](references/atlas.md) for filters, geography, reveals and pagination before Atlas work.
|
|
95
|
+
Start with a small preview using `--reveal none` and verified fields. A null locked name or description
|
|
96
|
+
is not evidence that the record does not exist. Separate matching the requested business and role from
|
|
97
|
+
data availability, reachability and freshness. A semantic match or a confidence score is not proof of fit.
|
|
98
|
+
|
|
99
|
+
Use `--wait` on a new find so the CLI subscribes before submitting it. `FILLING` is provisional;
|
|
100
|
+
`COMPLETE` means the page stopped filling, not that every row meets the commercial brief.
|
|
101
|
+
Keep the company, caller, `externalId`, filters, page cursor, status and constraints for continuation.
|
|
102
|
+
|
|
103
|
+
On timeout (exit 5), the request may still complete. Preserve the last output and `externalId`.
|
|
104
|
+
**Do not rerun the find to wait**, even with the same `externalId` or a longer `--wait`: without
|
|
105
|
+
`page.after`, it submits a new search. Discover an exposed read or subscription for that result and
|
|
106
|
+
inspect its help before using it. If no such command is available, report the pending or partial
|
|
107
|
+
result and the recovery limitation. A new search is a separate decision within the user's authorized
|
|
108
|
+
scope and cost ceiling, not a silent retry. Do not present a next-page cursor as a way to recover the
|
|
109
|
+
missing first page.
|
|
110
|
+
|
|
111
|
+
## Costs and permission
|
|
112
|
+
|
|
113
|
+
Read [billing-and-permissions.md](references/billing-and-permissions.md) before quoting a paid
|
|
114
|
+
operation, revealing data, changing billing, or reporting spend. Three quantities differ:
|
|
115
|
+
|
|
116
|
+
- Atlas reveal units in `credits.used` and `credits.byDimension` count dimensions revealed per record.
|
|
117
|
+
- Customer billing credits apply the current price per dimension or action. They are not the raw
|
|
118
|
+
reveal-unit total, and an account balance does not supply the price list.
|
|
119
|
+
- Provider work can cost Sortlist upstream even without a customer reveal. A no-reveal preview does
|
|
120
|
+
not establish zero provider cost. Do not add an approval hurdle to ordinary requested sourcing merely
|
|
121
|
+
because of this internal cost; honor a stricter user requirement for zero total cost by explaining
|
|
122
|
+
that a stock-only/provider-free execution mode must be verified and may be unavailable.
|
|
123
|
+
|
|
124
|
+
For paid work, quote from the [price list](references/billing-and-permissions.md#prices) with its
|
|
125
|
+
date, and name the payer before execution. If an item is not on it, say that its price and the
|
|
126
|
+
credit ceiling are unknown, and continue with a bounded no-reveal preview within the user's cost
|
|
127
|
+
constraints, or prepare the paid command for review. Do not execute an unbounded paid call.
|
|
128
|
+
|
|
129
|
+
Execute authorized paid work or writes under their concrete approved scope. A bounded approval must
|
|
130
|
+
name the selected records or selection rule, dimensions/actions, company, maximum customer credits,
|
|
131
|
+
and, for recurring work, duration and stop conditions. A budget alone selects nobody and authorizes
|
|
132
|
+
no message. Obtain a new decision for an added recipient, dimension, step, duration or higher ceiling.
|
|
133
|
+
Before approval is needed, prepare the actual command or plan so it is reviewable. Report observed
|
|
134
|
+
units separately from verified or estimated billing credits and mark incomplete accounting as unknown.
|
|
135
|
+
|
|
136
|
+
## Conditional workflows
|
|
137
|
+
|
|
138
|
+
- For Signals definitions, ICP, caps, lead polling, billing pauses and shared watcher lifecycle, read
|
|
139
|
+
[signals.md](references/signals.md). An ongoing watcher requires an approved duration, caps and
|
|
140
|
+
stopping method; it continues after the chat.
|
|
141
|
+
- For LinkedIn account connection, individual actions, idempotency, pacing, replies and failures,
|
|
142
|
+
read [outreach.md](references/outreach.md). Outreach offers individual actions, not a campaign
|
|
143
|
+
scheduler. A plan for a future action is not evidence that it is scheduled.
|
|
144
|
+
- For Hermes company membership, invitations, applications, credentials and subscriptions, read
|
|
145
|
+
[identity-and-accounts.md](references/identity-and-accounts.md). Keep secrets out of files and logs.
|
|
146
|
+
|
|
147
|
+
## Errors
|
|
148
|
+
|
|
149
|
+
| Error | Response |
|
|
150
|
+
| --- | --- |
|
|
151
|
+
| Unknown command or missing operation | Check `sl operations`, identity and relevant scopes; do not bypass the CLI. |
|
|
152
|
+
| Invalid field/argument or no usable session (exit 2) | Read the error: fix input/selection from help and schema before submission, or use the login flow only for a session error. |
|
|
153
|
+
| Company/token refused (exit 4) | Verify caller, membership and intended `--company`; do not retry against another payer silently. |
|
|
154
|
+
| `INVALID_INTERACTION`, expired `after` | The previous search cannot be paginated; consider a new search explicitly within scope and budget. |
|
|
155
|
+
| Subscription timeout or still filling (exit 5) | Preserve context and use the recovery rules above. |
|
|
156
|
+
| `INSUFFICIENT_CREDITS` | Stop paid work, report the payer and balance if readable, and revise scope or funding with the user. |
|
|
157
|
+
| Endpoint unreachable (exit 3) | Check endpoint and connectivity; do not switch environments to make an error disappear. |
|
|
158
|
+
|
|
159
|
+
Exit 1 covers GraphQL or business errors. `SL_DEBUG=1` prints queries, variables and responses;
|
|
160
|
+
use it only when needed and do not expose secrets or restricted contact data in a shared log.
|