@sortlist/cli 0.38.0 → 0.40.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 +69 -19
- package/dist/index.js +365 -88
- package/dist/index.js.map +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -35,6 +35,18 @@ sl whoami # shows current user
|
|
|
35
35
|
sl token # prints access token to stdout (useful for curl/scripts)
|
|
36
36
|
```
|
|
37
37
|
|
|
38
|
+
### When commands are missing
|
|
39
|
+
|
|
40
|
+
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 organizations` reports `unknown command`, not a permission error.
|
|
41
|
+
|
|
42
|
+
`sl login` warns when a service came back with nothing:
|
|
43
|
+
|
|
44
|
+
```
|
|
45
|
+
⚠ No scope granted for: atlas, billing, core, signals.
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
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.
|
|
49
|
+
|
|
38
50
|
## Acting as an application locally
|
|
39
51
|
|
|
40
52
|
`sl use application <id>` 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.
|
|
@@ -47,6 +59,43 @@ sl use me # go back to acting as yourself
|
|
|
47
59
|
|
|
48
60
|
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.
|
|
49
61
|
|
|
62
|
+
## Acting for a company
|
|
63
|
+
|
|
64
|
+
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 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, no company is named: a staff account is served without anything being counted, anyone else is refused until they pick one. An application belongs to exactly one company, so acting as one needs no header.
|
|
65
|
+
|
|
66
|
+
```bash
|
|
67
|
+
sl config set company spin42 # for every command from now on
|
|
68
|
+
sl contacts --company spin42 … # for one call
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
## Revealing contact details
|
|
72
|
+
|
|
73
|
+
Reading 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 the fields they unlock (`identity`, `emailAddress`, `phoneNumber`, `linkedinUrl`) or `all`. Whoever may read contacts may reveal them: nothing beyond `atlas/organization:read` is needed. Every Atlas command is checked with Hermes first: you must still be a member of the company you act for, 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.
|
|
74
|
+
|
|
75
|
+
```bash
|
|
76
|
+
sl contacts --first 5 --fields firstName,lastName,emailAddress # what you own
|
|
77
|
+
sl contacts --first 5 --fields firstName,lastName,emailAddress --reveal identity,emailAddress # reveal, once per window
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
```
|
|
81
|
+
Q29udGFjdC8wMTllZGE0Mi1lYTAyLTc0YTAtYTgyMS0wZmIxNmUwNWQzZmY
|
|
82
|
+
firstName Ada
|
|
83
|
+
lastName Lovelace
|
|
84
|
+
emailAddress ada@acme.com
|
|
85
|
+
reveals CONTACT_IDENTITY REVEALED until 2026-12-11 23:59:59
|
|
86
|
+
CONTACT_EMAIL_ADDRESS REVEALED until 2026-12-11 23:59:59
|
|
87
|
+
|
|
88
|
+
credits
|
|
89
|
+
held 2
|
|
90
|
+
used 2
|
|
91
|
+
byDimension CONTACT_IDENTITY 1
|
|
92
|
+
CONTACT_EMAIL_ADDRESS 1
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
Every row in a list is titled by its id, selected whether or not `--fields` names it, so a locked contact still has a handle to reveal it by. The `credits` block after the list is the bill of the command: `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; owned and unavailable cost nothing. Nothing is charged yet — these are the figures that would be.
|
|
96
|
+
|
|
97
|
+
`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. Every list argument typed as an enum accepts the same shorthand.
|
|
98
|
+
|
|
50
99
|
## Unattended authentication
|
|
51
100
|
|
|
52
101
|
`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.
|
|
@@ -63,7 +112,7 @@ With both set, **every** command authenticates as the application instead of as
|
|
|
63
112
|
|
|
64
113
|
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.
|
|
65
114
|
|
|
66
|
-
|
|
115
|
+
A credential carries the **platform's application scopes**, the same for every application and set by nobody: `atlas/organization:read`, which reads contacts and organizations and reveals them, metered on the application's company. Scopes are additive on this platform, so the token also reaches the baseline — Mercator's geography, the billing plan catalog — while 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".
|
|
67
116
|
|
|
68
117
|
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.
|
|
69
118
|
|
|
@@ -106,11 +155,12 @@ The cache is keyed by endpoint **and** by a fingerprint of your access token, so
|
|
|
106
155
|
|
|
107
156
|
## Global options
|
|
108
157
|
|
|
109
|
-
| Flag
|
|
110
|
-
|
|
|
111
|
-
| `--endpoint <url>`
|
|
112
|
-
| `--
|
|
113
|
-
| `--
|
|
158
|
+
| Flag | Description |
|
|
159
|
+
| ---------------------- | --------------------------------------------------------------------------------- |
|
|
160
|
+
| `--endpoint <url>` | Override federation endpoint (default: `https://federation.sortlist.com/graphql`) |
|
|
161
|
+
| `--company <slug\|id>` | Act for this company; sent as `X-Company-Id` and checked against your token |
|
|
162
|
+
| `--json` | Force JSON output (auto-enabled when non-TTY) |
|
|
163
|
+
| `--no-color` | Disable colored output |
|
|
114
164
|
|
|
115
165
|
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:
|
|
116
166
|
|
|
@@ -127,24 +177,24 @@ The three `use-*` commands and `sl config set endpoint` exist only when running
|
|
|
127
177
|
|
|
128
178
|
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.
|
|
129
179
|
|
|
130
|
-
| File
|
|
131
|
-
|
|
|
132
|
-
| `config.json`
|
|
133
|
-
| `credentials.json`
|
|
134
|
-
| `application-session.json` | one application token from `sl use application`, mode `0600`
|
|
135
|
-
| `schema.json`
|
|
180
|
+
| File | Holds | Lifetime |
|
|
181
|
+
| -------------------------- | ----------------------------------------------------------------------------- | -------------------------------------------------------- |
|
|
182
|
+
| `config.json` | endpoint, token endpoint, selected company, last known account | until changed; `sl config reset` clears it |
|
|
183
|
+
| `credentials.json` | your own access and refresh tokens, mode `0600` | the Auth0 session; `sl login` replaces it |
|
|
184
|
+
| `application-session.json` | one application token from `sl use application`, mode `0600` | one token lifetime, then ignored; `sl use me` removes it |
|
|
185
|
+
| `schema.json` | the introspected schema, keyed by endpoint **and** a fingerprint of the token | one hour; `sl schema refresh` forces a refetch |
|
|
136
186
|
|
|
137
187
|
`endpoint` and `tokenEndpoint` describe an environment rather than an identity, so `sl logout` keeps them and drops the rest.
|
|
138
188
|
|
|
139
189
|
## Exit codes
|
|
140
190
|
|
|
141
|
-
| Code | Meaning
|
|
142
|
-
|
|
|
143
|
-
| `0`
|
|
144
|
-
| `1`
|
|
145
|
-
| `2`
|
|
146
|
-
| `3`
|
|
147
|
-
| `4`
|
|
191
|
+
| Code | Meaning |
|
|
192
|
+
| ---- | ------------------------------------------------------------------------------------ |
|
|
193
|
+
| `0` | success |
|
|
194
|
+
| `1` | bad usage, missing state, or an operation the server refused |
|
|
195
|
+
| `2` | not authenticated: no token, an expired one, or a credential that would not exchange |
|
|
196
|
+
| `3` | the endpoint could not be reached, or answered with an HTTP error |
|
|
197
|
+
| `4` | acting as an application, and the operation belongs to the management API |
|
|
148
198
|
|
|
149
199
|
## Code generation
|
|
150
200
|
|