@future-unknown/known 0.0.0-stage → 0.1.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 +558 -2
- package/bin/known +156 -0
- package/lib/auth.js +206 -0
- package/lib/cmds/_audit.js +153 -0
- package/lib/cmds/_code.js +673 -0
- package/lib/cmds/_config.js +91 -0
- package/lib/cmds/_endpoints.js +58 -0
- package/lib/cmds/_feedback.js +44 -0
- package/lib/cmds/_help.js +70 -0
- package/lib/cmds/_login.js +50 -0
- package/lib/cmds/_logout.js +40 -0
- package/lib/cmds/_members.js +403 -0
- package/lib/cmds/_ping.js +49 -0
- package/lib/cmds/_post.js +103 -0
- package/lib/cmds/_rpc.js +86 -0
- package/lib/cmds/_sessions.js +68 -0
- package/lib/cmds/_sites.js +300 -0
- package/lib/cmds/_teams.js +270 -0
- package/lib/cmds/_whoami.js +76 -0
- package/lib/cmds/_wiki.js +1503 -0
- package/lib/cmds/org.js +85 -0
- package/lib/config.js +297 -0
- package/lib/helpers.js +371 -0
- package/lib/output.js +338 -0
- package/lib/project.js +100 -0
- package/package.json +50 -4
package/README.md
CHANGED
|
@@ -1,3 +1,559 @@
|
|
|
1
|
-
#
|
|
1
|
+
# known — the Known CLI
|
|
2
2
|
|
|
3
|
-
|
|
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). Any member creates a wiki and is its admin; an org owner
|
|
245
|
+
administers every wiki already, so one who creates a wiki gets no grant
|
|
246
|
+
(unless it is restricted and they name nobody, when it is theirs). Say
|
|
247
|
+
what a wiki is for with `wiki update labs --description "…"` (or `wiki create
|
|
248
|
+
labs --description "…"`); its admins and org owners change who reads it with
|
|
249
|
+
`wiki grant labs team:platform:write`, `wiki revoke labs user:user_456`, and
|
|
250
|
+
`wiki update labs --restricted` / `--open`. Levels are read, write and admin.
|
|
251
|
+
A person in a grant is a user id, an `@handle` or an email address
|
|
252
|
+
(`user:@ada:write`); the last two must match exactly one member. A path that
|
|
253
|
+
names no wiki is refused with the same list.
|
|
254
|
+
|
|
255
|
+
`wiki access <wiki>` says who has access, at what level, and why: a row for
|
|
256
|
+
everyone when the wiki is open to the org, one for each team it is granted
|
|
257
|
+
to, and one for each person who holds it for a reason of their own — a direct
|
|
258
|
+
grant, a team, owning the org. An org owner with no grant on a restricted
|
|
259
|
+
wiki manages its access and holds no level.
|
|
260
|
+
|
|
261
|
+
A wiki's admins and org owners rename and delete it. `wiki rename <wiki>
|
|
262
|
+
<new-name>` asks first (a script must pass `--yes`; nothing is assumed): the name is in every address of
|
|
263
|
+
every page, so the wiki's shares and the sites attached to it follow, sites
|
|
264
|
+
that read it must be republished, and agents must use the new name. Pages in
|
|
265
|
+
other wikis that still link by the old name are listed. `wiki delete <wiki>`
|
|
266
|
+
is confirmed by the wiki's name — typed at a terminal, or `--confirm <name>`
|
|
267
|
+
from a script (`--yes` is not enough) — and a refusal prints as the API said
|
|
268
|
+
it, such as a site that still calls the wiki home. Nothing is destroyed: the
|
|
269
|
+
wiki leaves every list, address, share and site, its name stays taken, and
|
|
270
|
+
`wiki restore <wiki>` brings it back whole. `wiki deleted` lists the deleted
|
|
271
|
+
wikis you could restore, with when each went and who deleted it.
|
|
272
|
+
|
|
273
|
+
A wiki other than `general` can be shared with another organization. Its
|
|
274
|
+
admins and org owners invite one by its slug with `wiki share <wiki> <org>`,
|
|
275
|
+
up to a level (`--level read` or `write`, read when unsaid; another
|
|
276
|
+
organization never administers a shared wiki), see where each share stands
|
|
277
|
+
with `wiki shares <wiki>`, and end one with `wiki unshare <wiki> <org>`. The
|
|
278
|
+
other organization's owners see what is waiting with `wiki invitations`, each
|
|
279
|
+
named `<org>/<wiki>`; `wiki accept <org>/<wiki>` takes it, under a name of
|
|
280
|
+
their own with `--as <name>`, and `wiki decline <org>/<wiki>` turns it down.
|
|
281
|
+
The wiki alone names an invitation when only one carries that name. Once
|
|
282
|
+
accepted it is one of their wikis (`wiki grant` decides which of their people
|
|
283
|
+
use it) until they `wiki leave <wiki>`.
|
|
284
|
+
|
|
285
|
+
`write` takes content exactly one way — `--text`, `--file`, or piped stdin —
|
|
286
|
+
plus optional `--title` and `--message` (a short note recorded on the change).
|
|
287
|
+
Missing parent pages, and the wiki itself on first write, are created
|
|
288
|
+
automatically. `read` prints raw Markdown so it pipes cleanly; `--json` adds
|
|
289
|
+
ids and the page's `revisionId`.
|
|
290
|
+
|
|
291
|
+
The safe edit loop for scripts and agents: change part of a page with `edit`,
|
|
292
|
+
giving the exact text you read — it touches nothing else, so a change made
|
|
293
|
+
meanwhile elsewhere on the page survives. To rewrite a page, read with
|
|
294
|
+
`--json`, keep `revisionId`, and write back with `--if-revision <id>`; the
|
|
295
|
+
write fails only if *that page* changed in between — re-read, merge, retry.
|
|
296
|
+
`read` and `tree` accept `--change <id>` / `--at <iso>` to read the wiki as it
|
|
297
|
+
was.
|
|
298
|
+
|
|
299
|
+
Pages take notes — feedback attached to the page, outside its edit
|
|
300
|
+
history, so leaving one never conflicts with an edit. Notes follow the
|
|
301
|
+
page through moves and are resolved (idempotently) when handled.
|
|
302
|
+
`wiki notes general:` lists the whole wiki's open queue — each entry names
|
|
303
|
+
its page — so feedback is a work queue, not a scavenger hunt.
|
|
304
|
+
|
|
305
|
+
Pages also carry records: a page with a key (`wiki meta general:tasks --text
|
|
306
|
+
'{"key": "id"}'`) is a table, where `wiki set` adds or replaces the row with
|
|
307
|
+
that key and every version is kept (`--if-version` is the compare-and-swap);
|
|
308
|
+
a page without one is a log, where `wiki set` adds an entry (`--ts <iso>`
|
|
309
|
+
backfills when it happened). `wiki records` reads them in order (`--latest`,
|
|
310
|
+
`--since`/`--until`, `--limit`, `--reverse`, `--at` for a moment); `wiki get
|
|
311
|
+
<wiki>:<path>/<key>` reads one. Records are not listed in `wiki changes` —
|
|
312
|
+
a row's history is `wiki history <wiki>:<path>/<key>` — so report
|
|
313
|
+
measurements and other things of one shape here, and author prose with
|
|
314
|
+
`wiki write`.
|
|
315
|
+
|
|
316
|
+
### code
|
|
317
|
+
|
|
318
|
+
`known <org> code` is the org's source trees: a site's
|
|
319
|
+
files, with history, read and written over the API — no filesystem, git or
|
|
320
|
+
bundler. Every member of the org reads and writes every tree for now, and a
|
|
321
|
+
site names its tree as its source (`sites update <id> --source code:<tree>`).
|
|
322
|
+
Every path names its tree with a colon,
|
|
323
|
+
because file names carry dots: `hello:src/app.js`, and `hello:` is the root.
|
|
324
|
+
|
|
325
|
+
```bash
|
|
326
|
+
known acme code create hello --starter html --description "A hello world page"
|
|
327
|
+
known acme code write hello:index.html --file index.html
|
|
328
|
+
known acme code edit hello:app.js --old "Hello" --new "Hello, Acme"
|
|
329
|
+
known acme code read hello:app.js --lines 1:40
|
|
330
|
+
known acme code read hello:index.html hello:app.js hello:style.css
|
|
331
|
+
known acme code tree hello:
|
|
332
|
+
known acme code grep "fetch(" hello:src --context 2
|
|
333
|
+
known acme code pin hello preact
|
|
334
|
+
known acme code check hello
|
|
335
|
+
known acme code changes hello:
|
|
336
|
+
known acme code diff hello:app.js
|
|
337
|
+
known acme code restore hello: --change 3
|
|
338
|
+
```
|
|
339
|
+
|
|
340
|
+
Every write prints the tree's problems after it, each at its place
|
|
341
|
+
(`hello:app.js:2:20`): files that do not parse, imports and page references
|
|
342
|
+
that resolve to nothing (browsers add no extensions, so `./util` is not
|
|
343
|
+
`./util.js`), names imported from a tree's file that it does not export, and
|
|
344
|
+
packages missing from the import map, `imports.json`. A write is never refused
|
|
345
|
+
for them. `read` takes several addresses and prints each under a
|
|
346
|
+
`==> <address> <==` line. `pin` asks npm for an exact version and pins
|
|
347
|
+
it on esm.sh. A file that is not UTF-8 text goes up as binary. The safe loop is
|
|
348
|
+
the wiki's: `edit` with the exact text you read, or `write --if-revision`.
|
|
349
|
+
|
|
350
|
+
### sites
|
|
351
|
+
|
|
352
|
+
`known <org> sites` lists the sites that sign the org's people in with Known. A
|
|
353
|
+
site belongs to a wiki, its home: whoever can read that wiki may sign in, and its
|
|
354
|
+
admins and the org's owners add, change and remove the site. It has a client id,
|
|
355
|
+
the exact redirect URIs a sign-in may return to, the addresses it is published
|
|
356
|
+
at, and the wikis attached to it, its home and any others. With no `--source`, a
|
|
357
|
+
new site gets a code tree of its short name. Another wiki is attached by its
|
|
358
|
+
admins or an org owner, for writing — the site does there what the person signed in may, pages and
|
|
359
|
+
records — or read-only with `--read`; attaching again with `--read` or
|
|
360
|
+
`--write` switches it. The home stays attached; `update --wiki` moves it.
|
|
361
|
+
Commands name a site by its short name — its name lowercased, accents dropped,
|
|
362
|
+
other characters made hyphens ("Deal Flow" is `deal-flow`), unique in the org —
|
|
363
|
+
or by its client id.
|
|
364
|
+
|
|
365
|
+
```bash
|
|
366
|
+
known acme sites create "Capital" --wiki capital
|
|
367
|
+
known acme sites attach capital labs
|
|
368
|
+
known acme sites attach capital board --read
|
|
369
|
+
known acme sites update capital --wiki deals
|
|
370
|
+
known acme sites update capital --source code:capital
|
|
371
|
+
known acme sites publish capital
|
|
372
|
+
known acme sites publish capital --change 4
|
|
373
|
+
known acme sites detach capital labs
|
|
374
|
+
known acme sites rm capital
|
|
375
|
+
```
|
|
376
|
+
|
|
377
|
+
A site calls each wiki it reads by the wiki's name, in its sign-in scope
|
|
378
|
+
(`wiki:capital:read`), its paths (`capital.round`) and its live stream; the
|
|
379
|
+
org is its token's, so renaming the org leaves the site's code as it is. A
|
|
380
|
+
site attached to a wiki before this keeps the address it was made with
|
|
381
|
+
(`acme_capital`) until the wiki is attached again.
|
|
382
|
+
|
|
383
|
+
A site whose source is a code tree publishes it with `publish`, to
|
|
384
|
+
`<site>-<org>.known.vision` (its short name and the org's slug), and
|
|
385
|
+
signs people in from there; `--change` publishes an earlier change, which is
|
|
386
|
+
how to roll back. Its managers publish. JSX and TypeScript are not
|
|
387
|
+
transformed yet, so a tree for publishing is plain JavaScript (htm for markup).
|
|
388
|
+
|
|
389
|
+
Removing a site, taking someone off its list, or detaching a wiki takes effect
|
|
390
|
+
on the site's next call, not when its sign-in expires. A wiki granted to someone
|
|
391
|
+
after they signed in reaches the app at its next token refresh.
|
|
392
|
+
|
|
393
|
+
`--source` records where the app's code lives: one of the org's code trees,
|
|
394
|
+
`code:<tree>`, which must exist, or a repository's address — an https URL or an
|
|
395
|
+
ssh address (`git@github.com:acme/capital.git`, as `git remote get-url origin`
|
|
396
|
+
prints it), kept as given, never with a password or token in it, and never
|
|
397
|
+
checked (`--no-source` clears it). It is shown only to the org's owners and
|
|
398
|
+
whoever registered the app, and is never part of a sign-in.
|
|
399
|
+
|
|
400
|
+
### teams
|
|
401
|
+
|
|
402
|
+
`known <org> teams` lists the org's teams. A team is some of the org's people
|
|
403
|
+
under a slug, with a name and a description; a grant to a team (`wiki grant
|
|
404
|
+
labs team:<slug>:write`) follows its roster, so joining a team opens its wikis
|
|
405
|
+
and leaving closes them. On a team a person is a member or a maintainer. Any
|
|
406
|
+
member of the org creates a team and is its first maintainer (an org owner
|
|
407
|
+
keeps every team already, and is not put on one by creating it); a team's
|
|
408
|
+
maintainers and org owners rename it and change its roster; org owners delete
|
|
409
|
+
teams; anyone leaves a team they are on.
|
|
410
|
+
|
|
411
|
+
```bash
|
|
412
|
+
known acme teams
|
|
413
|
+
known acme teams get design # people with their roles, and the wikis it reaches
|
|
414
|
+
known acme teams create "Design" --description "Brand, product and web"
|
|
415
|
+
known acme teams update design --name "Design studio"
|
|
416
|
+
known acme teams add design @ada
|
|
417
|
+
known acme teams maintainer design @ada # --off makes them a member again
|
|
418
|
+
known acme teams remove design ada@acme.com
|
|
419
|
+
known acme teams leave design
|
|
420
|
+
known acme teams delete design # type its slug, or --confirm design
|
|
421
|
+
```
|
|
422
|
+
|
|
423
|
+
A new team's slug is its name lowercased, accents dropped, other characters
|
|
424
|
+
made hyphens ("Design Studio" is `design-studio`). Commands name a team by
|
|
425
|
+
its slug or its id (`team_…`). Deleting a team strikes it from every wiki's
|
|
426
|
+
grants, so it is confirmed by the team's slug: typed at a terminal, or
|
|
427
|
+
`--confirm <slug>` from a script.
|
|
428
|
+
|
|
429
|
+
### audit
|
|
430
|
+
|
|
431
|
+
`known <org> audit` is the org's audit log, the newest event first. Every
|
|
432
|
+
change to the organization itself is recorded as it is made and never changed
|
|
433
|
+
or removed afterwards: its people and their roles, invitations and requests to
|
|
434
|
+
join, teams and their rosters, which wikis exist and who holds them (grants,
|
|
435
|
+
visibility, renames, deletions), what is shared with other organizations, its
|
|
436
|
+
sites, domains and settings. Each line says when, who did it and through what
|
|
437
|
+
(nothing for the web app; `via the CLI`, `via Known's assistant`, or an agent
|
|
438
|
+
by the name it gave), the method that did it, and what it was done to. What is
|
|
439
|
+
written in a wiki is that wiki's own history (`wiki changes`). Org owners read
|
|
440
|
+
the log.
|
|
441
|
+
|
|
442
|
+
```
|
|
443
|
+
known acme audit
|
|
444
|
+
known acme audit --action wiki.grant # one kind of change
|
|
445
|
+
known acme audit --action team # a whole family: wiki, team, members, share, site, domains, org
|
|
446
|
+
known acme audit --person @ada # made to her, or by her
|
|
447
|
+
known acme audit --actor ada@acme.com # made by her
|
|
448
|
+
known acme audit --kind wiki --target vault # what happened to one thing
|
|
449
|
+
known acme audit --limit 100 --before 412 # the page after the one that ended at 412
|
|
450
|
+
known acme audit --json # { items, next } as the API answers
|
|
451
|
+
```
|
|
452
|
+
|
|
453
|
+
An owner who grants themselves a wiki is marked `(themselves)`: that is how an
|
|
454
|
+
owner comes to read a restricted wiki, and it shows here.
|
|
455
|
+
|
|
456
|
+
### members
|
|
457
|
+
|
|
458
|
+
`known <org> members` lists the org's people and their roles: an owner runs
|
|
459
|
+
the organization (its people, settings and billing), a member works in it.
|
|
460
|
+
Every member sees who is in the org; email addresses, invitations, requests
|
|
461
|
+
to join and every change are an owner's.
|
|
462
|
+
|
|
463
|
+
```bash
|
|
464
|
+
known acme members # --query <text>, --role owner|member, --limit <n>
|
|
465
|
+
known acme members get @ada # the person, and what they reach and why
|
|
466
|
+
known acme members role @ada owner
|
|
467
|
+
known acme members remove @ada
|
|
468
|
+
known acme members leave
|
|
469
|
+
|
|
470
|
+
known acme members invite ada@acme.com grace@acme.com --role member
|
|
471
|
+
known acme members invitations
|
|
472
|
+
known acme members resend ada@acme.com # the old link stops working
|
|
473
|
+
known acme members revoke orginv_2abc
|
|
474
|
+
|
|
475
|
+
known acme members requests # who is waiting to join
|
|
476
|
+
known acme members approve grace@acme.com --role member
|
|
477
|
+
known acme members decline @linus
|
|
478
|
+
```
|
|
479
|
+
|
|
480
|
+
A person is named by user id (`user_…`), `@handle` or email address,
|
|
481
|
+
everywhere a command takes one (`members`, `teams`, and `user:` grants on a
|
|
482
|
+
wiki). A handle or an address is looked up among the org's people and must
|
|
483
|
+
match exactly one of them exactly; otherwise the command stops and lists who
|
|
484
|
+
came close. Only owners read email addresses, so a member names people by
|
|
485
|
+
handle or id. An invitation is named by its id (`orginv_…`) or the address it
|
|
486
|
+
went to.
|
|
487
|
+
|
|
488
|
+
`members get <person>` shows the person and, for an owner or for yourself,
|
|
489
|
+
what they reach: their teams, every wiki they hold with its level and why
|
|
490
|
+
(the org, a direct grant, a team, owning the org), and the sites they may use
|
|
491
|
+
or manage. `members` reads the whole list a page at a time; `--limit` stops
|
|
492
|
+
it early.
|
|
493
|
+
|
|
494
|
+
`members invite` answers for each address on its own: those invited and
|
|
495
|
+
those refused (already a member, already invited) print apart, and the
|
|
496
|
+
command fails only when nobody was invited. `members remove` and `members
|
|
497
|
+
leave` ask first (a script must pass `--yes`; nothing is assumed): every grant the person holds on a wiki
|
|
498
|
+
and every seat on a team is deleted, and coming back later restores nothing.
|
|
499
|
+
An org keeps at least one owner. `members requests` lists who has asked to
|
|
500
|
+
join from one of the org's verified domains; `approve` lets one in at a role
|
|
501
|
+
(a member when unsaid) and `decline` turns one down.
|
|
502
|
+
|
|
503
|
+
## Flags
|
|
504
|
+
|
|
505
|
+
- `--endpoint <name|url>` — which environment to sign in to. Only `known login`
|
|
506
|
+
and `known endpoints` read it; every other command gets its endpoint from the
|
|
507
|
+
session named by the org.
|
|
508
|
+
- `--text <string>` / `--file <path>` / `--title <string>` — content for `post`,
|
|
509
|
+
`wiki write`, and `wiki set`.
|
|
510
|
+
- `--old <text>` / `--new <text>` / `--all` — what `wiki edit` replaces, and with what.
|
|
511
|
+
- `--message <string>` — a note recorded on a wiki change.
|
|
512
|
+
- `--metadata <json>` — set page metadata as a JSON object on `wiki write`
|
|
513
|
+
(replaces whole; omitted metadata is preserved; `wiki meta` merges instead).
|
|
514
|
+
- `--if-revision <id>` / `--if-change <id>` / `--if-version <n>` — conditional
|
|
515
|
+
wiki writes: a page's revision, the wiki's latest change, a row's version.
|
|
516
|
+
- `--change <id>` / `--at <iso>` — historical wiki reads.
|
|
517
|
+
- `--depth <n>` / `--limit <n>` / `--before <id>` — bound `wiki tree`,
|
|
518
|
+
`wiki changes`, and result lists.
|
|
519
|
+
- `--ts <iso>` — backfill when a log entry happened, for `wiki set`.
|
|
520
|
+
- `--latest` / `--since <iso>` / `--until <iso>` / `--reverse` / `--at <iso>` —
|
|
521
|
+
select `wiki records`.
|
|
522
|
+
- `--description <text>` / `--title <text>` / `--restricted` / `--open` — what
|
|
523
|
+
`wiki update` changes.
|
|
524
|
+
- `--confirm <name>` — confirm `wiki delete` and `teams delete` by name, for
|
|
525
|
+
scripts; at a terminal the name is asked for.
|
|
526
|
+
- `--level read|write` — how far `wiki share` lets another organization reach.
|
|
527
|
+
- `--as <name>` — the name `wiki accept` gives a shared wiki here.
|
|
528
|
+
- `--name <text>` — rename a team (`teams update`) or a site (`sites update`).
|
|
529
|
+
- `--role owner|member` — filter `members`, and the role for `members invite`
|
|
530
|
+
and `members approve`.
|
|
531
|
+
- `--query <text>` — narrow `members` by name or email address.
|
|
532
|
+
- `--off` — with `teams maintainer`, make a maintainer a member again.
|
|
533
|
+
- `--recursive` — let `wiki rm` take a whole subtree, and `code rm` a folder.
|
|
534
|
+
- `--lines <first>:<last>` — read part of a file with `code read`.
|
|
535
|
+
- `--regex` / `--ignore-case` / `--context <n>` — how `code grep` matches.
|
|
536
|
+
- `--starter <name>` — begin a tree from a starter's files (`html`).
|
|
537
|
+
- `--help` — after a command, show its menu and run nothing (`known acme code create --help`).
|
|
538
|
+
- `--json` — machine-readable output for scripting.
|
|
539
|
+
- `--yes`, `-y` — skip confirmation prompts (for scripts).
|
|
540
|
+
|
|
541
|
+
## Development
|
|
542
|
+
|
|
543
|
+
```bash
|
|
544
|
+
npm test # mocha — exercises the CLI against a local mock API
|
|
545
|
+
npm run mock # start the mock API on :4566
|
|
546
|
+
```
|
|
547
|
+
|
|
548
|
+
A release is one command: `npm version patch` (or `minor`, `major`). It runs
|
|
549
|
+
the tests, publishes to npm, then commits, tags and pushes.
|
|
550
|
+
|
|
551
|
+
```
|
|
552
|
+
bin/known entry — flag parsing + command dispatch
|
|
553
|
+
lib/
|
|
554
|
+
config.js the session store — one file per (endpoint, org), no global state
|
|
555
|
+
auth.js OAuth 2.0 auth-code + PKCE against /.well-known/trace
|
|
556
|
+
helpers.js session resolution (incl. @env qualification) + client construction
|
|
557
|
+
output.js terminal output primitives (and --json)
|
|
558
|
+
cmds/ one file per command; org.js dispatches `known <org> …`
|
|
559
|
+
```
|