@ninefish/cli 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.
Files changed (3) hide show
  1. package/README.md +213 -2
  2. package/dist/nf.js +3097 -0
  3. package/package.json +37 -3
package/README.md CHANGED
@@ -1,3 +1,214 @@
1
- # Temporary Holding Version
1
+ # nf
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
+ The nine fish command-line interface: `@ninefish/cli`, the `nf` executable. The
4
+ contract is [docs/api-cli/02](../../docs/api-cli/02-cli-contract.md).
5
+
6
+ **Status.** Every command works against the management API on dev, and `doctor`,
7
+ `version` and `help` run locally. There is no declarative file: nf is one command
8
+ per change (A-061). Commands are listed in the order of the journey (A-076): sign in,
9
+ the organisation, a card, a domain, forwards, platforms, people, then the rest;
10
+ `nf --help` follows the same order.
11
+
12
+ ```sh
13
+ pnpm --filter @ninefish/cli build
14
+ node apps/cli/dist/nf.js --help
15
+ ```
16
+
17
+ ## Commands
18
+
19
+ An organisation can be named by its name or its id (`org_…`); names never
20
+ hold `_`, so the two don't clash. People and
21
+ memberships are named by id. Commands that act inside an organisation use
22
+ `--org`, then `NF_ORG`, then the profile's `org`, and exit 7 with
23
+ `no_org_selected` when there is none. Lists follow every page unless `--limit`
24
+ caps them.
25
+
26
+ | Command | Notes |
27
+ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
28
+ | `nf login [--device]` | |
29
+ | `nf logout` | |
30
+ | `nf whoami` | |
31
+ | `nf org create <name>` | |
32
+ | `nf org use <org>` | Writes the profile's `org` |
33
+ | `nf org list [--limit <n>]` | |
34
+ | `nf org show [org]` | |
35
+ | `nf org branding show [--domain <domain>]` | Shown only once the organisation has an active verified domain (A-049) |
36
+ | `nf org branding set --name <display-name> --primary <#rrggbb> --background <#rrggbb> [--logo <file.png>] [--dark-primary <#rrggbb> --dark-background <#rrggbb>] [--dark-logo <file.png>] [--light-only] [--support-url <url>] [--domain <domain>]` | The sign-in pages on the domain's host show it (A-038); dark colours and logo for viewers in dark mode (A-085) |
37
+ | `nf org branding remove-logo [--dark] [--domain <domain>]` | With --dark, only the logo for dark mode |
38
+ | `nf org branding remove --domain <domain>` | The domain's host shows the organisation's brand again (A-074) |
39
+ | `nf org sign-in show` | |
40
+ | `nf org sign-in set --email-links enabled\|disabled` | Owner, step-up (A-048, A-051); the sign-in pages apply it |
41
+ | `nf org transfer <membership>` | Owner with a step-up; they become owner, you a member (A-064) |
42
+ | `nf org leave` | The last owner transfers or closes it first |
43
+ | `nf org close --confirm <name>` | Owner with a step-up; once nothing billable is left; settles the account |
44
+ | `nf billing setup` | Owner with a step-up; prints a Stripe page to add a card (A-063) |
45
+ | `nf billing show` | Whether a card is on file (A-012) |
46
+ | `nf billing invoices` | Totals in A$ from whole cents; unbilled usage is in `nf usage show` |
47
+ | `nf domain setup <fqdn> [--email yes\|no] [--routes <local=address,…>] [--host <name\|none>] [--name <name>] [--zone]` | Asks what the domain is for, then prints every record at once (A-073) |
48
+ | `nf domain check <domain> [--zone]` | Verifies, turns forwarding on, adds routes and the host, as DNS allows |
49
+ | `nf domain add <fqdn>` | Prints the TXT record to publish |
50
+ | `nf domain instructions <fqdn>` | |
51
+ | `nf domain verify <fqdn>` | Exit 2 with `domain_txt_missing` until DNS has the record |
52
+ | `nf domain list [--limit <n>]` | |
53
+ | `nf domain show <fqdn>` | |
54
+ | `nf domain remove <fqdn>` | |
55
+ | `nf email route create <address> --to <targets>` | Mailboxes or people, comma-separated; a new mailbox is added (step-up) and the route forwards once it agrees (A-078) |
56
+ | `nf email route list [--limit <n>]` | |
57
+ | `nf email route show <route>` | |
58
+ | `nf email route update <route> --to <targets>` | |
59
+ | `nf email route delete <route>` | |
60
+ | `nf email destination add <email> [--person <person>]` | Needs a recent step-up; pending until its owner agrees |
61
+ | `nf email destination list [--limit <n>]` | |
62
+ | `nf email destination show <destination>` | |
63
+ | `nf email destination resend <destination>` | |
64
+ | `nf email destination remove <destination>` | |
65
+ | `nf email enable <fqdn>` | Prints the MX and DKIM records to publish |
66
+ | `nf email list [--limit <n>]` | |
67
+ | `nf email show <fqdn>` | |
68
+ | `nf email check <fqdn>` | Looks up MX, DKIM and DMARC now |
69
+ | `nf email disable <fqdn>` | Routes are kept |
70
+ | `nf platform add [name] [--domain <fqdn>] [--callback <uri>]... [--public] [--secret-file <path>]` | Asks for what's missing at a terminal, never under `--json`; prints the issuer, client ID, secret and callback to paste in; a callback needs a recent step-up (A-080) |
71
+ | `nf platform add [name] --saml [--domain <fqdn>] [--entity-id <uri>] [--acs <url>]... [--sp-cert <path>] [--attributes <list>]` | Asks for name, domain, entity ID and ACS at a terminal, never under `--json`; prints the IdP entity ID, metadata URL, SSO URL and certificate to paste in, no secret; an ACS needs a recent step-up (A-079) |
72
+ | `nf platform list [--limit <n>]` | |
73
+ | `nf platform show <platform>` | With its issuer, client ID, endpoints and callbacks, or a SAML platform's metadata URL, SSO URL and certificate |
74
+ | `nf platform callback add <platform> <uri>` | Needs a recent passkey step-up |
75
+ | `nf platform callback remove <platform> <uri>` | Needs a recent passkey step-up |
76
+ | `nf platform remove <platform>` | Sign-in and billing stop; to move it to another domain, remove it and add it again |
77
+ | `nf platform rotate-secret <platform> [--secret-file <path>]` | Needs a recent passkey step-up; the secret goes to the file, or is shown once at a terminal |
78
+ | `nf person invite <email> [--name <name>]` | Records the invite; they join as a member (A-078) once they follow the emailed link and sign in |
79
+ | `nf person list [--limit <n>]` | |
80
+ | `nf person suspend <membership>` | |
81
+ | `nf person restore <membership>` | |
82
+ | `nf person remove <membership>` | |
83
+ | `nf person name add <membership> <name>` | |
84
+ | `nf person name remove <membership> <name>` | |
85
+ | `nf invite list [--limit <n>]` | |
86
+ | `nf invite revoke <invite>` | |
87
+ | `nf auth-host add <hostname>` | The record and its rules (A-044); pending until its CNAME and certificate are in place, then the edge serves it (A-059) |
88
+ | `nf auth-host list` | One host per verified domain (A-072) |
89
+ | `nf auth-host show <hostname>` | |
90
+ | `nf auth-host check <hostname>` | Activates the host once its certificate is issued; its CNAME must point at nine fish first |
91
+ | `nf auth-host remove <hostname>` | |
92
+ | `nf usage show [--from <date>] [--to <date>]` | Exact amounts, this month to now by default |
93
+ | `nf audit list [--limit <n>]` | |
94
+ | `nf doctor` | Local checks only |
95
+ | `nf version` | |
96
+ | `nf help [command]` | |
97
+
98
+ Bare `nf` and `nf --help` draw the mark (`src/mark.ts`, generated from
99
+ `apps/marketing/public/logo.svg` by `pnpm --filter @ninefish/cli render-mark`) in the
100
+ brand blue, only on a terminal and never with `NO_COLOR` or `TERM=dumb`. With
101
+ `--json` or `--output yaml`, help is the command tree as data and there is no banner.
102
+
103
+ ## Signing in
104
+
105
+ `nf login` signs in with a passkey in the browser (A-009): nf listens once on
106
+ `127.0.0.1`, opens `/authorize` at the stage's auth origin as the public client
107
+ `nf-cli` with PKCE S256, and takes the code back over loopback (RFC 8252). With
108
+ `--device`, or with no terminal, it shows a code to approve at `/device` on any
109
+ signed-in device (RFC 8628). The tokens go to the OS keychain (the macOS
110
+ Keychain, or the Secret Service through `secret-tool` on Linux), never to a file
111
+ or the terminal; with neither, `nf login` exits 7. Each profile has its own
112
+ tokens, and a token is only ever sent to the API host it was issued for. An
113
+ expired access token is refreshed, and the refresh token rotates. `nf logout`
114
+ revokes the refresh token and forgets both.
115
+
116
+ A change on the step-up list (security/01) needs a passkey in the last five
117
+ minutes. At a terminal nf asks for it in place (A-078): it opens the browser for
118
+ a fresh passkey, keeps the new tokens and carries on with the command. Without a
119
+ terminal, or under `--json` or `--output`, it exits 6 with `step_up_required`:
120
+ run `nf login`, then the command again.
121
+
122
+ On dev, with no tokens, nf still takes the bootstrap credential (A-020) from
123
+ `NF_BOOTSTRAP_CREDENTIAL`, never stored or printed. It never sends it to prod:
124
+ on a prod profile it exits 3 with `bootstrap_credential_refused` before making
125
+ any request.
126
+
127
+ Every request carries `X-Request-Id` (the `--request-id`, or a fresh `req_…`),
128
+ and every POST, PATCH and DELETE a fresh `Idempotency-Key`. A suspend or restore
129
+ reads the membership first and sends its version as `If-Match`, so a change made
130
+ in between is refused rather than overwritten.
131
+
132
+ ## Scripts and CI
133
+
134
+ A script or CI job runs as a person (A-080): sign in once with `nf login --device`
135
+ where it runs, approve the code from any browser, and it acts with that person's
136
+ role. Its tokens are kept in the OS keychain like any other sign-in, so nf needs
137
+ the macOS Keychain or the Secret Service there; without one, `nf login` refuses
138
+ rather than writing tokens to a file. Anything on the step-up list needs that
139
+ person's recent passkey step-up, as it would at a laptop.
140
+
141
+ ## Global options
142
+
143
+ `--org <id or name>`, `--profile <name>`, `--no-interactive`, `--timeout <duration>`
144
+ (`30`, `30s`, `2m`, `1500ms`; default 30s), `--request-id <id>`, `--json`,
145
+ `--output json|yaml|table` (`-o`), `--help` (`-h`), `--version`. There is no
146
+ `--environment`: a profile names a stage (A-021).
147
+
148
+ ## Profiles and stages
149
+
150
+ Resolution is flags, then environment variables, then the config file.
151
+
152
+ - The config file is `NF_CONFIG`, else `$XDG_CONFIG_HOME/nf/config.yaml`, else
153
+ `~/.config/nf/config.yaml`. Unknown keys are refused, and so is any key that
154
+ looks like a credential: tokens are kept in the OS keychain (A-009).
155
+ - A profile has a `stage` (`dev` or `prod`) and optionally an `org`. The API and
156
+ auth hosts come from `@nf/naming`, never from the file. The profiles `dev`
157
+ and `prod` are built in.
158
+ - `NF_PROFILE` and `NF_ORG` stand in for the flags. `NF_API` may name a stage's
159
+ own API, or a loopback `http://` origin for a local server (dev).
160
+ - With nothing selected on a laptop, the stage is dev.
161
+ - **In CI (`CI` or `GITHUB_ACTIONS` set) nf never picks a stage.** The file's
162
+ selected profile and the dev default are ignored, and a command exits 7 unless
163
+ `--profile`, `NF_PROFILE` or `NF_API` names one.
164
+
165
+ ```yaml
166
+ profile: work
167
+ profiles:
168
+ work:
169
+ stage: prod
170
+ org: org_example
171
+ ```
172
+
173
+ ## Output and errors
174
+
175
+ Read output is a table by default, or `--json` / `--output yaml`. An error in
176
+ JSON or YAML is the API's envelope on stdout, as
177
+ `{"code", "message", "request_id", "details", "retryable"}` (`ErrorEnvelope` in `@nf/contracts`); in a table,
178
+ it is a sentence and a remediation on stderr, with the server's request id when the
179
+ API answered. An error the API returns is printed as the API sent it. Neither
180
+ ever holds a secret. A platform's client secret goes only to `--secret-file`, readable
181
+ only by you, or is shown once to a person at a terminal; it is never in `--json` output,
182
+ and without a terminal or a file `nf platform add` and `rotate-secret` refuse.
183
+
184
+ An API error's exit code comes from its HTTP status, except `step_up_required`,
185
+ which is 6:
186
+
187
+ | Status | Exit |
188
+ | ------------- | ---- |
189
+ | 400, 422 | 2 |
190
+ | 401 | 3 |
191
+ | 403 | 8 |
192
+ | 404, 410 | 4 |
193
+ | 409, 412, 428 | 5 |
194
+ | 429, 5xx | 9 |
195
+ | anything else | 1 |
196
+
197
+ No answer within `--timeout`, or no connection, is 9 (`timeout`, `network_error`).
198
+
199
+ ## Exit codes
200
+
201
+ A code never changes meaning (`src/exit-codes.ts`).
202
+
203
+ | Code | Name | Meaning |
204
+ | ---- | ----------------- | ------------------------------------------------------------------------------------------------------------------- |
205
+ | 0 | `ok` | It worked. |
206
+ | 1 | `error` | Something failed that no other code covers, or a `doctor` check failed. |
207
+ | 2 | `usage` | The command line is wrong: an unknown command or option, a missing argument, or a value the API refused as invalid. |
208
+ | 3 | `unauthenticated` | Not signed in, or the session has expired. Run `nf login`. |
209
+ | 4 | `notFound` | The organisation, person, domain or platform doesn't exist, or isn't visible to you. |
210
+ | 5 | `conflict` | The resource changed since it was read, or the change conflicts with another. |
211
+ | 6 | `stepUpRequired` | The change needs a passkey presented in the last five minutes (a step-up). |
212
+ | 7 | `config` | The config file, profile or stage selection is invalid or missing. |
213
+ | 8 | `forbidden` | Signed in, but not allowed to do this. |
214
+ | 9 | `retryable` | A timeout, rate limit or server error. Retrying may work. |