@sortlist/cli 0.36.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 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
- ## Service operations
38
+ ## Acting as an application locally
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
+ `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 atlas <operation> # company and contact enrichment
45
- sl marketplace <operation> # agencies, projects, opportunities, quotes
46
- sl hermes <operation> # OAuth/auth operations
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
- Use `--help` on any service to list available operations (grouped by queries and mutations):
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 atlas --help
53
- sl marketplace --help
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 can be configured via `--endpoint`, `SL_ENDPOINT` env var, or `~/.sortlist/config.json`.
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: `http://localhost:4020/graphql`) |
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 the schema from `../backend/supergraph.graphql`.
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
package/bin/sl.mjs CHANGED
@@ -52,22 +52,35 @@ if (process.env.SL_PREFER_LOCAL !== '0') {
52
52
  }
53
53
  }
54
54
 
55
- const tsxPath = resolve(selfRoot, 'node_modules/.bin/tsx');
56
- const entryPoint = resolve(selfRoot, 'src/index.ts');
55
+ // Published builds ship a bundled dist/; source checkouts run TypeScript via
56
+ // tsx — even when a locally-built dist/ exists, so stale bundles never shadow
57
+ // the live source.
58
+ const distEntry = resolve(selfRoot, 'dist/index.js');
59
+ const useDist = existsSync(resolve(selfRoot, '.published')) && existsSync(distEntry);
57
60
 
58
- if (!existsSync(tsxPath)) {
59
- console.error(`sl: missing dependency at ${tsxPath} — run \`npm install\` in ${selfRoot}`);
60
- process.exit(1);
61
+ let command;
62
+ let args;
63
+ if (useDist) {
64
+ command = process.execPath;
65
+ args = [distEntry, ...process.argv.slice(2)];
66
+ } else {
67
+ const tsxPath = resolve(selfRoot, 'node_modules/.bin/tsx');
68
+ if (!existsSync(tsxPath)) {
69
+ console.error(`sl: missing dependency at ${tsxPath} — run \`npm install\` in ${selfRoot}`);
70
+ process.exit(1);
71
+ }
72
+ command = tsxPath;
73
+ args = [resolve(selfRoot, 'src/index.ts'), ...process.argv.slice(2)];
61
74
  }
62
75
 
63
76
  try {
64
- execFileSync(tsxPath, [entryPoint, ...process.argv.slice(2)], {
77
+ execFileSync(command, args, {
65
78
  stdio: 'inherit',
66
79
  env: { ...process.env, NODE_OPTIONS: [process.env.NODE_OPTIONS, '--enable-source-maps'].filter(Boolean).join(' ') },
67
80
  });
68
81
  } catch (err) {
69
82
  if (err.code === 'ENOENT') {
70
- console.error(`sl: failed to spawn tsx (${err.message})`);
83
+ console.error(`sl: failed to spawn ${command} (${err.message})`);
71
84
  }
72
85
  process.exit(err.status ?? 1);
73
86
  }