@sortlist/cli 0.37.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
@@ -33,26 +33,108 @@ sl login # opens browser for authentication
33
33
  sl logout # clears stored credentials
34
34
  sl whoami # shows current user
35
35
  sl token # prints access token to stdout (useful for curl/scripts)
36
- sl switch # switch active agency context
37
36
  ```
38
37
 
39
- ## Service operations
38
+ ### When commands are missing
40
39
 
41
- Every query and mutation from the federated GraphQL schema is available as a CLI command. Operations are discovered at runtime via introspection and grouped by service based on the `[service]` prefix in field descriptions:
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
+
50
+ ## Acting as an application locally
51
+
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.
42
53
 
43
54
  ```bash
44
- sl atlas <operation> # company and contact enrichment
45
- sl marketplace <operation> # agencies, projects, opportunities, quotes
46
- sl hermes <operation> # OAuth/auth operations
55
+ sl use application <id> # act as it for one token lifetime
56
+ sl whoami # confirms: person or application
57
+ sl use me # go back to acting as yourself
47
58
  ```
48
59
 
49
- Use `--help` on any service to list available operations (grouped by queries and mutations):
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.
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.
50
65
 
51
66
  ```bash
52
- sl atlas --help
53
- sl marketplace --help
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
+
99
+ ## Unattended authentication
100
+
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.
102
+
103
+ ```bash
104
+ # Create a credential — the secret is in the response and shown only once
105
+ sl create-application-credential --application-id <id> --name continuous-integration
106
+
107
+ export SORTLIST_CLIENT_ID=slc_...
108
+ export SORTLIST_CLIENT_SECRET=sl_live_...
54
109
  ```
55
110
 
111
+ 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.
112
+
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.
114
+
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".
116
+
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.
118
+
119
+ ## Federation operations
120
+
121
+ Every query and mutation on the supergraph is available as a command, discovered at runtime through introspection. Operation names are unique across the supergraph, so they are **not** namespaced by subgraph:
122
+
123
+ ```bash
124
+ sl operations # list them all, grouped by queries and mutations
125
+ sl operations --search company # filter by operation or subgraph name
126
+ sl <operation> --help # flags for one operation
127
+ ```
128
+
129
+ They are hidden from the root help — listing seventy-odd entries there would bury the curated commands above — but they are ordinary top-level commands:
130
+
131
+ ```bash
132
+ sl organizations --first 5
133
+ sl create-watcher --help
134
+ ```
135
+
136
+ 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.
137
+
56
138
  Each operation supports:
57
139
 
58
140
  | Flag | Description |
@@ -69,21 +151,54 @@ The CLI fetches the GraphQL schema via introspection on startup and caches it lo
69
151
  sl schema refresh
70
152
  ```
71
153
 
72
- The endpoint can be configured via `--endpoint`, `SL_ENDPOINT` env var, or `~/.sortlist/config.json`.
154
+ 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.
73
155
 
74
156
  ## Global options
75
157
 
76
- | Flag | Description |
77
- | ------------------ | ----------------------------------------------------------------------- |
78
- | `--endpoint <url>` | Override federation endpoint (default: `http://localhost:4020/graphql`) |
79
- | `--json` | Force JSON output (auto-enabled when non-TTY) |
80
- | `--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 |
164
+
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:
166
+
167
+ ```bash
168
+ sl config show # what you are currently talking to
169
+ sl config use-local # localhost:4020 (federation router) + localhost:8003 (Hermes)
170
+ sl config use-staging
171
+ sl config use-production
172
+ ```
173
+
174
+ The three `use-*` commands and `sl config set endpoint` exist only when running from a source checkout — a published build always targets production.
175
+
176
+ ## State on disk
177
+
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.
179
+
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 |
186
+
187
+ `endpoint` and `tokenEndpoint` describe an environment rather than an identity, so `sl logout` keeps them and drops the rest.
188
+
189
+ ## Exit codes
81
190
 
82
- The endpoint can also be set via the `SL_ENDPOINT` environment variable or `~/.sortlist/config.json`.
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 |
83
198
 
84
199
  ## Code generation
85
200
 
86
- The only build-time step is `npm run codegen`, which generates TypeScript types for hand-written operations (auth flow) using `graphql-codegen`. It reads the schema from `../backend/supergraph.graphql`.
201
+ 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`.
87
202
 
88
203
  ```bash
89
204
  npm run generate # alias for npm run codegen