@sortlist/cli 0.56.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/README.md +149 -130
- package/dist/index.js +732 -109
- package/dist/index.js.map +1 -1
- package/package.json +2 -1
- package/skills/sortlist-cli/SKILL.md +579 -0
- package/skills/sortlist-go-to-market/SKILL.md +233 -0
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@sortlist/cli",
|
|
3
|
-
"version": "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.
|