@sortlist/cli 0.57.0 → 0.58.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.58.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,579 @@
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 and `--total-count` adds the total. In a terminal a table shows a page only as a count of
189
+ its entries, so pass `--json` there; from a tool call the output is JSON already. `--exclude` drops
190
+ heavy fields, and `--depth` controls how deep nested objects are selected (default 0) and never
191
+ selects a deprecated field; name one in `--fields` to get it anyway.
192
+ - A mutation prints the object it returns, and its `--fields` name that object's fields:
193
+ `create-company --fields id,slug`, not `company.id`.
194
+ - Operation descriptions carry the business rules. Read `--help` before a mutation, not after.
195
+
196
+ ## 5. Atlas: finding organizations and contacts
197
+
198
+ ### What Atlas holds
199
+
200
+ - **Organization**: a company, keyed by its primary `domain` (unique). Name, website, description,
201
+ industry, Mercator `locations`, `companySize` and `annualRevenue` as `[min, max]` ranges, foundedYear,
202
+ LinkedIn, phone, logo, offices, and a `confidenceScore` (0 to 1) merged from its sources.
203
+ - **Contact**: a person at one organization (`contact.organization`). Job title, function and level,
204
+ city, country and Mercator `locations`, `confidenceScore`, `profileCompleteness`. Then the **reach
205
+ fields, which are paid** (see Reveals): name, avatar and career entries (`CONTACT_IDENTITY`),
206
+ `emailAddress` / `emailStatus` / `emailPattern` (`CONTACT_EMAIL_ADDRESS`), `linkedinUrl`
207
+ (`CONTACT_LINKEDIN_URL`), `phone` (`CONTACT_PHONE_NUMBER`).
208
+
209
+ ### How a find works
210
+
211
+ `find-organizations` and `find-contacts` are searches: the mutation only answers `{status: "received"}`,
212
+ and the page arrives on a subscription. **Always pass `--wait`.** It subscribes, sends the mutation,
213
+ and prints the page once Atlas has finished filling it.
214
+
215
+ ```bash
216
+ sl atlas find-organizations --filter '{"domain":{"eq":"acme.com"}}' --page '{"first":1}' --wait \
217
+ --fields name,domain
218
+
219
+ sl atlas find-contacts --organization-filter '{"domain":{"eq":"acme.com"}}' --wait \
220
+ --fields jobTitle,jobLevel --total-count
221
+ ```
222
+
223
+ - A page is sent `FILLING` while Atlas may still change it and again `COMPLETE` on its last version;
224
+ `--wait` prints the `COMPLETE` one. If `--wait` runs out first (exit code `5`), it prints the page so
225
+ far and says it was still filling: wait longer rather than starting the search again.
226
+ - **Pages:** `--page '{"first":20}'` (1 to 20, 20 by default). When more follow, `--wait`
227
+ ends with the exact command for the next page (`Next page: sl atlas find-contacts --external-id …
228
+ --page '{"first":20,"after":"…"}' --wait`): run it as given. With `after`, Atlas
229
+ reads on in the same search and ignores the call's own `--filter`, `--organization-filter` and
230
+ `--sort`. A search lives one hour and lists at most 1000 records; `hasNextPage` says whether more
231
+ follow, `totalCount` how many it has listed so far.
232
+ - **One record:** `--page '{"first":1}'` with a filter naming it: an organization by
233
+ `"domain":{"eq":…}`; a contact by `"id"`, `"linkedinUrl"` or `"emailAddress"` with `eq`, or by
234
+ `"name":{"eq":…}` together with `--organization-filter '{"id":{"eq":"<organization id>"}}'`.
235
+ - **No quality floor.** A find applies exactly the filter given. A contact with no name, no verified
236
+ email or a low confidence comes back unless the filter excludes it, so spell out what is wanted:
237
+ `"name":{"presence":true}`, `"confidenceScore":{"gteq":0.5}`, `"reachableBy":{"all":["EMAIL_ADDRESS"]}`.
238
+ - **`reachableBy`** keeps records reachable through a channel without revealing it: `EMAIL_ADDRESS`
239
+ (verified), `LINKEDIN_URL`, `PHONE_NUMBER` on contacts, plus `WEBSITE` on organizations; with `eq`,
240
+ `in`, `all`, `notEq`, `notIn`.
241
+ - The result is the subscription payload: `{"externalId": …, "status": "COMPLETE", "contacts":
242
+ {"edges": [{"node": {…}, "reveals": […]}], "pageInfo": …, "credits": …}}` (`organizations` instead of
243
+ `contacts` for `find-organizations`). Without `--fields` it carries every direct field of each
244
+ record. Each edge's `reveals` and `credits`, and the page's `credits`, `pageInfo` and `status`,
245
+ come back whatever `--fields` names, so `--fields` only lists record fields and the spend report
246
+ always has what it needs.
247
+
248
+ ### Filters and sorting
249
+
250
+ - **Scalar operators:** strings take `eq`, `in`, `notEq`, `notIn`, `presence`, `blank`; numbers take
251
+ `eq`, `gt`, `gteq`, `lt`, `lteq`; ranges (`companySize`) take `overlaps`, `containedBy`, `contains`.
252
+ Any of them can add `"allowBlank": true` to also keep rows where the value is missing.
253
+ - **Normalized matching:** `domain` drops the scheme, `www.` and path; `name` drops case, accents,
254
+ punctuation and legal forms (`Sortlist NV/SA` finds `Sortlist`); `linkedinUrl` compares vanity
255
+ slugs; `emailAddress` is trimmed and lowercased. Each is still an exact match after that.
256
+ - **Semantic filters** (`description`, `industry` on organizations, `jobTitle` on contacts): a list
257
+ of `{"queries":[…],"match":"INCLUDED_STRICT"}` entries. Queries inside an entry are OR, several
258
+ entries are AND. `INCLUDED_LOOSE` widens, `EXCLUDED_*` removes. List related terms and translations
259
+ (`["CMO","Marketing Director","Directeur Marketing"]`), one concept per query.
260
+ - **Size (organizations):** `"companySize":{"overlaps":[0,100]}`, or `[1000]` for 1000 and above.
261
+ - **Sorting:** `--sort '[{"field":"CONFIDENCE_SCORE"}]'`, `NAME`, `CREATED_AT`, or by closeness to a
262
+ text with `INDUSTRY_DISTANCE` / `DESCRIPTION_DISTANCE` (and `JOB_TITLE_DISTANCE` on contacts). **A
263
+ distance sort defaults to descending, which puts the least similar first**: always pass
264
+ `"direction":"ASC"`, e.g. `[{"field":"INDUSTRY_DISTANCE","query":"digital marketing agency","direction":"ASC"}]`.
265
+ - `sl schema inspect ContactsFilterInput` / `OrganizationsFilterInput` lists every field.
266
+
267
+ ### Places
268
+
269
+ Atlas does not take place names. Every geographic filter is `divisionIds`: Mercator location ids.
270
+ So a search by place is always two steps, **resolve the place in Mercator, then filter Atlas**.
271
+
272
+ ```bash
273
+ sl mercator resolve-by-code --code BE --code-type COUNTRY_ISO --fields id,name # a country, by ISO code
274
+ sl mercator resolve-locations --query "Brabant wallon" --within <belgium-id> \
275
+ --first 5 --fields id,name,shortName,subtype,adminLevel # anything below it
276
+ ```
277
+
278
+ - `resolve-locations` is a fuzzy search. Pass `--within <country-id>` to disambiguate same-named
279
+ places (Georgia, Victoria, Luxembourg), `--subtypes '{"in":["LOCALITY"]}'` to pick a level, and
280
+ `--exact-only true` when a wrong best guess would be worse than no result ("Stockholm" otherwise
281
+ resolves to the county).
282
+ - Check `subtype` and `name` in the answer before using the id, and show them to the user when the
283
+ query was ambiguous. Levels, coarse to fine: `MACROCOUNTRY` (BENELUX, DACH…), `COUNTRY`, `DEPENDENCY`,
284
+ `MACROREGION`, `REGION`, `MACROCOUNTY`, `COUNTY`, `LOCALADMIN`, `LOCALITY`, `BOROUGH`, `MACROHOOD`,
285
+ `NEIGHBORHOOD` (`sl mercator location-subtypes`). Brabant wallon is a `COUNTY`, Wavre a `LOCALITY`.
286
+ - A division matches everything inside it: the Brabant wallon id also returns contacts in Wavre.
287
+ Several places go in one `in` list.
288
+
289
+ Then pick the filter that answers the question:
290
+
291
+ | Question | Filter |
292
+ | ------------------------------------------------- | ---------------------------------------------------------------- |
293
+ | Organizations with an address in the place | `find-organizations --filter '{"divisionIds":{"in":["<id>"]}}'` |
294
+ | Contacts located in the place | `find-contacts --filter '{"divisionIds":{"in":["<id>"]}}'` |
295
+ | Contacts working for an organization in the place | `find-contacts --organization-filter '{"divisionIds":{"in":…}}'` |
296
+
297
+ ### Reveals cost credits
298
+
299
+ A find reveals nothing unless asked: by default the reach fields come back `null` and each edge's
300
+ `reveals` shows them `LOCKED`, while job title, level, city and organization stay readable. To reveal
301
+ on purpose, name exactly the dimensions needed, after the user's yes (section 6):
302
+ `--reveal contactEmailAddress` or `--reveal contactIdentity,contactEmailAddress` (the full
303
+ `CONTACT_EMAIL_ADDRESS` spelling works too). Organizations have their own dimensions
304
+ (`organizationIdentity`, `organizationFirmographics`, `organizationWebsite`…). `--reveal` applies to
305
+ every record on the page, so narrow the page to the records the user picked first: `--filter
306
+ '{"id":{"in":["<id>",…]}}'`.
307
+
308
+ Each edge's `reveals` gives the status of every dimension the call touched:
309
+
310
+ | Status | Meaning | Cost |
311
+ | ------------- | ----------------------------------------------------------------- | -------------------------------------------------------- |
312
+ | `LOCKED` | Atlas has it; this company has not asked for it | Nothing; the fields are `null` |
313
+ | `REVEALED` | Asked for and found, recorded by this response | 1 unit on the page's bill, priced by billing (below) |
314
+ | `OWNED` | Already revealed to this company inside its window (`ownedUntil`) | Nothing more: re-reading is free until the window closes |
315
+ | `UNAVAILABLE` | Atlas has nothing for it | Never recorded |
316
+ | `FAILED` | A lookup could not complete (`find-contacts` only) | Never recorded; a new search tries again |
317
+
318
+ Every page carries its bill in `credits`: `{"held": 20, "used": 19, "byDimension": [{"dimension":
319
+ "CONTACT_IDENTITY", "used": 11}, …]}`, where `held` is the ceiling reserved (requested dimensions ×
320
+ rows) and `used` what the page actually consumed. These count units, one per dimension revealed on a
321
+ record. What a unit costs is billing's price list, per dimension: a contact's name is 2 credits, its
322
+ email 40, its phone 150, an organization's name 1. Those credits are taken from the company's balance
323
+ and listed on the developer portal's Usage page under whoever made the call.
324
+
325
+ ### When Atlas looks further
326
+
327
+ A find can call external providers on the user's behalf, which costs money upstream:
328
+
329
+ - `find-contacts` searches Coresignal in the background when the contacts already listed cannot fill
330
+ the page, and a filter naming one person runs a full identification when Atlas holds no fresh row.
331
+ - `find-contacts` with `--reveal` naming `contactEmailAddress` or `contactPhoneNumber` looks up what
332
+ the page lacks: up to one email and one phone lookup per contact on the page.
333
+ - `find-organizations` with `"domain":{"eq":…}` looks the domain up when Atlas holds no fresh row for
334
+ it. Every other organization filter is answered from the database.
335
+
336
+ ## 5b. Signals: watchers and leads
337
+
338
+ A **watcher** follows one buying signal for an ideal customer profile (ICP) and turns each matching
339
+ event into a **qualified lead**: a person at a company, with the event that qualified them.
340
+
341
+ ```bash
342
+ sl signals watcher-definitions --fields slug,version,name,description,triggers # what can be watched
343
+ sl signals watcher-definition --slug fundraising --watcher-definition-version 2 \
344
+ --fields watcherInputSchema,canonicalEventSchema # its input and event shape
345
+ sl signals watchers --fields id,name,lifecycleState,provisioningStatus # what already runs
346
+ ```
347
+
348
+ - **Pick the definition from its `description`**: each says when to use it and when not to. Prefer the
349
+ latest version; pin slug and version once chosen.
350
+ - **`watcherInput`** is JSON matching the definition's `watcherInputSchema` (keywords, LinkedIn URLs,
351
+ job titles, investment types…). Read the schema, never guess keys.
352
+ - **ICP**: `--icp '{"organization":{"industry":[{"queries":["software"],"match":"INCLUDED_STRICT"}],"companySize":{"overlaps":[11,200]},"divisionIds":{"in":["<id>"]}},"contact":{"jobTitle":[{"queries":["CEO","founder"],"match":"INCLUDED_LOOSE"}]}}'`.
353
+ Same meaning filters and Mercator ids as Atlas (section 5).
354
+ - **Caps**: `--lead-caps '[{"maximumLeads":20,"period":"P1D"}]'` caps delivered leads. Always set one.
355
+ `maximumLeadsPerOrganization` defaults to 2 per day.
356
+ - **Create** with `sl signals create-watcher … --wait`: it provisions and prints the watcher; with
357
+ `--wait`, `--fields` names the result's fields (`watcher.id,watcher.provisioningStatus`). No
358
+ `--webhook` is needed: leads are stored and read with `watcher-events`.
359
+ - **The company the creating call acts for pays for every lead** (section 3), for the watcher's whole
360
+ life. Create it while acting for the company the user chose.
361
+ - **`BILLING_PAUSED`**: billing refused a lead (no credits, or no billing account), so the watcher
362
+ stopped watching and delivers nothing. Say so. Once the company has credits,
363
+ `sl signals resume-watcher --id <id>` restarts it and replays the leads held back in the last week,
364
+ each billed again (ask first, it spends credits).
365
+ - **Watchers are immutable and shared**: the same input and ICP reuse an existing watcher. To change
366
+ one, create a new one and delete the old. `update-watcher-lead-caps` and `delete-watcher` affect
367
+ every consumer of a shared watcher: check `watchers` first.
368
+ - **When leads arrive** depends on the watcher's provider, not on the definition's `triggers`. Read
369
+ `sl signals watchers --fields id,providerStates.providerSlug,providerStates.nextRunAt`: a
370
+ `nextRunAt` means a scheduled provider, which `trigger-watcher` runs at once; null means the
371
+ provider pushes on its own and `trigger-watcher` does nothing. `linkedin-reactions` lists
372
+ `SCHEDULE` but runs on a pushing provider: its first leads came about 30 minutes after creation.
373
+ Most other definitions deliver over hours or days. Tell the user which, and check back.
374
+ - `--fields` takes a connection's counters next to its rows, e.g.
375
+ `--fields id,events.total,events.discarded,events.observedAt`. `discardReason` and the discarded
376
+ slice need a service-wide read scope (`signals/*:read`): a plain login gets an error for them, not an empty
377
+ value.
378
+
379
+ **Reading leads**
380
+
381
+ ```bash
382
+ sl signals watcher-events --filter '{"watcherId":{"eq":"<id>"},"qualifiedAt":{"gt":"<last seen>"}}' \
383
+ --first 20 --fields id,qualifiedAt,occurredAt,payload,contact.node.id
384
+ ```
385
+
386
+ - **Never select a contact's reach fields on `watcher-events`** (`contact.node.firstName`,
387
+ `emailAddress`, `phone`, `linkedinUrl`, or a `--depth` that reaches them): with no `reveal:`
388
+ argument the event reveals and charges every reach field selected. Select `contact.node.id`, show
389
+ the leads, then reveal what the user picks with `sl atlas find-contacts --filter
390
+ '{"id":{"in":[…]}}' --reveal … --wait` (section 6).
391
+ - **Don't handle a lead twice.** Read with `--filter '{"acknowledged":{"eq":"UNACKNOWLEDGED"}}'`
392
+ and, once the user has decided about a lead (contacted it or skipped it),
393
+ `sl signals acknowledge-watcher-events --ids '["<event id>",…]'`. Not when it is merely shown.
394
+ - `payload` follows `canonicalEventSchema`: what happened, when, to which company. Quote it; never
395
+ invent a score or a probability.
396
+ - Say "no lead yet" only for a watcher that is `PROVISIONED` and `ACTIVE`. Tell it apart from a
397
+ watcher still provisioning, paused, billing paused, or out of its caps.
398
+ - Each lead costs 20, 50 or 100 credits depending on the definition, charged when delivered.
399
+ - Watchers keep running after the conversation. At the end of a task, list the ones created and ask
400
+ whether to keep them (`delete-watcher --id <id>` stops one).
401
+
402
+ ## 5c. Outreach: accounts and actions
403
+
404
+ Outreach sends **one action at a time** from an account it holds for the user: a LinkedIn
405
+ invitation, message, profile visit or lookup, or an email. There are no campaigns or sequences: a
406
+ campaign is a plan the agent holds and runs as single actions (the `sortlist-go-to-market` skill).
407
+
408
+ ```bash
409
+ sl outreach outbound-channel-accounts --fields id,channel,provider,status,externalId
410
+ ```
411
+
412
+ - Use an account that is `RUNNING`. Connecting a new one needs the account owner: a hosted sign-in
413
+ link (`authenticate-outbound-channel-account`) they open themselves. Email accounts can't be
414
+ connected from the CLI yet.
415
+ - **Connecting LinkedIn from the owner's browser** (provider `LINKEDIN_DIRECT`): the account runs on the
416
+ owner's own browser session. Ask first: it signs Outreach in as them, and the owner must be at the
417
+ computer to sign in.
418
+ 1. Create the account, acting for the company that pays:
419
+ `sl outreach create-outbound-channel-account --channel LINKEDIN --provider LINKEDIN_DIRECT
420
+ --external-id <who it is for> --fields channelAccount.id,channelAccount.status`. No webhook is
421
+ needed: events are read with the CLI.
422
+ 2. Run `sl outreach connect-linkedin <account id> <country code>` (the owner's country, e.g. `BE`)
423
+ in the background. It opens Chrome, Edge, Brave or Chromium on linkedin.com/login in a fresh
424
+ profile, prints "A browser window is open…", waits up to 10 minutes (`--timeout <minutes>`)
425
+ for the owner to sign in, verification code included, then sends the session to Outreach itself
426
+ and deletes the profile.
427
+ 3. As soon as that line appears, tell the owner to sign in in that window. The command ends with
428
+ `Connected: <name> is RUNNING`, or Outreach's refusal (`credentials.rejected`: run it again).
429
+ - **Never read, print or ask for the cookie yourself**, and never ask the owner to paste it: it is
430
+ their whole LinkedIn login. The command is the only path, and it never shows the value.
431
+ - It needs a desktop session on the owner's computer (macOS, Windows or Linux): not over SSH, in a
432
+ headless container or in WSL without a display. A snap or Flatpak Chromium cannot be driven; it
433
+ says so, and `CHROME_PATH` picks another browser.
434
+ - With this provider, acceptances and replies arrive within about 10 minutes (Outreach checks the
435
+ inbox every 10 minutes) instead of at once. A session LinkedIn ends turns the account
436
+ `DISCONNECTED`: run the command again on the same account id.
437
+ - **The company the call that creates the account acts for pays for every LinkedIn action on it**
438
+ (section 3). Create it while acting for the company the user chose.
439
+ - **Find the LinkedIn member id** with a silent lookup (2 credits, nobody is notified):
440
+ `sl outreach perform-outbound-channel-action --channel-account-id <id> --external-id lookup-<slug>
441
+ --action '{"linkedinLookupProfile":{"identifier":"<linkedin url or vanity>"}}' --wait`. Its
442
+ `result` carries `member_id` (the `ACoAA…` id every other action takes), `network_distance` (`SELF`
443
+ … `OUT_OF_NETWORK`) and `pending_invitation`. Don't invite a first-degree connection or someone with a
444
+ pending invitation: LinkedIn doesn't always refuse it.
445
+ - **Act**: `--action '{"linkedinInvite":{"memberId":"…","message":"…"}}'` (note 300 characters
446
+ max), `{"linkedinSendMessage":{"memberId":"…","text":"…"}}`, `{"linkedinVisit":{"memberId":"…"}}`,
447
+ `{"linkedinCancelInvitation":{"invitationId":"…"}}`.
448
+ - **Always pass a meaningful `--external-id`** (`<prospect>-step-<n>`): the same id returns the same
449
+ action instead of sending twice. After a timeout, read `outbound-channel-actions` before acting again.
450
+ - A free LinkedIn account gets only a handful of invitations with a note per month: LinkedIn refuses
451
+ more as `not_allowed`. Offer to send without a note rather than retrying.
452
+ - `--wait` follows the action until it settles; its `--fields` then name the result's fields
453
+ (`channelAction.state,channelAction.result`). On a timeout (exit code 5), or without it, read
454
+ `sl outreach outbound-channel-action --id <id> --fields state,error,result`. States: `PENDING`, `EXECUTING`, `COMPLETED`, `FAILED`,
455
+ `CANCELLED`. A failed action is never retried by the gateway.
456
+ - **Refused by billing**: the action is `FAILED` with `error.code` `insufficient_credits` and
457
+ `error.billing_code` saying why (`INSUFFICIENT_CREDITS`, `NO_BILLING_CUSTOMER`,
458
+ `PRODUCT_NOT_BILLED`). LinkedIn was never reached and nothing was charged. `billing_unavailable`
459
+ means billing was down for 24 hours. Stop the plan, report it with the company's balance
460
+ (`sl use company`), and resend only after a new yes, under a new `--external-id`.
461
+ - **Pacing**: 50 invitations and 150 messages a day per LinkedIn member. Actions queue; `scheduledAt`
462
+ says when one will run. `cancel-outbound-channel-actions --channel-account-id <id> --channel-action-ids '[…]'` stops pending ones.
463
+ - **Replies and acceptances**: `sl outreach outbound-channel-events --channel-account-id <id> --fields id,eventType,occurredAt,payload`
464
+ (`invitation.accepted`, `message.received`…), `linkedin-chats`, `linkedin-chat-messages`.
465
+ `--filter '{"acknowledged":{"eq":"UNACKNOWLEDGED"}}'` returns only what is left; acknowledge what was
466
+ acted on with `sl outreach acknowledge-outbound-channel-events --channel-account-id <id> --ids
467
+ '["<event id>",…]'`. Outreach reads only the conversations it is part of: chats it started, and
468
+ people the account invited or is writing to. A message someone sends the account out of the blue
469
+ never appears, so start the conversation with `linkedinSendMessage` first.
470
+ - Costs: invitation or message 5 credits, visit or lookup 2, withdrawal 1. Email is free.
471
+ - Every action reaches a real person in the user's name: section 6 applies to each one.
472
+
473
+ ## 6. Paid calls, writes and go-aheads
474
+
475
+ ### Which calls are paid
476
+
477
+ | Call | What costs |
478
+ | ------------------------------------------------------- | ------------------------------------------------------------------ |
479
+ | `find-contacts` or `find-organizations` with `--reveal` | Each dimension `REVEALED`, per record, and the lookups it triggers |
480
+ | `find-contacts` that may look further (section 5) | Provider searches on the user's behalf |
481
+ | `find-organizations` by `domain` `eq` Atlas lacks | One domain lookup |
482
+ | `signals create-watcher` | Every lead it delivers: 20, 50 or 100 credits, until deleted |
483
+ | `signals watcher-events` selecting contact reach fields | A reveal per field selected (avoid: section 5b) |
484
+ | `outreach perform-outbound-channel-action` | 1 to 5 credits per LinkedIn action, and a message to a real person |
485
+ | `hermes change-company-subscription` | An upgrade invoices the company's card at once, prorated |
486
+ | `hermes create-application-credential` | Nothing, but it is a write that hands out a secret (see Writes) |
487
+
488
+ Everything else (Mercator, Hermes reads such as `companies` and `applications`, a find without
489
+ `--reveal` that Atlas answers from its database) is free and can be run without asking.
490
+
491
+ ### Before a paid call: always ask
492
+
493
+ **Never run a paid call without an explicit yes from the user, every time, even after an earlier
494
+ approval and even for a retry.** Ask with the `AskUserQuestion` tool, so the user picks an answer
495
+ instead of typing one. Never ask in prose.
496
+
497
+ - **Question:** one line, what is bought, the most it can cost in credits, who pays (section 3: the
498
+ `--company`, else the personal company). For example: "Reveal names +
499
+ emails of 10 contacts (up to 20 credits, charged to Personal)?"
500
+ - **Options**, 2 to 4, each a real alternative with its cost in the description:
501
+ - the call as proposed, first, with the exact command in its `preview`;
502
+ - cheaper variants when they exist, each with its own command in `preview`: one dimension only
503
+ ("Emails only, up to 10 credits"), fewer records, or a different company;
504
+ - "Don't reveal": continue with what the find without `--reveal` already shows.
505
+ - Mention already-owned records in the question only when there are some ("3 already owned, free").
506
+ Check with a find without `--reveal` beforehand when it matters: their `reveals` say `OWNED`.
507
+ - If the tool is not available, fall back to one line plus the command, and wait.
508
+
509
+ Then wait for the answer and run exactly the option picked. An answer about one call does not cover the
510
+ next one, with one exception: a **bounded plan**. When the user approves a plan that names the exact
511
+ people, the exact dimensions or actions, and a maximum in credits (for example a campaign's first
512
+ step for five named prospects, at most 25 credits), run it without asking again for each call,
513
+ stop at the maximum, and ask again for anything outside it: another person, another field, another
514
+ step, or more credits. A lower actual cost (already owned) needs no new question. A budget alone
515
+ selects nobody: show who and what first.
516
+
517
+ ### After a paid call: report the spend
518
+
519
+ Report it from the pages themselves, in two or three lines, no more, starting with the total:
520
+
521
+ ```
522
+ Credits used: 19 (11 names, 8 emails) · Personal
523
+ 6 contacts already owned, free · 3 emails unavailable
524
+ Free to re-read until 2026-12-23
525
+ ```
526
+
527
+ The total is the sum of `credits.used` over every page the task read; the per-dimension split comes
528
+ from `credits.byDimension`, and the owned and unavailable counts from each edge's `reveals`. Leave out
529
+ what is zero. Credits are units, not money: never convert them into an amount. Atlas charges them, and so do
530
+ Signals (per lead) and Outreach (per LinkedIn action).
531
+
532
+ ### Writes
533
+
534
+ - **Before any mutation other than a find, show the user the exact command and wait for approval**,
535
+ on every environment.
536
+ - Ask with `AskUserQuestion`, the exact command in the option's `preview`, as for a paid call. These
537
+ cannot be undone, so say so in the question and never batch two of them under one yes:
538
+ `delete-company`, `delete-application`, `remove-company-member` (it also revokes every credential
539
+ that member created), `revoke-application-credential` (new tokens stop at once), and
540
+ `cancel-company-subscription` (ends the plan immediately and forfeits the rest of the period).
541
+ - `create-company-invitation` hands whoever redeems the code full control of the company's
542
+ applications and credentials. Confirm who it is for, and never paste the code anywhere but to the
543
+ user.
544
+ - `accept-company-invitation` joins the user to another company: run
545
+ `company-invitation-preview` first and show what the code is for.
546
+ A code is spent by whoever redeems it, a member of the company included, so never accept one
547
+ meant for someone else.
548
+ - `create-application-credential` returns the client id and the secret, the secret exactly once.
549
+ Hand it to the user to store, and never write it into a file or repeat it later in the
550
+ conversation. The credential's id, which `revoke-application-credential` takes, is listed by
551
+ `sl hermes application --id <application id> --fields credentials.id,credentials.name`.
552
+ - `create-company-billing-portal-session` returns a Stripe URL: give it to the user to open, and do
553
+ not open it yourself. Subscribing to a plan has no command. It happens on the developer portal's
554
+ Billing page.
555
+ - `sl token` prints the bearer token. Never echo it into a reply or a file.
556
+
557
+ ## 7. Reading errors
558
+
559
+ | Error | Meaning | What to do |
560
+ | ----------------------------------------------------------------- | ----------------------------------------------------------- | -------------------------------------------------------------------------------------- |
561
+ | `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 |
562
+ | `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 |
563
+ | `<service> refused this request: it names no company to act for` | No company could be resolved, not even the personal one | Pass `--company <slug>` |
564
+ | `<service> refused to act for your personal company` | The fallback of section 3 was refused | Pass `--company <slug>` from `sl use company` |
565
+ | `Subgraph http callback status code not ok` (a subscription) | The subgraph refused the subscription; production hides why | Retry with `--company <slug>` |
566
+ | `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 |
567
+ | `<service> refused to act for company <x>` | The user is not a member of that company | Pick one from `sl use company` |
568
+ | `INVALID_INTERACTION` with `details.after` expired | The cursor's search expired or belongs to someone else | Start a new search without `after` |
569
+ | `You are not logged in` / `session has expired` | No usable token | Log in again (section 2) |
570
+ | 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 |
571
+ | `No application "<slug>" in <company>` | No application by that slug in that company | `sl hermes applications` lists them with their companies |
572
+ | `INSUFFICIENT_CREDITS` | Too few credits for the reservation, or no billing account | Fewer records or dimensions; `sl use company` shows each company's credits |
573
+ | Outreach `rate_limited` / account `pausedUntil` | LinkedIn refused; the account is paused | Wait; never resend with a new external id |
574
+ | Outreach `account_disconnected` | The account lost its session | The owner reconnects it; nothing to retry |
575
+ | `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 |
576
+
577
+ Exit codes: `1` a GraphQL or business error, `2` no usable session, `3` endpoint unreachable or an HTTP
578
+ failure, `4` the token or the acting company was refused, `5` a subscription or `--wait` timed out.
579
+ Set `SL_DEBUG=1` to print the query, variables and response of a failing call.