@sortlist/cli 0.37.0 → 0.38.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 +78 -13
- package/dist/index.js +736 -339
- package/dist/index.js.map +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -33,26 +33,59 @@ 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
|
-
##
|
|
38
|
+
## Acting as an application locally
|
|
40
39
|
|
|
41
|
-
|
|
40
|
+
`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
41
|
|
|
43
42
|
```bash
|
|
44
|
-
sl
|
|
45
|
-
sl
|
|
46
|
-
sl
|
|
43
|
+
sl use application <id> # act as it for one token lifetime
|
|
44
|
+
sl whoami # confirms: person or application
|
|
45
|
+
sl use me # go back to acting as yourself
|
|
47
46
|
```
|
|
48
47
|
|
|
49
|
-
|
|
48
|
+
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
|
+
|
|
50
|
+
## Unattended authentication
|
|
51
|
+
|
|
52
|
+
`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.
|
|
53
|
+
|
|
54
|
+
```bash
|
|
55
|
+
# Create a credential — the secret is in the response and shown only once
|
|
56
|
+
sl create-application-credential --application-id <id> --name continuous-integration
|
|
57
|
+
|
|
58
|
+
export SORTLIST_CLIENT_ID=slc_...
|
|
59
|
+
export SORTLIST_CLIENT_SECRET=sl_live_...
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
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.
|
|
63
|
+
|
|
64
|
+
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
|
+
|
|
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".
|
|
67
|
+
|
|
68
|
+
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
|
+
|
|
70
|
+
## Federation operations
|
|
71
|
+
|
|
72
|
+
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:
|
|
50
73
|
|
|
51
74
|
```bash
|
|
52
|
-
sl
|
|
53
|
-
sl
|
|
75
|
+
sl operations # list them all, grouped by queries and mutations
|
|
76
|
+
sl operations --search company # filter by operation or subgraph name
|
|
77
|
+
sl <operation> --help # flags for one operation
|
|
54
78
|
```
|
|
55
79
|
|
|
80
|
+
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:
|
|
81
|
+
|
|
82
|
+
```bash
|
|
83
|
+
sl organizations --first 5
|
|
84
|
+
sl create-watcher --help
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
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.
|
|
88
|
+
|
|
56
89
|
Each operation supports:
|
|
57
90
|
|
|
58
91
|
| Flag | Description |
|
|
@@ -69,21 +102,53 @@ The CLI fetches the GraphQL schema via introspection on startup and caches it lo
|
|
|
69
102
|
sl schema refresh
|
|
70
103
|
```
|
|
71
104
|
|
|
72
|
-
The endpoint
|
|
105
|
+
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
106
|
|
|
74
107
|
## Global options
|
|
75
108
|
|
|
76
109
|
| Flag | Description |
|
|
77
110
|
| ------------------ | ----------------------------------------------------------------------- |
|
|
78
|
-
| `--endpoint <url>` | Override federation endpoint (default: `
|
|
111
|
+
| `--endpoint <url>` | Override federation endpoint (default: `https://federation.sortlist.com/graphql`) |
|
|
79
112
|
| `--json` | Force JSON output (auto-enabled when non-TTY) |
|
|
80
113
|
| `--no-color` | Disable colored output |
|
|
81
114
|
|
|
82
|
-
The endpoint can also be set via the `SL_ENDPOINT` environment variable or `~/.sortlist/config.json`.
|
|
115
|
+
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
|
+
|
|
117
|
+
```bash
|
|
118
|
+
sl config show # what you are currently talking to
|
|
119
|
+
sl config use-local # localhost:4020 (federation router) + localhost:8003 (Hermes)
|
|
120
|
+
sl config use-staging
|
|
121
|
+
sl config use-production
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
The three `use-*` commands and `sl config set endpoint` exist only when running from a source checkout — a published build always targets production.
|
|
125
|
+
|
|
126
|
+
## State on disk
|
|
127
|
+
|
|
128
|
+
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
|
+
|
|
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 |
|
|
136
|
+
|
|
137
|
+
`endpoint` and `tokenEndpoint` describe an environment rather than an identity, so `sl logout` keeps them and drops the rest.
|
|
138
|
+
|
|
139
|
+
## Exit codes
|
|
140
|
+
|
|
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 |
|
|
83
148
|
|
|
84
149
|
## Code generation
|
|
85
150
|
|
|
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
|
|
151
|
+
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
152
|
|
|
88
153
|
```bash
|
|
89
154
|
npm run generate # alias for npm run codegen
|