@ninefish/cli 0.0.0-stage → 0.1.1

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 +193 -2
  2. package/dist/nf.js +3103 -0
  3. package/package.json +37 -3
package/README.md CHANGED
@@ -1,3 +1,194 @@
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 command line for [nine fish](https://nine.fish): sign-in for your apps, on your own domain,
4
+ with your brand. Set up an organisation, verify a domain, forward its mail and register the apps
5
+ your people sign in to.
6
+
7
+ ```sh
8
+ npm install -g @ninefish/cli
9
+ nf login
10
+ ```
11
+
12
+ Needs Node.js 24 or later, and somewhere safe to keep tokens: the macOS Keychain, or on Linux
13
+ the Secret Service (`secret-tool`, from libsecret). nf never writes tokens to a file.
14
+
15
+ ## Getting started
16
+
17
+ ```sh
18
+ nf login # sign in with a passkey in your browser
19
+ nf org create acme # make an organisation; you are its owner
20
+ nf billing setup # add a card (opens a Stripe page)
21
+ nf domain setup example.com # what the domain is for, and every DNS record at once
22
+ nf domain check example.com # verify it, as DNS allows
23
+ nf platform add # register an app; prints what to paste into it
24
+ ```
25
+
26
+ `nf help <command>` explains any command, and `nf --help` lists them in this order.
27
+
28
+ ## Commands
29
+
30
+ An organisation can be named by its name or its id (`org_…`). People and memberships are named
31
+ by id. Commands that act inside an organisation use `--org`, then `NF_ORG`, then the profile's
32
+ `org`, and exit 7 with `no_org_selected` when there is none. Lists follow every page unless
33
+ `--limit` caps them.
34
+
35
+ Some changes need a **step-up**: a passkey presented in the last five minutes. At a terminal nf
36
+ asks for one in your browser and carries on.
37
+
38
+ | Command | Notes |
39
+ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
40
+ | `nf login [--device]` | `--device` shows a code to approve from any signed-in browser |
41
+ | `nf logout` | |
42
+ | `nf whoami` | |
43
+ | `nf org create <name>` | |
44
+ | `nf org use <org>` | Makes it the profile's organisation |
45
+ | `nf org list [--limit <n>]` | |
46
+ | `nf org show [org]` | |
47
+ | `nf org branding show [--domain <domain>]` | Once the organisation has a verified domain |
48
+ | `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>]` | Your sign-in pages show it; the dark colours and logo are for viewers in dark mode |
49
+ | `nf org branding remove-logo [--dark] [--domain <domain>]` | With `--dark`, only the dark-mode logo |
50
+ | `nf org branding remove --domain <domain>` | The domain shows the organisation's brand again |
51
+ | `nf org sign-in show` | |
52
+ | `nf org sign-in set --email-links enabled\|disabled` | Owner, step-up |
53
+ | `nf org transfer <membership>` | Owner, step-up; they become owner and you a member |
54
+ | `nf org leave` | The last owner transfers or closes it first |
55
+ | `nf org close --confirm <name>` | Owner, step-up; once nothing billable is left; settles the account |
56
+ | `nf billing setup` | Owner, step-up; prints a Stripe page to add a card |
57
+ | `nf billing show` | Whether a card is on file |
58
+ | `nf billing invoices` | Totals in A$; usage not yet invoiced is in `nf usage show` |
59
+ | `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 |
60
+ | `nf domain check <domain> [--zone]` | Verifies, turns forwarding on, adds routes and the sign-in host, as DNS allows |
61
+ | `nf domain add <fqdn>` | Prints the TXT record to publish |
62
+ | `nf domain instructions <fqdn>` | |
63
+ | `nf domain verify <fqdn>` | Exit 2 with `domain_txt_missing` until DNS has the record |
64
+ | `nf domain list [--limit <n>]` | |
65
+ | `nf domain show <fqdn>` | |
66
+ | `nf domain remove <fqdn>` | |
67
+ | `nf email route create <address> --to <targets>` | Mailboxes or people, comma-separated; a new mailbox (step-up) gets mail once its owner agrees |
68
+ | `nf email route list [--limit <n>]` | |
69
+ | `nf email route show <route>` | |
70
+ | `nf email route update <route> --to <targets>` | |
71
+ | `nf email route delete <route>` | |
72
+ | `nf email destination add <email> [--person <person>]` | Step-up; pending until its owner agrees |
73
+ | `nf email destination list [--limit <n>]` | |
74
+ | `nf email destination show <destination>` | |
75
+ | `nf email destination resend <destination>` | |
76
+ | `nf email destination remove <destination>` | |
77
+ | `nf email enable <fqdn>` | Prints the MX and DKIM records to publish |
78
+ | `nf email list [--limit <n>]` | |
79
+ | `nf email show <fqdn>` | |
80
+ | `nf email check <fqdn>` | Looks up MX, DKIM and DMARC now |
81
+ | `nf email disable <fqdn>` | Routes are kept |
82
+ | `nf platform add [name] [--domain <fqdn>] [--callback <uri>]... [--public] [--secret-file <path>]` | An OpenID Connect app; prints the issuer, client ID, secret and callback to paste in; a callback needs a step-up |
83
+ | `nf platform add [name] --saml [--domain <fqdn>] [--entity-id <uri>] [--acs <url>]... [--sp-cert <path>] [--attributes <list>]` | A SAML app; prints the entity ID, metadata URL, SSO URL and certificate to paste in; an ACS URL needs a step-up |
84
+ | `nf platform list [--limit <n>]` | |
85
+ | `nf platform show <platform>` | Its issuer, client ID, endpoints and callbacks, or a SAML app's metadata URL, SSO URL and certificate |
86
+ | `nf platform callback add <platform> <uri>` | Step-up |
87
+ | `nf platform callback remove <platform> <uri>` | Step-up |
88
+ | `nf platform remove <platform>` | Sign-in and billing stop; to move it to another domain, remove it and add it again |
89
+ | `nf platform rotate-secret <platform> [--secret-file <path>]` | Step-up; the secret goes to the file, or is shown once at a terminal |
90
+ | `nf person invite <email> [--name <name>]` | They join as a member once they follow the emailed link and sign in |
91
+ | `nf person list [--limit <n>]` | |
92
+ | `nf person suspend <membership>` | |
93
+ | `nf person restore <membership>` | |
94
+ | `nf person remove <membership>` | |
95
+ | `nf person name add <membership> <name>` | A forwarding name, such as `alex` for `alex@` |
96
+ | `nf person name remove <membership> <name>` | |
97
+ | `nf invite list [--limit <n>]` | |
98
+ | `nf invite revoke <invite>` | |
99
+ | `nf auth-host add <hostname>` | Your sign-in host, such as `auth.example.com`; pending until its CNAME is in place and its certificate is issued |
100
+ | `nf auth-host list` | One host per verified domain |
101
+ | `nf auth-host show <hostname>` | |
102
+ | `nf auth-host check <hostname>` | Activates the host once its certificate is issued |
103
+ | `nf auth-host remove <hostname>` | |
104
+ | `nf usage show [--from <date>] [--to <date>]` | Exact amounts, this month to now by default |
105
+ | `nf audit list [--limit <n>]` | |
106
+ | `nf doctor` | Checks this machine: Node, the config file, the profile and whether you are signed in |
107
+ | `nf version` | |
108
+ | `nf help [command]` | |
109
+
110
+ ## Signing in
111
+
112
+ `nf login` opens your browser to sign in with a passkey, then takes the result back on
113
+ `127.0.0.1`. With `--device`, or with no browser, it shows a code to approve from any signed-in
114
+ device. Tokens go to the OS keychain, never to a file or the terminal, and are only ever sent
115
+ to nine fish. `nf logout` signs out and forgets them.
116
+
117
+ A change that needs a step-up, run without a terminal or with `--json` or `--output`, exits 6
118
+ with `step_up_required`: run `nf login`, then the command again.
119
+
120
+ ## Scripts and CI
121
+
122
+ A script or CI job runs as a person: sign in once with `nf login --device` where it runs,
123
+ approve the code from your browser, and it acts with your role. It needs the macOS Keychain or
124
+ the Secret Service there too. Anything that needs a step-up needs your recent passkey, as it
125
+ would at a laptop.
126
+
127
+ In CI (`CI` or `GITHUB_ACTIONS` set), nf never assumes a profile: name one with `--profile` or
128
+ `NF_PROFILE`, or a command exits 7.
129
+
130
+ ## Global options
131
+
132
+ `--org <id or name>`, `--profile <name>`, `--no-interactive`, `--timeout <duration>` (`30`,
133
+ `30s`, `2m`, `1500ms`; default 30s), `--request-id <id>`, `--json`, `--output json|yaml|table`
134
+ (`-o`), `--help` (`-h`), `--version`.
135
+
136
+ ## Profiles
137
+
138
+ A profile chooses an organisation. Flags win over environment variables (`NF_PROFILE`,
139
+ `NF_ORG`), which win over the config file: `NF_CONFIG`, else `$XDG_CONFIG_HOME/nf/config.yaml`,
140
+ else `~/.config/nf/config.yaml`. The config file never holds a credential; nf refuses one that
141
+ does.
142
+
143
+ ```yaml
144
+ profile: work
145
+ profiles:
146
+ work:
147
+ stage: prod
148
+ org: acme
149
+ ```
150
+
151
+ ## Output and errors
152
+
153
+ Output is a table by default, or `--json` / `--output yaml`. In JSON or YAML an error is
154
+ printed on stdout as `{"code", "message", "request_id", "details", "retryable"}`; in a table it
155
+ is a sentence and what to do next, on stderr. Quote the request id to support. A platform's
156
+ client secret goes only to `--secret-file`, readable only by you, or is shown once at a
157
+ terminal; it is never in `--json` output.
158
+
159
+ An error from the API exits by its HTTP status, except `step_up_required`, which is 6:
160
+
161
+ | Status | Exit |
162
+ | ------------- | ---- |
163
+ | 400, 422 | 2 |
164
+ | 401 | 3 |
165
+ | 403 | 8 |
166
+ | 404, 410 | 4 |
167
+ | 409, 412, 428 | 5 |
168
+ | 429, 5xx | 9 |
169
+ | anything else | 1 |
170
+
171
+ No answer within `--timeout`, or no connection, is 9 (`timeout`, `network_error`).
172
+
173
+ ## Exit codes
174
+
175
+ A code never changes meaning.
176
+
177
+ | Code | Name | Meaning |
178
+ | ---- | ----------------- | ------------------------------------------------------------------------------------------------------------------- |
179
+ | 0 | `ok` | It worked. |
180
+ | 1 | `error` | Something failed that no other code covers, or a `doctor` check failed. |
181
+ | 2 | `usage` | The command line is wrong: an unknown command or option, a missing argument, or a value the API refused as invalid. |
182
+ | 3 | `unauthenticated` | Not signed in, or the session has expired. Run `nf login`. |
183
+ | 4 | `notFound` | The organisation, person, domain or platform doesn't exist, or isn't visible to you. |
184
+ | 5 | `conflict` | The resource changed since it was read, or the change conflicts with another. |
185
+ | 6 | `stepUpRequired` | The change needs a passkey presented in the last five minutes (a step-up). |
186
+ | 7 | `config` | The config file, profile or stage selection is invalid or missing. |
187
+ | 8 | `forbidden` | Signed in, but not allowed to do this. |
188
+ | 9 | `retryable` | A timeout, rate limit or server error. Retrying may work. |
189
+
190
+ ## Help
191
+
192
+ Write to [support@nine.fish](mailto:support@nine.fish), which also takes security reports. Use
193
+ of nine fish is under its [terms](https://nine.fish/terms) and
194
+ [privacy policy](https://nine.fish/privacy).