@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/README.md +149 -130
- package/dist/index.js +712 -70
- 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/README.md
CHANGED
|
@@ -1,6 +1,11 @@
|
|
|
1
1
|
# Sortlist CLI (`sl`)
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
The command line for the Sortlist API: find companies and contacts, watch buying signals, reach
|
|
4
|
+
prospects on LinkedIn and manage your account, from a terminal or from an AI agent.
|
|
5
|
+
|
|
6
|
+
Its commands are not written one by one: `sl` reads the API's own description and offers every
|
|
7
|
+
operation published for it. When a new operation is published, its command appears on its own,
|
|
8
|
+
without a new release of the CLI.
|
|
4
9
|
|
|
5
10
|
## Install
|
|
6
11
|
|
|
@@ -8,200 +13,214 @@ Requires Node 24 or later.
|
|
|
8
13
|
|
|
9
14
|
```bash
|
|
10
15
|
npm install -g @sortlist/cli
|
|
11
|
-
sl
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
## Local development
|
|
15
|
-
|
|
16
|
-
```bash
|
|
17
|
-
cd cli
|
|
18
|
-
npm install
|
|
19
|
-
|
|
20
|
-
npx sl <command>
|
|
16
|
+
sl login
|
|
17
|
+
sl whoami
|
|
21
18
|
```
|
|
22
19
|
|
|
23
|
-
|
|
20
|
+
## Signing in
|
|
24
21
|
|
|
25
22
|
```bash
|
|
26
|
-
|
|
23
|
+
sl login # opens your browser to sign in
|
|
24
|
+
sl whoami # who you are, the company you act for, its credits and plan
|
|
25
|
+
sl logout # removes your stored credentials
|
|
26
|
+
sl token # prints your access token, for scripts
|
|
27
27
|
```
|
|
28
28
|
|
|
29
|
-
|
|
29
|
+
`sl login --no-browser` prints a link and a code to open on any device instead.
|
|
30
30
|
|
|
31
|
-
|
|
31
|
+
### When commands are missing
|
|
32
32
|
|
|
33
|
-
|
|
34
|
-
sl login
|
|
35
|
-
sl
|
|
36
|
-
|
|
37
|
-
sl token # prints access token to stdout (useful for curl/scripts)
|
|
38
|
-
```
|
|
33
|
+
`sl` only shows what your account may use. An operation your account cannot reach has **no command
|
|
34
|
+
at all**, so it reports `unknown command` rather than a permission error. `sl login` warns when a
|
|
35
|
+
service gives your account nothing, and `sl operations` lists what you have. Access to some services
|
|
36
|
+
is granted per account: ask your Sortlist contact.
|
|
39
37
|
|
|
40
|
-
|
|
38
|
+
## Agent skills
|
|
41
39
|
|
|
42
|
-
|
|
40
|
+
`sl` ships two skills that teach Claude Code how to drive it:
|
|
43
41
|
|
|
44
|
-
|
|
42
|
+
| Skill | Teaches |
|
|
43
|
+
| ----------------------- | --------------------------------------------------------------------------------------------- |
|
|
44
|
+
| `sortlist-cli` | Every command: identity, companies, finding and revealing, signals, outreach, credits, errors |
|
|
45
|
+
| `sortlist-go-to-market` | A playbook from a business description to prospects, signal watchers and a LinkedIn campaign |
|
|
45
46
|
|
|
46
|
-
```
|
|
47
|
-
|
|
47
|
+
```bash
|
|
48
|
+
sl skill list # the skills bundled with this version
|
|
49
|
+
sl skill install # into ~/.claude/skills, or $CLAUDE_CONFIG_DIR/skills when set
|
|
50
|
+
sl skill install --project . # into ./.claude/skills, for one project
|
|
48
51
|
```
|
|
49
52
|
|
|
50
|
-
|
|
53
|
+
A skill already installed and identical is left alone; one that differs is refused unless
|
|
54
|
+
`--replace`, which backs it up first. `--dry-run` shows what would change. Start a new Claude Code
|
|
55
|
+
session afterwards: skills are read when a session starts. Then describe your business ("I sell X to
|
|
56
|
+
Y, find me customers"), or type `/sortlist-go-to-market`.
|
|
51
57
|
|
|
52
|
-
##
|
|
58
|
+
## Companies and credits
|
|
53
59
|
|
|
54
|
-
|
|
60
|
+
Everything you reveal, every lead a watcher delivers and every LinkedIn action is charged to the
|
|
61
|
+
credits of the company you act for.
|
|
55
62
|
|
|
56
63
|
```bash
|
|
57
|
-
sl use
|
|
58
|
-
sl use
|
|
59
|
-
sl use
|
|
60
|
-
sl
|
|
61
|
-
sl use me # go back to acting as yourself
|
|
64
|
+
sl use company # your companies, with each one's credits and plan
|
|
65
|
+
sl use company acme # act for acme from now on
|
|
66
|
+
sl use company --personal # back to your personal company
|
|
67
|
+
sl atlas find-contacts --company acme … # act for acme for one command only
|
|
62
68
|
```
|
|
63
69
|
|
|
64
|
-
|
|
70
|
+
Without a choice, `sl` acts for your personal company. `--company` and `sl use company` take a
|
|
71
|
+
company's slug or its id, and refuse a company you do not belong to. An action the company's credits
|
|
72
|
+
cannot cover is refused, and nothing is charged.
|
|
65
73
|
|
|
66
|
-
|
|
74
|
+
## Finding companies and contacts
|
|
67
75
|
|
|
68
|
-
|
|
76
|
+
```bash
|
|
77
|
+
sl atlas find-organizations --filter '{"domain":{"eq":"acme.com"}}' --page '{"first":1}' --wait
|
|
78
|
+
sl atlas find-contacts --organization-filter '{"domain":{"eq":"acme.com"}}' --wait \
|
|
79
|
+
--fields jobTitle,jobLevel
|
|
80
|
+
```
|
|
69
81
|
|
|
70
|
-
A
|
|
82
|
+
A find is a search: it is accepted at once and its page arrives as it fills, which `--wait` follows
|
|
83
|
+
until the last, `COMPLETE`, version. Places are Mercator ids: resolve a place first, then filter on
|
|
84
|
+
it.
|
|
71
85
|
|
|
72
86
|
```bash
|
|
73
|
-
sl
|
|
74
|
-
sl atlas find-contacts --company acme … # for one call
|
|
87
|
+
sl mercator resolve-locations --query "Brussels" --first 3 --fields id,name,subtype
|
|
75
88
|
```
|
|
76
89
|
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
90
|
+
Names, emails, phone numbers and LinkedIn profiles come back empty until revealed. Revealing is
|
|
91
|
+
explicit, with `--reveal` and the dimensions you want (`contactIdentity`, `contactEmailAddress`,
|
|
92
|
+
`contactPhoneNumber`, `contactLinkedinUrl`, and `organization…` for companies):
|
|
80
93
|
|
|
81
94
|
```bash
|
|
82
|
-
sl atlas find-contacts --
|
|
83
|
-
--fields firstName,emailAddress
|
|
84
|
-
sl atlas find-contacts --page '{"first":5}' --wait --reveal contactIdentity,contactEmailAddress \
|
|
85
|
-
--fields firstName,emailAddress # reveal, once per window
|
|
95
|
+
sl atlas find-contacts --filter '{"id":{"in":["<id>"]}}' --wait \
|
|
96
|
+
--reveal contactIdentity,contactEmailAddress --fields firstName,emailAddress
|
|
86
97
|
```
|
|
87
98
|
|
|
88
|
-
|
|
99
|
+
Each row says what happened to every dimension: `REVEALED` was charged by this call, `OWNED` was
|
|
100
|
+
already yours and costs nothing until the window closes, `LOCKED` was not asked for, `UNAVAILABLE`
|
|
101
|
+
does not exist. The page's `credits` is the bill.
|
|
89
102
|
|
|
90
|
-
##
|
|
103
|
+
## Watching buying signals
|
|
91
104
|
|
|
92
|
-
|
|
105
|
+
A watcher follows one signal (a fundraising, a job change, reactions to a LinkedIn post…) for an
|
|
106
|
+
ideal customer profile, and turns each match into a lead.
|
|
93
107
|
|
|
94
108
|
```bash
|
|
95
|
-
|
|
96
|
-
sl
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
109
|
+
sl signals watcher-definitions --fields slug,version,name,description
|
|
110
|
+
sl signals create-watcher --definition-slug <slug> --definition-version <n> \
|
|
111
|
+
--watcher-input '{…}' --lead-caps '[{"maximumLeads":20,"period":"P1D"}]' --wait \
|
|
112
|
+
--fields watcher.id,watcher.provisioningStatus
|
|
113
|
+
sl signals watcher-events --filter '{"acknowledged":{"eq":"UNACKNOWLEDGED"}}' \
|
|
114
|
+
--fields id,qualifiedAt,payload
|
|
115
|
+
sl signals acknowledge-watcher-events --ids '["<event id>"]'
|
|
100
116
|
```
|
|
101
117
|
|
|
102
|
-
|
|
118
|
+
Each lead is charged when it is delivered. Most signals deliver over hours or days. Read the leads
|
|
119
|
+
you have not handled yet, then acknowledge the ones you acted on, so the next read shows only what is
|
|
120
|
+
new. A watcher keeps running until you delete it (`sl signals delete-watcher --id <id>`).
|
|
121
|
+
|
|
122
|
+
## Reaching prospects on LinkedIn
|
|
103
123
|
|
|
104
|
-
|
|
124
|
+
Outreach sends one action at a time from a LinkedIn account it holds for you: a profile lookup, an
|
|
125
|
+
invitation, a message.
|
|
105
126
|
|
|
106
|
-
|
|
127
|
+
```bash
|
|
128
|
+
sl outreach create-outbound-channel-account --channel LINKEDIN --provider LINKEDIN_DIRECT \
|
|
129
|
+
--external-id me --fields channelAccount.id
|
|
130
|
+
sl outreach connect-linkedin <account id> BE
|
|
131
|
+
sl outreach perform-outbound-channel-action --channel-account-id <account id> \
|
|
132
|
+
--external-id ana-invite --action '{"linkedinInvite":{"memberId":"…","message":"…"}}' --wait
|
|
133
|
+
sl outreach outbound-channel-events --channel-account-id <account id> \
|
|
134
|
+
--filter '{"acknowledged":{"eq":"UNACKNOWLEDGED"}}'
|
|
135
|
+
```
|
|
107
136
|
|
|
108
|
-
|
|
137
|
+
`connect-linkedin` opens Chrome, Edge, Brave or Chromium on linkedin.com in a fresh, empty profile,
|
|
138
|
+
waits for you to sign in (a verification code included, up to `--timeout` minutes, 10 by default),
|
|
139
|
+
sends that session to your account and deletes the profile. The session is never printed or stored
|
|
140
|
+
anywhere else. Run it on your own computer, with a desktop session; `CHROME_PATH` picks the browser.
|
|
141
|
+
A snap or Flatpak Chromium cannot be driven this way.
|
|
109
142
|
|
|
110
|
-
|
|
143
|
+
The same `--external-id` returns the same action instead of sending twice. Acceptances and replies
|
|
144
|
+
arrive as events; acknowledge them once handled.
|
|
111
145
|
|
|
112
|
-
|
|
146
|
+
## Commands
|
|
113
147
|
|
|
114
|
-
Commands are
|
|
148
|
+
Commands are grouped by service: `sl atlas`, `sl mercator`, `sl signals`, `sl outreach`, `sl hermes`
|
|
149
|
+
(your account, companies, members and applications).
|
|
115
150
|
|
|
116
151
|
```bash
|
|
117
|
-
sl operations #
|
|
118
|
-
sl operations --search
|
|
119
|
-
sl <service> <
|
|
152
|
+
sl operations # every command your account has
|
|
153
|
+
sl operations --search watcher # filter by name or service
|
|
154
|
+
sl <service> <command> --help # its arguments and types
|
|
155
|
+
sl schema inspect <type> # the fields of an input or an enum
|
|
120
156
|
```
|
|
121
157
|
|
|
122
|
-
|
|
158
|
+
A command that needs a permission your account holds is marked `privileged: <scope>`, in
|
|
159
|
+
`sl operations` and at the top of its `--help`.
|
|
123
160
|
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
sl atlas find-organizations --help
|
|
127
|
-
sl mercator resolve-locations --query brussels
|
|
128
|
-
```
|
|
161
|
+
Arguments are kebab-case flags. Input objects, lists and JSON values take JSON:
|
|
162
|
+
`--filter '{"domain":{"in":["acme.com"]}}'`. A list of enum values also takes a comma-separated list.
|
|
129
163
|
|
|
130
|
-
Output is JSON when piped or with `--json`, and aligned
|
|
164
|
+
Output is JSON when piped or with `--json`, and aligned blocks in a terminal. Ids are never
|
|
165
|
+
truncated: they are what you paste into the next command.
|
|
131
166
|
|
|
132
|
-
|
|
167
|
+
| Flag | Description |
|
|
168
|
+
| ------------------ | ------------------------------------------------------------------------------- |
|
|
169
|
+
| `--fields <a,b.c>` | Fields to include; dotted paths reach nested fields and a list's counters |
|
|
170
|
+
| `--exclude <a,b>` | Fields to leave out |
|
|
171
|
+
| `--depth <n>` | How deep nested fields are selected (default 0); deprecated fields are left out |
|
|
172
|
+
| `--wait [seconds]` | For a command that answers later, wait for the result and print it |
|
|
173
|
+
| `--company <slug>` | Act for this company for this command only |
|
|
174
|
+
| `--json` | JSON output, also the default when the output is not a terminal |
|
|
175
|
+
| `--no-color` | No colours |
|
|
133
176
|
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
| `--depth <n>` | Selection depth for nested fields (default: 0); deprecated fields are left out |
|
|
137
|
-
| `--fields <a,b,c>` | Comma-separated fields to include, deprecated ones too when named |
|
|
138
|
-
| `--exclude <a,b,c>` | Comma-separated fields to exclude |
|
|
177
|
+
A request that asks for too much at once is refused as `Query too complex` (or `too deep`): select
|
|
178
|
+
fewer fields with `--fields`, or a smaller page with `--first`.
|
|
139
179
|
|
|
140
|
-
##
|
|
180
|
+
## Running unattended
|
|
141
181
|
|
|
142
|
-
|
|
182
|
+
`sl login` is interactive and its session expires, so it cannot back a scheduled job. An
|
|
183
|
+
**application credential** can: a client id and secret that every command exchanges for a
|
|
184
|
+
short-lived token.
|
|
143
185
|
|
|
144
186
|
```bash
|
|
145
|
-
sl
|
|
146
|
-
```
|
|
187
|
+
sl hermes create-application-credential --application-id <id> --name ci # the secret is shown once
|
|
147
188
|
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
189
|
+
export SORTLIST_CLIENT_ID=slc_...
|
|
190
|
+
export SORTLIST_CLIENT_SECRET=sl_live_...
|
|
191
|
+
```
|
|
151
192
|
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
| `--json` | Force JSON output (auto-enabled when non-TTY) |
|
|
157
|
-
| `--no-color` | Disable colored output |
|
|
193
|
+
With both set, every command acts as the application, for its company. A credential reaches finding
|
|
194
|
+
and revealing companies and contacts, and places, today; signals and outreach still need a signed-in
|
|
195
|
+
person. Managing credentials always needs a person, so a leaked secret cannot create more. Revoking a
|
|
196
|
+
credential stops new tokens at once.
|
|
158
197
|
|
|
159
|
-
|
|
198
|
+
To act as an application yourself for a while, without storing a secret:
|
|
160
199
|
|
|
161
200
|
```bash
|
|
162
|
-
sl
|
|
163
|
-
sl
|
|
164
|
-
sl config use-staging
|
|
165
|
-
sl config use-production
|
|
201
|
+
sl use application <company>/<slug> # a short-lived token; the credential is revoked at once
|
|
202
|
+
sl use me # back to yourself
|
|
166
203
|
```
|
|
167
204
|
|
|
168
|
-
The three `use-*` commands and `sl config set endpoint` exist only when running from a source checkout — a published build always targets production.
|
|
169
|
-
|
|
170
205
|
## State on disk
|
|
171
206
|
|
|
172
|
-
Everything
|
|
207
|
+
Everything `sl` remembers lives in `~/.sortlist/`. Nothing there is a long-lived secret, and
|
|
208
|
+
`sl logout` removes the tokens.
|
|
173
209
|
|
|
174
|
-
| File | Holds
|
|
175
|
-
| -------------------------- |
|
|
176
|
-
| `config.json` |
|
|
177
|
-
| `credentials.json` | your
|
|
178
|
-
| `application-session.json` |
|
|
179
|
-
| `schema.json` | the
|
|
180
|
-
|
|
181
|
-
`endpoint` and `tokenEndpoint` describe an environment rather than an identity, so `sl logout` keeps them and drops the rest.
|
|
210
|
+
| File | Holds | Lifetime |
|
|
211
|
+
| -------------------------- | ------------------------------------------------ | ------------------------------------------ |
|
|
212
|
+
| `config.json` | the company you act for, your last known account | until changed; `sl config reset` clears it |
|
|
213
|
+
| `credentials.json` | your access and refresh tokens, mode `0600` | your session; `sl login` replaces it |
|
|
214
|
+
| `application-session.json` | a token from `sl use application`, mode `0600` | one token lifetime; `sl use me` removes it |
|
|
215
|
+
| `schema.json` | the commands available to your account | one hour; `sl schema refresh` rebuilds it |
|
|
182
216
|
|
|
183
217
|
## Exit codes
|
|
184
218
|
|
|
185
|
-
| Code | Meaning
|
|
186
|
-
| ---- |
|
|
187
|
-
| `0` | success
|
|
188
|
-
| `1` | bad usage,
|
|
189
|
-
| `2` | not
|
|
190
|
-
| `3` | the
|
|
191
|
-
| `4` |
|
|
192
|
-
|
|
193
|
-
## Code generation
|
|
194
|
-
|
|
195
|
-
The only build-time step is `npm run codegen`, which generates TypeScript types for hand-written operations (auth flow) using `graphql-codegen`. It reads `$SUPERGRAPH_PATH` when set, and otherwise `../backend/supergraph.graphql`.
|
|
196
|
-
|
|
197
|
-
```bash
|
|
198
|
-
npm run generate # alias for npm run codegen
|
|
199
|
-
npm run codegen # regenerate TypeScript types for hand-written operations
|
|
200
|
-
```
|
|
201
|
-
|
|
202
|
-
This is only needed when:
|
|
203
|
-
|
|
204
|
-
- The hand-written operations in `src/graphql/operations/` change
|
|
205
|
-
- The schema types referenced by those operations change in the supergraph
|
|
206
|
-
|
|
207
|
-
All dynamically generated commands (service operations) require no build step — they are derived entirely from runtime introspection.
|
|
219
|
+
| Code | Meaning |
|
|
220
|
+
| ---- | ------------------------------------------------------------------------------ |
|
|
221
|
+
| `0` | success |
|
|
222
|
+
| `1` | bad usage, or the API refused the operation |
|
|
223
|
+
| `2` | not signed in, the session expired, or a credential did not exchange |
|
|
224
|
+
| `3` | the API could not be reached, or answered with an HTTP error |
|
|
225
|
+
| `4` | your token, or the company you act for, was refused |
|
|
226
|
+
| `5` | `--wait` or `connect-linkedin` ran out of time; the request may still complete |
|