@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.
- package/README.md +193 -2
- package/dist/nf.js +3103 -0
- package/package.json +37 -3
package/README.md
CHANGED
|
@@ -1,3 +1,194 @@
|
|
|
1
|
-
#
|
|
1
|
+
# nf
|
|
2
2
|
|
|
3
|
-
|
|
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).
|