@sortlist/cli 0.57.0 → 0.59.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,6 +1,11 @@
1
1
  # Sortlist CLI (`sl`)
2
2
 
3
- Command-line interface for the Sortlist platform. Talks to the GraphQL federation endpoint and dynamically discovers available operations via introspection.
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 <command>
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
- Tip: add an alias to your shell profile for convenience:
20
+ ## Signing in
24
21
 
25
22
  ```bash
26
- alias sl='npx sl'
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
- ## Authentication
29
+ `sl login --no-browser` prints a link and a code to open on any device instead.
30
30
 
31
- Uses the [Device Authorization Grant](https://datatracker.ietf.org/doc/html/rfc8628) flow via Hermes. Tokens are stored at `~/.sortlist/credentials.json`.
31
+ ### When commands are missing
32
32
 
33
- ```bash
34
- sl login # opens browser for authentication
35
- sl logout # clears stored credentials
36
- sl whoami # shows current user
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
- ### When commands are missing
38
+ ## Agent skills
41
39
 
42
- The CLI builds its commands from the schema the federation router returns, and the router filters that schema by the scopes in your token. A service you hold no scope for therefore has **no commands at all** — `sl atlas find-organizations` reports `unknown command`, not a permission error.
40
+ `sl` ships two skills that teach Claude Code how to drive it:
43
41
 
44
- `sl login` warns when a service came back with nothing:
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
- ⚠ No scope granted for: atlas, billing, core, signals.
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
- The cause is a role assignment in the tenant you logged into, not a CLI setting: Auth0 grants requested scopes by exact string match against your assigned permissions and drops the rest silently. Ask an administrator to assign you a role, then run `sl login` again. `sl token` shows what you actually hold.
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
- ## Acting as an application locally
58
+ ## Companies and credits
53
59
 
54
- `sl use application <application>` creates a credential, exchanges it for a token, and **revokes the credential immediately**. Nothing reusable is stored: what lands in `~/.sortlist/` is a bearer token that expires, and a subgraph verifies it by signature against Hermes' published keys rather than by asking whether the credential still lives.
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 application ci # by slug, in the company you act for (your personal one by default)
58
- sl use application acme/ci # by slug, naming the company
59
- sl use application <id> # by the application's id
60
- sl whoami # confirms: person or application
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
- An application's slug is derived from its name when it is created (`Organization importer` → `organization-importer`) and stays the same if it is renamed. It is unique within its company, so two companies can each own a `ci`. `sl hermes applications` lists the applications of every company you belong to, with their slugs, and the developer portal shows both the slug and the id on the application's page.
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
- When the token expires, renewing needs your own login again — so this is a local convenience, never a path to unattended use. For that, see below.
74
+ ## Finding companies and contacts
67
75
 
68
- ## Acting for a company
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 person can belong to several companies, and a subgraph that counts usage — Atlas records which contact details it hands out — needs to know which one a call is for. Every authenticated request carries that company as an `X-Company-Id` header, taken from `--company` or from `sl config set company`. Both take the company's slug or its GraphQL `id`, as `sl hermes companies` lists them; a slug costs one lookup per command, and a raw uuid is refused. The subgraph checks it against the companies your token lists and refuses the request outright when it names one you do not belong to. Without either, the request names your personal company, looked up once per command, staff elevation included, so that is where Atlas, Signals and Outreach count what you use. An application belongs to exactly one company, so acting as one needs no header.
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 config set company acme # for every command from now on
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
- ## Revealing contact details
78
-
79
- Finding a contact shows only the reach details your company already owns — a name, an email, a phone, a LinkedIn profile each come back empty until revealed — and Atlas says so beside every row. Revealing is explicit, in the same command, with `--reveal`: a comma-separated list of dimensions named after what they unlock (`contactIdentity`, `contactEmailAddress`, `contactPhoneNumber`, `contactLinkedinUrl`, and `organization…` for organizations). Finding and revealing need no scope, only a company to act for, which is your personal company unless you name another. Each reveal is charged to the company's credits. When you name a company, Atlas checks with Hermes first: you must still be a member of it, or the application must belong to it, otherwise the whole command is refused with a 403 and nothing is recorded — the token's claim was stamped at login and can outlive a membership.
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 --page '{"first":5}' --wait \
83
- --fields firstName,emailAddress # what you own
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
- The finds are searches: the mutation is acknowledged at once and the page arrives on a subscription, which `--wait` listens to. Atlas sends a page again as it fills it, and `--wait` prints its last, `COMPLETE`, version. Each edge's `reveals` says what happened to every dimension: `REVEALED` was recorded by this call, `OWNED` means the window is still running and nothing was counted again, `LOCKED` means Atlas has it and nobody asked, `UNAVAILABLE` means Atlas has nothing, and nothing is counted. The page's `credits` is the bill: `held` is the ceiling reserved before the page was read (rows × dimensions asked), `used` what it actually consumed, one unit per dimension revealed on one row. In staging and production those units are taken from the company's credit balance; a local Atlas only logs them. Every list argument typed as an enum accepts the same comma-separated shorthand.
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
- ## Unattended authentication
103
+ ## Watching buying signals
91
104
 
92
- `sl login` is interactive and its refresh token expires, so it cannot back a continuous integration job. An **application credential** can: a client id and secret that every command exchanges for a short-lived token.
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
- # Create a credential — the secret is in the response and shown only once
96
- sl hermes create-application-credential --application-id <id> --name continuous-integration
97
-
98
- export SORTLIST_CLIENT_ID=slc_...
99
- export SORTLIST_CLIENT_SECRET=sl_live_...
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
- With both set, **every** command authenticates as the application instead of as you. Managing credentials is the one exception: Hermes refuses its own tokens there, so a leaked secret cannot mint more.
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
- The secret is shown exactly once, because only its digest is stored. Revoking stops new tokens immediately; a token already issued stays valid until it expires.
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
- A credential's token carries **no scope**. It reaches what a plain login does: Atlas's `find-contacts` and `find-organizations`, whose reveals are charged to the application's company, Mercator's geography and the billing plan catalog. The unmetered `contacts` and `organizations` lists, Signals operations and every staff read stay out of reach. Hermes' own management API is **not** part of what a credential reaches: Hermes refuses the tokens it mints, which is what stops a leaked secret from minting more. The derivation is in `backend/hermes/docs/api.md` in the platform monorepo, under "What a minted token reaches".
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
- The token endpoint is a different host from the federation endpoint, so it cannot be derived. `sl config use-production` / `use-staging` / `use-local` set both together; `sl config set tokenEndpoint <url>` sets it on its own.
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
- ## Federation operations
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
- The CLI offers an operation only when its subgraph tags the root field for it, with `@tag(name: "cli")` (`tags: [{ name: "cli" }]` on the Ruby field). Every other query, mutation and subscription stays reachable through the API, but has no command. Exposing one more is a backend change: tag the field, and the command appears within the hour, with no CLI release.
146
+ ## Commands
113
147
 
114
- Commands are discovered at runtime through introspection and grouped under the subgraph that serves them, Hermes's account and company operations included: `sl hermes companies`, `sl hermes applications`, `sl hermes create-application`. Every Hermes operation a person can call is offered. The names they had at the top level before (`sl companies`, `sl create-application-credential`) still work, but are no longer listed.
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 # list them all, grouped by queries, mutations and subscriptions
118
- sl operations --search organization # filter by operation or subgraph name
119
- sl <service> <operation> --help # flags for one operation
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
- An operation whose subgraph declares a scope for it (`@requiresScopes`) is listed as `privileged: <scopes>`, and its `--help` opens with the same line. Everything else works with a plain login. The router hides a privileged operation from a token that lacks the scope, so it may be missing from the list rather than marked.
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
- ```bash
125
- sl hermes companies
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 key/value blocks in a terminal. Ids are never truncated — they are what you paste into the next command — so records are printed as blocks rather than a table.
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
- Each operation supports:
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
- | Flag | Description |
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
- ## Schema management
180
+ ## Running unattended
141
181
 
142
- The CLI fetches the GraphQL schema via introspection on startup and caches it locally at `~/.sortlist/schema.json` (1-hour TTL). To force a refresh:
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 schema refresh
146
- ```
187
+ sl hermes create-application-credential --application-id <id> --name ci # the secret is shown once
147
188
 
148
- The cache is keyed by endpoint **and** by a fingerprint of your access token, so switching environments or logging in as someone else re-introspects rather than reusing the previous schema.
149
-
150
- ## Global options
189
+ export SORTLIST_CLIENT_ID=slc_...
190
+ export SORTLIST_CLIENT_SECRET=sl_live_...
191
+ ```
151
192
 
152
- | Flag | Description |
153
- | ---------------------- | --------------------------------------------------------------------------------- |
154
- | `--endpoint <url>` | Override federation endpoint (default: `https://federation.sortlist.com/graphql`) |
155
- | `--company <slug\|id>` | Act for this company; sent as `X-Company-Id` and checked against your token |
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
- The endpoint can also be set via the `SL_ENDPOINT` environment variable or `~/.sortlist/config.json`. **The default targets production**, so point the CLI somewhere else deliberately:
198
+ To act as an application yourself for a while, without storing a secret:
160
199
 
161
200
  ```bash
162
- sl config show # what you are currently talking to
163
- sl config use-local # localhost:4020 (federation router) + localhost:8003 (Hermes)
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 the CLI remembers lives in `~/.sortlist/`. Nothing here is a long-lived secret: the two token files expire on their own, and `sl logout` removes all three.
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 | Lifetime |
175
- | -------------------------- | ----------------------------------------------------------------------------- | -------------------------------------------------------- |
176
- | `config.json` | endpoint, token endpoint, selected company, last known account | until changed; `sl config reset` clears it |
177
- | `credentials.json` | your own access and refresh tokens, mode `0600` | the Auth0 session; `sl login` replaces it |
178
- | `application-session.json` | one application token from `sl use application`, mode `0600` | one token lifetime, then ignored; `sl use me` removes it |
179
- | `schema.json` | the introspected schema, keyed by endpoint **and** a fingerprint of the token | one hour; `sl schema refresh` forces a refetch |
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, missing state, or an operation the server refused |
189
- | `2` | not authenticated: no token, an expired one, or a credential that would not exchange |
190
- | `3` | the endpoint could not be reached, or answered with an HTTP error |
191
- | `4` | acting as an application, and the operation belongs to the management API |
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 |