@sortlist/cli 0.57.0 → 0.59.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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sortlist/cli",
3
- "version": "0.57.0",
3
+ "version": "0.59.0",
4
4
  "description": "Sortlist platform CLI — GraphQL federation client",
5
5
  "repository": {
6
6
  "type": "git",
@@ -19,6 +19,7 @@
19
19
  "files": [
20
20
  "bin/",
21
21
  "dist/",
22
+ "skills/",
22
23
  ".published"
23
24
  ],
24
25
  "scripts": {
@@ -0,0 +1,582 @@
1
+ ---
2
+ name: sortlist-cli
3
+ description: Reaches the Sortlist app through the `sl` CLI — finding organizations and contacts in Atlas, revealing their details, resolving places in Mercator, watching buying signals and reading leads in Signals, connecting LinkedIn and email accounts and sending single actions through Outreach, and managing the user's account in Hermes (companies, members and invitations, applications and their credentials, the company's subscription), including acting as an application by its slug. The CLI offers only the operations the backend tags for it, grouped by service (`sl atlas …`, `sl mercator …`, `sl signals …`, `sl outreach …`, `sl hermes …`). Covers which environment and identity it acts as, when to elevate, how Atlas's find searches, filters, places and reveals work, and which calls need the user's go-ahead first. Use whenever a task needs what the app itself says or does, or the user asks to "watch for companies that raise funds", "send a LinkedIn invitation", "look up an organization", "find contacts in <place>", "list the contacts of <company>", "find agencies doing <activity>", "call the API", "use sl".
4
+ user-invocable: true
5
+ ---
6
+
7
+ # Sortlist CLI
8
+
9
+ `sl` is a client for the Sortlist GraphQL federation. It introspects the supergraph with the caller's
10
+ token and registers a command for every operation the backend tags for the CLI and the token may see,
11
+ grouped under the service that serves it: `sl atlas find-contacts`, `sl mercator resolve-locations`.
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.
15
+
16
+ **Apply this skill silently.** When it loads or reloads, do not announce it, restate its rules or
17
+ say which ones you will follow: just act on them in the task at hand.
18
+
19
+ **Ask every question with the `AskUserQuestion` tool, never in prose.** Whenever the user has to
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:
22
+
23
+ - 2 to 4 options, each with what it does and what it costs in its description (e.g. "Search the 6
24
+ missing companies — up to 6 paid lookups").
25
+ - `multiSelect: true` when the options combine (search the missing companies _and_ look up the
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.
30
+
31
+ Do not end a reply with a list of things you could do next: ask it instead. Section 6 adds what a
32
+ paid-call question must contain.
33
+
34
+ **Reach the app only through `sl` commands.** Do not send GraphQL yourself: no `curl` or `fetch` to
35
+ the router or a subgraph, no hand-written queries, no `sl token` piped into another client. The
36
+ commands carry what a raw request skips: the right company, the personal-company fallback, token
37
+ refresh, `--reveal` handling, `--wait`, readable errors. When no command does what is needed, say so
38
+ and stop, rather than working around it.
39
+
40
+ ## 1. Know where and as whom before the first call
41
+
42
+ ```bash
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.
215
+
216
+ ```bash
217
+ sl atlas find-organizations --filter '{"domain":{"eq":"acme.com"}}' --page '{"first":1}' --wait \
218
+ --fields name,domain
219
+
220
+ sl atlas find-contacts --organization-filter '{"domain":{"eq":"acme.com"}}' --wait \
221
+ --fields jobTitle,jobLevel
222
+ ```
223
+
224
+ - A page is sent `FILLING` while Atlas may still change it and again `COMPLETE` on its last version;
225
+ `--wait` prints the `COMPLETE` one. If `--wait` runs out first (exit code `5`), it prints the page so
226
+ far and says it was still filling: wait longer rather than starting the search again.
227
+ - **Pages:** `--page '{"first":20}'` (1 to 20, 20 by default). When more follow, `--wait`
228
+ ends with the exact command for the next page (`Next page: sl atlas find-contacts --external-id …
229
+ --page '{"first":20,"after":"…"}' --wait`): run it as given. With `after`, Atlas
230
+ reads on in the same search and ignores the call's own `--filter`, `--organization-filter` and
231
+ `--sort`. A search lives one hour and lists at most 1000 records; `hasNextPage` says whether more
232
+ follow. Atlas gives no count of every match: say "more follow", never a total.
233
+ - **One record:** `--page '{"first":1}'` with a filter naming it: an organization by
234
+ `"domain":{"eq":…}`; a contact by `"id"`, `"linkedinUrl"` or `"emailAddress"` with `eq`, or by
235
+ `"name":{"eq":…}` together with `--organization-filter '{"id":{"eq":"<organization id>"}}'`.
236
+ - **No quality floor.** A find applies exactly the filter given. A contact with no name, no verified
237
+ email or a low confidence comes back unless the filter excludes it, so spell out what is wanted:
238
+ `"name":{"presence":true}`, `"confidenceScore":{"gteq":0.5}`, `"reachableBy":{"all":["EMAIL_ADDRESS"]}`.
239
+ - **`reachableBy`** keeps records reachable through a channel without revealing it: `EMAIL_ADDRESS`
240
+ (verified), `LINKEDIN_URL`, `PHONE_NUMBER` on contacts, plus `WEBSITE` on organizations; with `eq`,
241
+ `in`, `all`, `notEq`, `notIn`.
242
+ - The result is the subscription payload: `{"externalId": …, "status": "COMPLETE", "contacts":
243
+ {"edges": [{"node": {…}, "reveals": […]}], "pageInfo": …, "credits": …}}` (`organizations` instead of
244
+ `contacts` for `find-organizations`). Without `--fields` it carries every direct field of each
245
+ record. Each edge's `reveals` and `credits`, and the page's `credits`, `pageInfo` and `status`,
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**.
272
+
273
+ ```bash
274
+ sl mercator resolve-by-code --code BE --code-type COUNTRY_ISO --fields id,name # a country, by ISO code
275
+ sl mercator resolve-locations --query "Brabant wallon" --within <belgium-id> \
276
+ --first 5 --fields id,name,shortName,subtype,adminLevel # anything below it
277
+ ```
278
+
279
+ - `resolve-locations` is a fuzzy search. Pass `--within <country-id>` to disambiguate same-named
280
+ places (Georgia, Victoria, Luxembourg), `--subtypes '{"in":["LOCALITY"]}'` to pick a level, and
281
+ `--exact-only true` when a wrong best guess would be worse than no result ("Stockholm" otherwise
282
+ resolves to the county).
283
+ - Check `subtype` and `name` in the answer before using the id, and show them to the user when the
284
+ query was ambiguous. Levels, coarse to fine: `MACROCOUNTRY` (BENELUX, DACH…), `COUNTRY`, `DEPENDENCY`,
285
+ `MACROREGION`, `REGION`, `MACROCOUNTY`, `COUNTY`, `LOCALADMIN`, `LOCALITY`, `BOROUGH`, `MACROHOOD`,
286
+ `NEIGHBORHOOD` (`sl mercator location-subtypes`). Brabant wallon is a `COUNTY`, Wavre a `LOCALITY`.
287
+ - A division matches everything inside it: the Brabant wallon id also returns contacts in Wavre.
288
+ Several places go in one `in` list.
289
+
290
+ Then pick the filter that answers the question:
291
+
292
+ | Question | Filter |
293
+ | ------------------------------------------------- | ---------------------------------------------------------------- |
294
+ | Organizations with an address in the place | `find-organizations --filter '{"divisionIds":{"in":["<id>"]}}'` |
295
+ | Contacts located in the place | `find-contacts --filter '{"divisionIds":{"in":["<id>"]}}'` |
296
+ | Contacts working for an organization in the place | `find-contacts --organization-filter '{"divisionIds":{"in":…}}'` |
297
+
298
+ ### Reveals cost credits
299
+
300
+ A find reveals nothing unless asked: by default the reach fields come back `null` and each edge's
301
+ `reveals` shows them `LOCKED`, while job title, level, city and organization stay readable. To reveal
302
+ on purpose, name exactly the dimensions needed, after the user's yes (section 6):
303
+ `--reveal contactEmailAddress` or `--reveal contactIdentity,contactEmailAddress` (the full
304
+ `CONTACT_EMAIL_ADDRESS` spelling works too). Organizations have their own dimensions
305
+ (`organizationIdentity`, `organizationFirmographics`, `organizationWebsite`…). `--reveal` applies to
306
+ every record on the page, so narrow the page to the records the user picked first: `--filter
307
+ '{"id":{"in":["<id>",…]}}'`.
308
+
309
+ Each edge's `reveals` gives the status of every dimension the call touched:
310
+
311
+ | Status | Meaning | Cost |
312
+ | ------------- | ----------------------------------------------------------------- | -------------------------------------------------------- |
313
+ | `LOCKED` | Atlas has it; this company has not asked for it | Nothing; the fields are `null` |
314
+ | `REVEALED` | Asked for and found, recorded by this response | 1 unit on the page's bill, priced by billing (below) |
315
+ | `OWNED` | Already revealed to this company inside its window (`ownedUntil`) | Nothing more: re-reading is free until the window closes |
316
+ | `UNAVAILABLE` | Atlas has nothing for it | Never recorded |
317
+ | `FAILED` | A lookup could not complete (`find-contacts` only) | Never recorded; a new search tries again |
318
+
319
+ Every page carries its bill in `credits`: `{"held": 20, "used": 19, "byDimension": [{"dimension":
320
+ "CONTACT_IDENTITY", "used": 11}, …]}`, where `held` is the ceiling reserved (requested dimensions ×
321
+ rows) and `used` what the page actually consumed. These count units, one per dimension revealed on a
322
+ record. What a unit costs is billing's price list, per dimension: a contact's name is 2 credits, its
323
+ email 40, its phone 150, an organization's name 1. Those credits are taken from the company's balance
324
+ and listed on the developer portal's Usage page under whoever made the call.
325
+
326
+ ### When Atlas looks further
327
+
328
+ A find can call external providers on the user's behalf, which costs money upstream:
329
+
330
+ - `find-contacts` searches Coresignal in the background when the contacts already listed cannot fill
331
+ the page, and a filter naming one person runs a full identification when Atlas holds no fresh row.
332
+ - `find-contacts` with `--reveal` naming `contactEmailAddress` or `contactPhoneNumber` looks up what
333
+ the page lacks: up to one email and one phone lookup per contact on the page.
334
+ - `find-organizations` with `"domain":{"eq":…}` looks the domain up when Atlas holds no fresh row for
335
+ it. Every other organization filter is answered from the database.
336
+
337
+ ## 5b. Signals: watchers and leads
338
+
339
+ A **watcher** follows one buying signal for an ideal customer profile (ICP) and turns each matching
340
+ event into a **qualified lead**: a person at a company, with the event that qualified them.
341
+
342
+ ```bash
343
+ sl signals watcher-definitions --fields slug,version,name,description,triggers # what can be watched
344
+ sl signals watcher-definition --slug fundraising --watcher-definition-version 2 \
345
+ --fields watcherInputSchema,canonicalEventSchema # its input and event shape
346
+ sl signals watchers --fields id,name,lifecycleState,provisioningStatus # what already runs
347
+ ```
348
+
349
+ - **Pick the definition from its `description`**: each says when to use it and when not to. Prefer the
350
+ latest version; pin slug and version once chosen.
351
+ - **`watcherInput`** is JSON matching the definition's `watcherInputSchema` (keywords, LinkedIn URLs,
352
+ job titles, investment types…). Read the schema, never guess keys.
353
+ - **ICP**: `--icp '{"organization":{"industry":[{"queries":["software"],"match":"INCLUDED_STRICT"}],"companySize":{"overlaps":[11,200]},"divisionIds":{"in":["<id>"]}},"contact":{"jobTitle":[{"queries":["CEO","founder"],"match":"INCLUDED_LOOSE"}]}}'`.
354
+ Same meaning filters and Mercator ids as Atlas (section 5).
355
+ - **Caps**: `--lead-caps '[{"maximumLeads":20,"period":"P1D"}]'` caps delivered leads. Always set one.
356
+ `maximumLeadsPerOrganization` defaults to 2 per day.
357
+ - **Create** with `sl signals create-watcher … --wait`: it provisions and prints the watcher; with
358
+ `--wait`, `--fields` names the result's fields (`watcher.id,watcher.provisioningStatus`). No
359
+ `--webhook` is needed: leads are stored and read with `watcher-events`.
360
+ - **The company the creating call acts for pays for every lead** (section 3), for the watcher's whole
361
+ life. Create it while acting for the company the user chose.
362
+ - **`BILLING_PAUSED`**: billing refused a lead (no credits, or no billing account), so the watcher
363
+ stopped watching and delivers nothing. Say so. Once the company has credits,
364
+ `sl signals resume-watcher --id <id>` restarts it and replays the leads held back in the last week,
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.