@future-unknown/known 0.0.0-stage → 0.2.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
@@ -1,3 +1,568 @@
1
- # Temporary Holding Version
1
+ # known — the Known CLI
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ `known` is the command-line interface to the [Known](https://known.info) platform.
4
+ It signs you in to an organization and talks to the Known API over JSON-RPC.
5
+
6
+ **A session is one sign-in** — an endpoint, an org, an account, and its tokens.
7
+ Those are inseparable: a token is issued by one API for one org, so the endpoint
8
+ is stored *with* the token and is never a mode you switch. You choose it when you
9
+ sign in; naming the org carries it from then on.
10
+
11
+ `known login` opens your browser, you choose the org there, and the CLI files
12
+ that sign-in under the org's slug. Run it again to add another org, another
13
+ environment, or another account — each is filed alongside the others. That's the
14
+ point: one machine can keep separate identities for separate projects, the way
15
+ `aws --profile` does.
16
+
17
+ The org leads every command scoped to one, so what a command targets is visible
18
+ in the command itself:
19
+
20
+ ```bash
21
+ known acme ping
22
+ ```
23
+
24
+ There is **no global state**: no selected environment, no current org, no config
25
+ file. `~/.known` is nothing but session files.
26
+
27
+ ## Install
28
+
29
+ ```bash
30
+ npm install -g @future-unknown/known
31
+ ```
32
+
33
+ That installs the `known` command. It needs Node 18 or later.
34
+
35
+ ## Quickstart
36
+
37
+ ```bash
38
+ known login # browser opens; pick the org (and account) to sign in as
39
+ known sessions # what's signed in on this machine
40
+ known acme ping # prove that session works, end to end
41
+ known acme whoami # who you are in that org
42
+ ```
43
+
44
+ Add a second org — or a second account, or another environment — by signing in
45
+ again and choosing it:
46
+
47
+ ```bash
48
+ known login # pick globex this time
49
+ known login --endpoint staging # the same or another org, on staging
50
+ known sessions # every session, grouped by environment
51
+ ```
52
+
53
+ `known login` targets **production** by default, so there's nothing to configure
54
+ first. Pass `--endpoint staging` (or `dev`, or a URL) to sign in elsewhere.
55
+
56
+ ## Concepts
57
+
58
+ - **Endpoint** — a Known API environment. `known` ships with **`prod`**,
59
+ **`staging`**, and **`dev`**, and `known login` targets `prod` out of the box.
60
+ An endpoint is **not** something you select: it belongs to the session it
61
+ issued, so you name it at sign-in (`known login --endpoint staging`) and never
62
+ again. `known endpoints` lists them read-only.
63
+ - **Session** — one browser sign-in: an endpoint, an org, an account, and its
64
+ tokens. Stored owner-only, one file each:
65
+
66
+ ```
67
+ ~/.known/prod/acme.json 0600 — endpoint, org, account, role, tokens
68
+ ~/.known/prod/globex.json
69
+ ~/.known/staging/acme.json
70
+ ```
71
+
72
+ Signing out of one project is a single file delete and leaves the others alone.
73
+ - **The org comes first** — `known <org> <verb>`. Naming it picks the endpoint
74
+ too, since the two travel together. A bare slug works whenever it's unique; if
75
+ you're signed into the same org on two environments, qualify it as
76
+ `known acme@staging …` — and the error names the candidates when it matters:
77
+
78
+ ```
79
+ Error - 'acme' matches 2 sessions — qualify it, e.g. `known acme@staging …`
80
+ • acme@staging: ada@acme.com
81
+ • acme@prod: ada@acme.com
82
+ ```
83
+
84
+ Where a command works with or without an org, the bare form resolves it from
85
+ the project you're in (below), else the only session on the machine.
86
+ - **Projects** — a `KNOWN_ORG` file binds a directory, and everything under it, to
87
+ an org. It holds one line, the same reference `known <org>` takes:
88
+
89
+ ```bash
90
+ echo acme > KNOWN_ORG # or acme@staging to pin the environment
91
+ known wiki read general:docs.deploy # → acme, from the nearest KNOWN_ORG above you
92
+ ```
93
+
94
+ The nearest file wins, walking up from the working directory, so a file in a
95
+ repo binds that repo and one in a parent folder (`~/clients/acme/KNOWN_ORG`)
96
+ binds every repo beneath it. It holds no secrets — commit it. The
97
+ `KNOWN_ORG` environment variable outranks any file, and an org typed on the command line
98
+ outranks both.
99
+
100
+ A binding only *selects* a session you already have. If the org it names
101
+ isn't signed in here, the command stops and says so — it never falls back
102
+ to another org. `ping` and `whoami` show where the org came from (`from`),
103
+ and `known config` shows the binding in effect.
104
+ - **Reserved words** — the machine-level commands (`login`, `logout`, `whoami`,
105
+ `sessions`, `config`, `endpoints`, `ping`, `post`, `wiki`, `rpc`, `help`) always win as the
106
+ first argument, so an org whose slug is one of them isn't addressable here.
107
+ - **Expiry** — a session refreshes itself silently in the background. If its
108
+ refresh token is gone, `known` names the exact sign-in to repeat
109
+ (`known login --endpoint staging` and pick `acme`) rather than re-opening the
110
+ browser on its own: the org and account a sign-in grants are chosen in the
111
+ browser and can't be steered from the terminal, so a silent retry could hand
112
+ back a different tenant than the command asked for.
113
+
114
+ ## Commands
115
+
116
+ ```
117
+ known login [--endpoint <name|url>] sign in to an org (pick it in the browser)
118
+ known sessions every session on this machine
119
+ known whoami who you are, in every session
120
+ known logout sign out of every session
121
+ known config resolved config (tokens redacted)
122
+ known endpoints [<url>] list environments / check a URL
123
+
124
+ known <org> commands available for that org
125
+ known <org> ping prove the session works, end to end
126
+ known <org> post --text "…" post a note into the org's stream
127
+ known <org> wiki [<cmd>] the org's wikis: pages and records (see below)
128
+ known <org> code [<cmd>] source trees held in Known (see below)
129
+ known <org> sites [<cmd>] sites that sign the org's people in with Known
130
+ known <org> teams [<cmd>] the org's teams: people grouped to be granted wikis together
131
+ known <org> members [<cmd>] the org's people: owners and members, invitations, requests to join
132
+ known <org> audit the org's audit log: who changed what, and when (org owners)
133
+ known <org> feedback <kind> "…" tell Known's team what got in the way (bug, missing, confusing, idea; --about, --ref)
134
+ known <org> whoami who you are in that org
135
+ known <org> logout sign out of that org
136
+ known <org> rpc [<method>] call a JSON-RPC method as that org; alone, list every method
137
+
138
+ known ping | post | wiki | code | teams | members | audit | rpc
139
+ the same, as this project's org (KNOWN_ORG)
140
+ ```
141
+
142
+ `known whoami` with no org reports on the project's org when one is bound, else
143
+ on every session on the machine — with one
144
+ session per org and possibly a different account per org, "who am I" is genuinely
145
+ a list.
146
+
147
+ ### ping
148
+
149
+ `known <org> ping` is more than a reachability check. The API authorizes every
150
+ method against a resolved organization membership, `system.ping` included, so a
151
+ successful ping means the token verified, the account still belongs to the org,
152
+ and the policy allowed the call. It reports what it authenticated *as*, which is
153
+ the thing worth knowing before you read or write anything:
154
+
155
+ ```
156
+ session acme@prod
157
+ endpoint https://api.known.info
158
+ org Acme org_3F92Ge…
159
+ account ada@acme.com
160
+ role owner
161
+ service knapi
162
+ latency 172ms
163
+ status ok
164
+ ```
165
+
166
+ ### post
167
+
168
+ `known <org> post` adds authored content to the org's Engram stream, where it
169
+ shows up in the feed and the activity digest alongside everything arriving from
170
+ chat and GitHub. Text can come from a flag, a file, or standard input:
171
+
172
+ ```bash
173
+ known acme post --text "hello world"
174
+ git log -1 --format=%B | known acme post
175
+ known acme post --file notes.md --title "Design review"
176
+ ```
177
+
178
+ The API builds the Engram — the CLI sends text and an optional title, and the
179
+ server derives the identity, timestamp, author, and provenance from the
180
+ authenticated session. A title is derived from the first line when you don't give
181
+ one. Posts are recorded under the `pi` adapter, so they are distinguishable from
182
+ integration traffic.
183
+
184
+ ### wiki
185
+
186
+ `known <org> wiki` is the org's wikis — versioned Markdown page trees used by
187
+ people and agents alike. Every org has a wiki named `general` and may hold
188
+ more (`known acme wiki wikis` lists them). Every path names its wiki, then the
189
+ page's dot-separated path within it: `general:docs.deploy`,
190
+ `labs:docs.deploy`, or `docs.deploy --wiki labs`; `labs:` alone is the wiki's
191
+ root. A path that names no wiki is refused, never guessed. Every path the CLI
192
+ prints is written the same way, so it pastes back.
193
+
194
+ Pages are authored writing, and take the authoring verbs; records are data on
195
+ a page, and take the data verbs. The two never overlap:
196
+
197
+ ```bash
198
+ # pages
199
+ known acme wiki read general:docs.deploy
200
+ known acme wiki write general:docs.deploy --file deploy.md --title "Deploying"
201
+ known acme wiki edit general:docs.deploy --old "nightly" --new "hourly"
202
+ known acme wiki move general:docs.deploy general:runbooks.deploy
203
+ known acme wiki rm general:scratch # --recursive for a subtree (the wiki's admins)
204
+ known acme wiki tree general: --depth 2
205
+ known acme wiki search "rollback" general:
206
+ known acme wiki check general: # links that point at nothing; writes, moves and rm say so too
207
+
208
+ # records
209
+ known acme wiki records general:metrics.usage --latest
210
+ known acme wiki get general:tasks/t-41
211
+ known acme wiki set general:metrics.usage --text '{"requests": 1042}'
212
+ known acme wiki del general:tasks/t-41
213
+
214
+ # history, changes, notes
215
+ known acme wiki history general:docs.deploy # or a row's versions: general:tasks/t-41
216
+ known acme wiki diff general:docs.deploy
217
+ known acme wiki changes general: # what changed across the wiki
218
+ known acme wiki note general:docs.deploy --text "needs a diagram"
219
+ known acme wiki notes general: # the wiki's whole open-feedback queue
220
+ known acme wiki resolve general:docs.deploy <noteId>
221
+
222
+ # wikis
223
+ known acme wiki wikis
224
+ known acme wiki create labs --description "Experiments; nothing load-bearing"
225
+ known acme wiki grant labs user:@ada:admin # or user:<id>, user:<email>, team:<slug>
226
+ known acme wiki access labs # who has access, at what level, and why
227
+ known acme wiki rename labs research
228
+ known acme wiki delete research # type its name, or --confirm research
229
+ known acme wiki deleted
230
+ known acme wiki restore research
231
+
232
+ # sharing with other organizations
233
+ known acme wiki share research globex --level write
234
+ known acme wiki shares research
235
+ known acme wiki unshare research globex
236
+ known globex wiki invitations
237
+ known globex wiki accept acme/research --as acme-research
238
+ known globex wiki decline acme/research
239
+ known globex wiki leave acme-research
240
+ ```
241
+
242
+ `known acme wiki wikis` says what each wiki is for and who reads it, so a
243
+ person or an agent can choose where something belongs (`--json` for
244
+ everything). Being in an organization gives nobody a wiki: a person holds
245
+ what a wiki's grants give them, their own or a team's. Every member is on
246
+ the built-in team `everyone`, so a wiki is open to the organization when
247
+ that team is granted it and restricted when it is not; a new wiki starts
248
+ granted to everyone unless `--grant` says who starts with it. Any member
249
+ creates a wiki and is its admin; an org owner administers every wiki
250
+ already, so one who creates a wiki gets no grant they did not name. Say
251
+ what a wiki is for with `wiki update labs --description "…"` (or `wiki create
252
+ labs --description "…"`); its admins and org owners change who reads it with
253
+ `wiki grant labs team:platform:write` and `wiki revoke labs user:user_456`;
254
+ `wiki grant labs team:everyone:read` opens it to every member at that level,
255
+ and `wiki revoke labs team:everyone` restricts it to its other grants (a
256
+ wiki keeps at least one). Levels are read, write and admin.
257
+ An org owner invites someone who is not in the organization yet with
258
+ `wiki invite labs dana@example.com:read`: they are invited to the
259
+ organization and the wiki is theirs when they join (`wiki uninvite` takes
260
+ it back; `wiki access` lists who is still invited).
261
+ A person in a grant is a user id, an `@handle` or an email address
262
+ (`user:@ada:write`); the last two must match exactly one member. A path that
263
+ names no wiki is refused with the same list.
264
+
265
+ `wiki access <wiki>` says who has access, at what level, and why: a row for
266
+ everyone when the wiki is open to the org, one for each team it is granted
267
+ to, and one for each person who holds it for a reason of their own — a direct
268
+ grant, a team, owning the org. An org owner with no grant on a restricted
269
+ wiki manages its access and holds no level.
270
+
271
+ A wiki's admins and org owners rename and delete it. `wiki rename <wiki>
272
+ <new-name>` asks first (a script must pass `--yes`; nothing is assumed): the name is in every address of
273
+ every page, so the wiki's shares and the sites attached to it follow, sites
274
+ that read it must be republished, and agents must use the new name. Pages in
275
+ other wikis that still link by the old name are listed. `wiki delete <wiki>`
276
+ is confirmed by the wiki's name — typed at a terminal, or `--confirm <name>`
277
+ from a script (`--yes` is not enough) — and a refusal prints as the API said
278
+ it, such as a site that still calls the wiki home. Nothing is destroyed: the
279
+ wiki leaves every list, address, share and site, its name stays taken, and
280
+ `wiki restore <wiki>` brings it back whole. `wiki deleted` lists the deleted
281
+ wikis you could restore, with when each went and who deleted it.
282
+
283
+ A wiki other than `general` can be shared with another organization. Its
284
+ admins and org owners invite one by its slug with `wiki share <wiki> <org>`,
285
+ up to a level (`--level read` or `write`, read when unsaid; another
286
+ organization never administers a shared wiki), see where each share stands
287
+ with `wiki shares <wiki>`, and end one with `wiki unshare <wiki> <org>`. The
288
+ other organization's owners see what is waiting with `wiki invitations`, each
289
+ named `<org>/<wiki>`; `wiki accept <org>/<wiki>` takes it, under a name of
290
+ their own with `--as <name>`, and `wiki decline <org>/<wiki>` turns it down.
291
+ The wiki alone names an invitation when only one carries that name. Once
292
+ accepted it is one of their wikis (`wiki grant` decides which of their people
293
+ use it) until they `wiki leave <wiki>`.
294
+
295
+ `write` takes content exactly one way — `--text`, `--file`, or piped stdin —
296
+ plus optional `--title` and `--message` (a short note recorded on the change).
297
+ Missing parent pages, and the wiki itself on first write, are created
298
+ automatically. `read` prints raw Markdown so it pipes cleanly; `--json` adds
299
+ ids and the page's `revisionId`.
300
+
301
+ The safe edit loop for scripts and agents: change part of a page with `edit`,
302
+ giving the exact text you read — it touches nothing else, so a change made
303
+ meanwhile elsewhere on the page survives. To rewrite a page, read with
304
+ `--json`, keep `revisionId`, and write back with `--if-revision <id>`; the
305
+ write fails only if *that page* changed in between — re-read, merge, retry.
306
+ `read` and `tree` accept `--change <id>` / `--at <iso>` to read the wiki as it
307
+ was.
308
+
309
+ Pages take notes — feedback attached to the page, outside its edit
310
+ history, so leaving one never conflicts with an edit. Notes follow the
311
+ page through moves and are resolved (idempotently) when handled.
312
+ `wiki notes general:` lists the whole wiki's open queue — each entry names
313
+ its page — so feedback is a work queue, not a scavenger hunt.
314
+
315
+ Pages also carry records: a page with a key (`wiki meta general:tasks --text
316
+ '{"key": "id"}'`) is a table, where `wiki set` adds or replaces the row with
317
+ that key and every version is kept (`--if-version` is the compare-and-swap);
318
+ a page without one is a log, where `wiki set` adds an entry (`--ts <iso>`
319
+ backfills when it happened). `wiki records` reads them in order (`--latest`,
320
+ `--since`/`--until`, `--limit`, `--reverse`, `--at` for a moment); `wiki get
321
+ <wiki>:<path>/<key>` reads one. Records are not listed in `wiki changes` —
322
+ a row's history is `wiki history <wiki>:<path>/<key>` — so report
323
+ measurements and other things of one shape here, and author prose with
324
+ `wiki write`.
325
+
326
+ ### code
327
+
328
+ `known <org> code` is the org's source trees: a site's
329
+ files, with history, read and written over the API — no filesystem, git or
330
+ bundler. Every member of the org reads and writes every tree for now, and a
331
+ site names its tree as its source (`sites update <id> --source code:<tree>`).
332
+ Every path names its tree with a colon,
333
+ because file names carry dots: `hello:src/app.js`, and `hello:` is the root.
334
+
335
+ ```bash
336
+ known acme code create hello --starter html --description "A hello world page"
337
+ known acme code write hello:index.html --file index.html
338
+ known acme code edit hello:app.js --old "Hello" --new "Hello, Acme"
339
+ known acme code read hello:app.js --lines 1:40
340
+ known acme code read hello:index.html hello:app.js hello:style.css
341
+ known acme code tree hello:
342
+ known acme code grep "fetch(" hello:src --context 2
343
+ known acme code pin hello preact
344
+ known acme code check hello
345
+ known acme code changes hello:
346
+ known acme code diff hello:app.js
347
+ known acme code restore hello: --change 3
348
+ ```
349
+
350
+ Every write prints the tree's problems after it, each at its place
351
+ (`hello:app.js:2:20`): files that do not parse, imports and page references
352
+ that resolve to nothing (browsers add no extensions, so `./util` is not
353
+ `./util.js`), names imported from a tree's file that it does not export, and
354
+ packages missing from the import map, `imports.json`. A write is never refused
355
+ for them. `read` takes several addresses and prints each under a
356
+ `==> <address> <==` line. `pin` asks npm for an exact version and pins
357
+ it on esm.sh. A file that is not UTF-8 text goes up as binary. The safe loop is
358
+ the wiki's: `edit` with the exact text you read, or `write --if-revision`.
359
+
360
+ ### sites
361
+
362
+ `known <org> sites` lists the sites that sign the org's people in with Known. A
363
+ site belongs to a wiki, its home: whoever can read that wiki may sign in, and its
364
+ admins and the org's owners add, change and remove the site. It has a client id,
365
+ the exact redirect URIs a sign-in may return to, the addresses it is published
366
+ at, and the wikis attached to it, its home and any others. With no `--source`, a
367
+ new site gets a code tree of its short name. Another wiki is attached by its
368
+ admins or an org owner, for writing — the site does there what the person signed in may, pages and
369
+ records — or read-only with `--read`; attaching again with `--read` or
370
+ `--write` switches it. The home stays attached; `update --wiki` moves it.
371
+ Commands name a site by its short name — its name lowercased, accents dropped,
372
+ other characters made hyphens ("Deal Flow" is `deal-flow`), unique in the org —
373
+ or by its client id.
374
+
375
+ ```bash
376
+ known acme sites create "Capital" --wiki capital
377
+ known acme sites attach capital labs
378
+ known acme sites attach capital board --read
379
+ known acme sites update capital --wiki deals
380
+ known acme sites update capital --source code:capital
381
+ known acme sites publish capital
382
+ known acme sites publish capital --change 4
383
+ known acme sites detach capital labs
384
+ known acme sites rm capital
385
+ ```
386
+
387
+ A site calls each wiki it reads by the wiki's name, in its sign-in scope
388
+ (`wiki:capital:read`), its paths (`capital.round`) and its live stream; the
389
+ org is its token's, so renaming the org leaves the site's code as it is. A
390
+ site attached to a wiki before this keeps the address it was made with
391
+ (`acme_capital`) until the wiki is attached again.
392
+
393
+ A site whose source is a code tree publishes it with `publish`, to
394
+ `<site>-<org>.known.vision` (its short name and the org's slug), and
395
+ signs people in from there; `--change` publishes an earlier change, which is
396
+ how to roll back. Its managers publish. JSX and TypeScript are not
397
+ transformed yet, so a tree for publishing is plain JavaScript (htm for markup).
398
+
399
+ Removing a site, taking someone off its list, or detaching a wiki takes effect
400
+ on the site's next call, not when its sign-in expires. A wiki granted to someone
401
+ after they signed in reaches the app at its next token refresh.
402
+
403
+ `--source` records where the app's code lives: one of the org's code trees,
404
+ `code:<tree>`, which must exist, or a repository's address — an https URL or an
405
+ ssh address (`git@github.com:acme/capital.git`, as `git remote get-url origin`
406
+ prints it), kept as given, never with a password or token in it, and never
407
+ checked (`--no-source` clears it). It is shown only to the org's owners and
408
+ whoever registered the app, and is never part of a sign-in.
409
+
410
+ ### teams
411
+
412
+ `known <org> teams` lists the org's teams. A team is some of the org's people
413
+ under a slug, with a name and a description; a grant to a team (`wiki grant
414
+ labs team:<slug>:write`) follows its roster, so joining a team opens its wikis
415
+ and leaving closes them. On a team a person is a member or a maintainer. Any
416
+ member of the org creates a team and is its first maintainer (an org owner
417
+ keeps every team already, and is not put on one by creating it); a team's
418
+ maintainers and org owners rename it and change its roster; org owners delete
419
+ teams; anyone leaves a team they are on.
420
+
421
+ ```bash
422
+ known acme teams
423
+ known acme teams get design # people with their roles, and the wikis it reaches
424
+ known acme teams create "Design" --description "Brand, product and web"
425
+ known acme teams update design --name "Design studio"
426
+ known acme teams add design @ada
427
+ known acme teams maintainer design @ada # --off makes them a member again
428
+ known acme teams remove design ada@acme.com
429
+ known acme teams leave design
430
+ known acme teams delete design # type its slug, or --confirm design
431
+ ```
432
+
433
+ A new team's slug is its name lowercased, accents dropped, other characters
434
+ made hyphens ("Design Studio" is `design-studio`). Commands name a team by
435
+ its slug or its id (`team_…`). Deleting a team strikes it from every wiki's
436
+ grants, so it is confirmed by the team's slug: typed at a terminal, or
437
+ `--confirm <slug>` from a script.
438
+
439
+ ### audit
440
+
441
+ `known <org> audit` is the org's audit log, the newest event first. Every
442
+ change to the organization itself is recorded as it is made and never changed
443
+ or removed afterwards: its people and their roles, invitations and requests to
444
+ join, teams and their rosters, which wikis exist and who holds them (grants,
445
+ visibility, renames, deletions), what is shared with other organizations, its
446
+ sites, domains and settings. Each line says when, who did it and through what
447
+ (nothing for the web app; `via the CLI`, `via Known's assistant`, or an agent
448
+ by the name it gave), the method that did it, and what it was done to. What is
449
+ written in a wiki is that wiki's own history (`wiki changes`). Org owners read
450
+ the log.
451
+
452
+ ```
453
+ known acme audit
454
+ known acme audit --action wiki.grant # one kind of change
455
+ known acme audit --action team # a whole family: wiki, team, members, share, site, domains, org
456
+ known acme audit --person @ada # made to her, or by her
457
+ known acme audit --actor ada@acme.com # made by her
458
+ known acme audit --kind wiki --target vault # what happened to one thing
459
+ known acme audit --limit 100 --before 412 # the page after the one that ended at 412
460
+ known acme audit --json # { items, next } as the API answers
461
+ ```
462
+
463
+ An owner who grants themselves a wiki is marked `(themselves)`: that is how an
464
+ owner comes to read a restricted wiki, and it shows here.
465
+
466
+ ### members
467
+
468
+ `known <org> members` lists the org's people and their roles: an owner runs
469
+ the organization (its people, settings and billing), a member works in it.
470
+ Every member sees who is in the org; email addresses, invitations, requests
471
+ to join and every change are an owner's.
472
+
473
+ ```bash
474
+ known acme members # --query <text>, --role owner|member, --limit <n>
475
+ known acme members get @ada # the person, and what they reach and why
476
+ known acme members role @ada owner
477
+ known acme members remove @ada
478
+ known acme members leave
479
+
480
+ known acme members invite ada@acme.com grace@acme.com --role member
481
+ known acme members invitations
482
+ known acme members resend ada@acme.com # the old link stops working
483
+ known acme members revoke orginv_2abc
484
+
485
+ known acme members requests # who is waiting to join
486
+ known acme members approve grace@acme.com --role member
487
+ known acme members decline @linus
488
+ ```
489
+
490
+ A person is named by user id (`user_…`), `@handle` or email address,
491
+ everywhere a command takes one (`members`, `teams`, and `user:` grants on a
492
+ wiki). A handle or an address is looked up among the org's people and must
493
+ match exactly one of them exactly; otherwise the command stops and lists who
494
+ came close. Only owners read email addresses, so a member names people by
495
+ handle or id. An invitation is named by its id (`orginv_…`) or the address it
496
+ went to.
497
+
498
+ `members get <person>` shows the person and, for an owner or for yourself,
499
+ what they reach: their teams, every wiki they hold with its level and why
500
+ (the org, a direct grant, a team, owning the org), and the sites they may use
501
+ or manage. `members` reads the whole list a page at a time; `--limit` stops
502
+ it early.
503
+
504
+ `members invite` answers for each address on its own: those invited and
505
+ those refused (already a member, already invited) print apart, and the
506
+ command fails only when nobody was invited. `members remove` and `members
507
+ leave` ask first (a script must pass `--yes`; nothing is assumed): every grant the person holds on a wiki
508
+ and every seat on a team is deleted, and coming back later restores nothing.
509
+ An org keeps at least one owner. `members requests` lists who has asked to
510
+ join from one of the org's verified domains; `approve` lets one in at a role
511
+ (a member when unsaid) and `decline` turns one down.
512
+
513
+ ## Flags
514
+
515
+ - `--endpoint <name|url>` — which environment to sign in to. Only `known login`
516
+ and `known endpoints` read it; every other command gets its endpoint from the
517
+ session named by the org.
518
+ - `--text <string>` / `--file <path>` / `--title <string>` — content for `post`,
519
+ `wiki write`, and `wiki set`.
520
+ - `--old <text>` / `--new <text>` / `--all` — what `wiki edit` replaces, and with what.
521
+ - `--message <string>` — a note recorded on a wiki change.
522
+ - `--metadata <json>` — set page metadata as a JSON object on `wiki write`
523
+ (replaces whole; omitted metadata is preserved; `wiki meta` merges instead).
524
+ - `--if-revision <id>` / `--if-change <id>` / `--if-version <n>` — conditional
525
+ wiki writes: a page's revision, the wiki's latest change, a row's version.
526
+ - `--change <id>` / `--at <iso>` — historical wiki reads.
527
+ - `--depth <n>` / `--limit <n>` / `--before <id>` — bound `wiki tree`,
528
+ `wiki changes`, and result lists.
529
+ - `--ts <iso>` — backfill when a log entry happened, for `wiki set`.
530
+ - `--latest` / `--since <iso>` / `--until <iso>` / `--reverse` / `--at <iso>` —
531
+ select `wiki records`.
532
+ - `--description <text>` / `--title <text>` — what `wiki update` changes.
533
+ - `--confirm <name>` — confirm `wiki delete` and `teams delete` by name, for
534
+ scripts; at a terminal the name is asked for.
535
+ - `--level read|write` — how far `wiki share` lets another organization reach.
536
+ - `--as <name>` — the name `wiki accept` gives a shared wiki here.
537
+ - `--name <text>` — rename a team (`teams update`) or a site (`sites update`).
538
+ - `--role owner|member` — filter `members`, and the role for `members invite`
539
+ and `members approve`.
540
+ - `--query <text>` — narrow `members` by name or email address.
541
+ - `--off` — with `teams maintainer`, make a maintainer a member again.
542
+ - `--recursive` — let `wiki rm` take a whole subtree, and `code rm` a folder.
543
+ - `--lines <first>:<last>` — read part of a file with `code read`.
544
+ - `--regex` / `--ignore-case` / `--context <n>` — how `code grep` matches.
545
+ - `--starter <name>` — begin a tree from a starter's files (`html`).
546
+ - `--help` — after a command, show its menu and run nothing (`known acme code create --help`).
547
+ - `--json` — machine-readable output for scripting.
548
+ - `--yes`, `-y` — skip confirmation prompts (for scripts).
549
+
550
+ ## Development
551
+
552
+ ```bash
553
+ npm test # mocha — exercises the CLI against a local mock API
554
+ npm run mock # start the mock API on :4566
555
+ ```
556
+
557
+ A release is one command: `npm version patch` (or `minor`, `major`). It runs
558
+ the tests, publishes to npm, then commits, tags and pushes.
559
+
560
+ ```
561
+ bin/known entry — flag parsing + command dispatch
562
+ lib/
563
+ config.js the session store — one file per (endpoint, org), no global state
564
+ auth.js OAuth 2.0 auth-code + PKCE against /.well-known/trace
565
+ helpers.js session resolution (incl. @env qualification) + client construction
566
+ output.js terminal output primitives (and --json)
567
+ cmds/ one file per command; org.js dispatches `known <org> …`
568
+ ```