@sortlist/cli 0.38.0 → 0.39.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
@@ -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
- An application credential carries **no scopes**. Scopes are additive on this platform, so a credential reaches the baseline — the whole Hermes management surface, Mercator's geography, the billing plan catalog — while Atlas enrichment and Signals operations stay behind their scopes and will be refused. The split is documented in `backend/hermes/docs/api.md` in the platform monorepo, under "What a minted token reaches".
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 | Description |
110
- | ------------------ | ----------------------------------------------------------------------- |
111
- | `--endpoint <url>` | Override federation endpoint (default: `https://federation.sortlist.com/graphql`) |
112
- | `--json` | Force JSON output (auto-enabled when non-TTY) |
113
- | `--no-color` | Disable colored output |
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 | Holds | Lifetime |
131
- | --- | --- | --- |
132
- | `config.json` | endpoint, token endpoint, selected company, last known account | until changed; `sl config reset` clears it |
133
- | `credentials.json` | your own access and refresh tokens, mode `0600` | the Auth0 session; `sl login` replaces it |
134
- | `application-session.json` | one application token from `sl use application`, mode `0600` | one token lifetime, then ignored; `sl use me` removes it |
135
- | `schema.json` | the introspected schema, keyed by endpoint **and** a fingerprint of the token | one hour; `sl schema refresh` forces a refetch |
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` | success |
144
- | `1` | bad usage, missing state, or an operation the server refused |
145
- | `2` | not authenticated: no token, an expired one, or a credential that would not exchange |
146
- | `3` | the endpoint could not be reached, or answered with an HTTP error |
147
- | `4` | acting as an application, and the operation belongs to the management API |
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