@gheima/cli 0.4.0 → 0.6.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/CHANGELOG.md +80 -0
- package/README.md +101 -27
- package/dist/bin.js +6 -0
- package/dist/cli.js +444 -78
- package/dist/client.js +18 -7
- package/dist/config.js +1 -1
- package/dist/device-login.js +103 -0
- package/dist/exit.js +49 -0
- package/dist/generated.js +44 -14
- package/dist/link.js +68 -0
- package/dist/prompt.js +11 -3
- package/dist/proxy.js +18 -0
- package/dist/ui.js +63 -4
- package/dist/update-check.js +107 -0
- package/dist/version.js +2 -0
- package/package.json +8 -6
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,85 @@
|
|
|
1
1
|
# @gheima/cli
|
|
2
2
|
|
|
3
|
+
## 0.6.0
|
|
4
|
+
|
|
5
|
+
### Minor Changes
|
|
6
|
+
|
|
7
|
+
- One-off runs: `gheima services create-run <id> --command <command>`, `services runs`,
|
|
8
|
+
`services get-run` and `services run-logs`.
|
|
9
|
+
|
|
10
|
+
- **`gheima link <service>`** binds a directory to a service (`.gheima/project.json`, found
|
|
11
|
+
from any subdirectory, and added to `.gitignore`). `deploy`, `logs`, `env ls/pull/push` and
|
|
12
|
+
`open` then default to it.
|
|
13
|
+
- **`gheima deploy` now waits:** it streams the build and exits 0 once the deployment is live,
|
|
14
|
+
or **8** with the reason if it fails, is cancelled or is skipped. `--no-wait` keeps the old
|
|
15
|
+
behaviour; `--timeout <minutes>` (default 30) exits 7. **Behaviour change:** a script that
|
|
16
|
+
relied on `deploy` returning at once needs `--no-wait`.
|
|
17
|
+
- **`gheima env pull`** now writes the values to `.env.local` (mode 0600). It refuses to
|
|
18
|
+
overwrite without `--force`, and prints values only with `--stdout`. **Behaviour change:**
|
|
19
|
+
the old key listing is now `gheima env ls`.
|
|
20
|
+
- **`gheima env push`** uploads a `.env` file. It merges by default; `--replace` needs `--yes`
|
|
21
|
+
without a terminal. Values round-trip exactly through `pull` and `push`.
|
|
22
|
+
- `gheima open` opens the linked service's dashboard page, and `--live` opens its live URL.
|
|
23
|
+
|
|
24
|
+
- **Scriptable.** `--json` on every command puts exactly one JSON document on stdout, or
|
|
25
|
+
NDJSON for `logs -f`. A command with nothing to return prints `{"ok":true}`, and an error
|
|
26
|
+
is JSON on stderr. Without a terminal, nothing prompts: a command that would ask fails with
|
|
27
|
+
exit code 2 and names the flag to pass, and a destructive operation needs `--yes`, now also
|
|
28
|
+
required on every `DELETE`. `NO_COLOR`, `FORCE_COLOR` and `CI` are honoured.
|
|
29
|
+
- **Documented exit codes:** 0 ok, 1 error, 2 usage, 3 auth, 4 not found, 5 conflict or
|
|
30
|
+
validation, 6 rate limited, 7 network or timeout. Before, every failure exited 1. See the
|
|
31
|
+
README.
|
|
32
|
+
- Errors show the API's `code` and the request id.
|
|
33
|
+
- Deploys and creates retry safely after a 5xx or a dropped connection, reusing one
|
|
34
|
+
`Idempotency-Key` (from `@gheima/sdk`).
|
|
35
|
+
- `HTTPS_PROXY`, `HTTP_PROXY` and `NO_PROXY` are honoured.
|
|
36
|
+
- A one-line notice on stderr when a newer release exists, checked in the background at
|
|
37
|
+
most once a day. Silent under `CI`, `--json` or without a terminal;
|
|
38
|
+
`GHEIMA_NO_UPDATE_CHECK=1` turns it off.
|
|
39
|
+
- `whoami --json` includes which source supplied the key (`auth.source`).
|
|
40
|
+
- **Fixed:** API requests now identify as `gheima-cli/<version>`. They sent no user agent,
|
|
41
|
+
so the audit log recorded CLI actions as the plain `API` surface.
|
|
42
|
+
- **Breaking: requires Node 20.18.1 or newer.** That is the floor of the `undici` it ships with. Node 18 is end-of-life. Installing on Node 18 now
|
|
43
|
+
fails with `EBADENGINE` under `engine-strict`, and may break at runtime otherwise.
|
|
44
|
+
|
|
45
|
+
- The default base URL is now `https://api.gheima.ma/v1`, the API's own host. Existing configuration keeps working unchanged: a URL that ends in `/v1` is used as the API base, and anything else (`https://gheima.ma`, `http://localhost:3000`, every `GHEIMA_URL` and CLI profile written so far) is treated as a dashboard origin and gets `/api/v1` appended, exactly as before. `https://gheima.ma/api/v1` itself stays served permanently.
|
|
46
|
+
|
|
47
|
+
SDK: `client.baseUrl` now returns the resolved API base (for example `https://api.gheima.ma/v1` or `https://gheima.ma/api/v1`) rather than the origin, and `apiBaseUrl()` and `DEFAULT_API_URL` are exported. CLI: `gheima open` still opens the dashboard, falling back to `https://gheima.ma` when the configured URL is an API base.
|
|
48
|
+
|
|
49
|
+
### Patch Changes
|
|
50
|
+
|
|
51
|
+
- The version is now baked in at build time (`src/version.ts`) instead of read from
|
|
52
|
+
`package.json` at runtime, and `dist/bin.js` is the entry for the standalone binary. No
|
|
53
|
+
change for npm installs.
|
|
54
|
+
- Sends `Gheima-Version` on every request, through `@gheima/sdk`.
|
|
55
|
+
- Updated dependencies
|
|
56
|
+
- @gheima/contracts@0.2.0
|
|
57
|
+
- @gheima/sdk@0.3.0
|
|
58
|
+
|
|
59
|
+
## 0.5.0
|
|
60
|
+
|
|
61
|
+
### Minor Changes
|
|
62
|
+
|
|
63
|
+
- 06d9ffc: Sign in through the browser instead of pasting an API key.
|
|
64
|
+
|
|
65
|
+
`gheima login` now starts a device authorization (RFC 8628): it prints a short code, opens
|
|
66
|
+
the dashboard, and polls until someone approves. The key arrives over the same connection
|
|
67
|
+
and is stored in the profile as before, so nothing downstream changes. Approving creates a
|
|
68
|
+
key named after the machine, revocable in Settings → API keys like any other, and only an
|
|
69
|
+
owner or admin can approve one because approving mints a credential.
|
|
70
|
+
|
|
71
|
+
The old path is still there for the cases the browser cannot serve: `--with-key` pastes a
|
|
72
|
+
key, `--no-browser` prints the URL for a headless or SSH session, and passing `--key`
|
|
73
|
+
skips the browser entirely.
|
|
74
|
+
|
|
75
|
+
The polling loop honours the server's `interval` and backs off further on `slow_down`,
|
|
76
|
+
because a client that ignores those is a self-inflicted denial of service against an
|
|
77
|
+
endpoint that takes no credential.
|
|
78
|
+
|
|
79
|
+
Note the published 0.4.0 has the paste-only flow while this repo's 0.4.0 does not, so the
|
|
80
|
+
README on `main` currently describes a browser login that installed clients do not have.
|
|
81
|
+
This release is what closes that gap.
|
|
82
|
+
|
|
3
83
|
## 0.4.0
|
|
4
84
|
|
|
5
85
|
### Minor Changes
|
package/README.md
CHANGED
|
@@ -9,19 +9,48 @@ gheima login
|
|
|
9
9
|
gheima services
|
|
10
10
|
```
|
|
11
11
|
|
|
12
|
-
Requires Node.js 18 or newer.
|
|
12
|
+
Requires Node.js 20.18.1 or newer.
|
|
13
13
|
|
|
14
14
|
## Authentication
|
|
15
15
|
|
|
16
|
+
`gheima login` signs you in through the browser. It prints a short code, opens the
|
|
17
|
+
dashboard, and waits while you approve it — nothing is pasted.
|
|
18
|
+
|
|
16
19
|
```bash
|
|
17
|
-
gheima login #
|
|
20
|
+
gheima login # browser sign-in; the key is stored in ~/.config/gheima/config.json (0600)
|
|
21
|
+
gheima login --no-browser # print the URL instead of opening one (SSH, CI, headless)
|
|
22
|
+
gheima login --with-key # paste an existing API key instead
|
|
18
23
|
gheima login --profile work # named profile
|
|
19
24
|
gheima whoami
|
|
20
25
|
gheima logout
|
|
21
26
|
```
|
|
22
27
|
|
|
28
|
+
Approving creates an API key named after your machine. It appears in **Settings → API
|
|
29
|
+
keys** like any other and can be revoked there at any time. Only an owner or admin can
|
|
30
|
+
approve a device, because approving one mints a key.
|
|
31
|
+
|
|
32
|
+
Approve a login only if you just started it yourself. The approval screen shows the client
|
|
33
|
+
name and the address the request came from — an unfamiliar one means someone else's login,
|
|
34
|
+
and approving it would hand them a key on your account.
|
|
35
|
+
|
|
36
|
+
The login expires after ten minutes and each code can be used once.
|
|
37
|
+
|
|
23
38
|
Resolution order for every command: `--key` → `GHEIMA_API_KEY` → stored profile
|
|
24
|
-
(`--profile` or the current one). Base URL: `--url` → `GHEIMA_URL` → profile.
|
|
39
|
+
(`--profile` or the current one). Base URL: `--url` → `GHEIMA_URL` → profile, defaulting to `https://api.gheima.ma/v1`. A URL
|
|
40
|
+
that does not end in `/v1` is a dashboard origin and gets `/api/v1` appended, as before.
|
|
41
|
+
|
|
42
|
+
### `command not found: gheima` after a global install
|
|
43
|
+
|
|
44
|
+
Your npm global bin directory is not on `PATH` — the package installed fine. Check where it
|
|
45
|
+
went and add it:
|
|
46
|
+
|
|
47
|
+
```bash
|
|
48
|
+
npm prefix -g # e.g. /Users/you/.npm-global
|
|
49
|
+
echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
This bites anyone who set a custom npm prefix to avoid `sudo` without also extending
|
|
53
|
+
`PATH`. `npx gheima <command>` works regardless.
|
|
25
54
|
|
|
26
55
|
## Commands
|
|
27
56
|
|
|
@@ -33,34 +62,37 @@ Resolution order for every command: `--key` → `GHEIMA_API_KEY` → stored prof
|
|
|
33
62
|
| `gheima status` | Account + resource counts |
|
|
34
63
|
| `gheima spend-cap` | Show the monthly spend cap and this month's spend |
|
|
35
64
|
| `gheima spend-cap:set [-c <mad>] [-a <pct>]` | Set or clear the monthly cap (MAD) and alert threshold; omit or `none` to clear |
|
|
36
|
-
| `gheima open [resource]`
|
|
65
|
+
| `gheima open [resource] [--live]` | Open the dashboard, the linked service in it, or with `--live` its live URL |
|
|
37
66
|
| `gheima completion [bash\|zsh\|fish]` | Print a shell-completion script |
|
|
38
67
|
|
|
39
68
|
### Services
|
|
40
69
|
|
|
41
|
-
| Command | Description
|
|
42
|
-
| --------------------------------------------------------------------------------------------------- |
|
|
43
|
-
| `gheima services [list]` | List services
|
|
44
|
-
| `gheima services get <service>` | Show service detail
|
|
45
|
-
| `gheima services create --name <name> [--type WEB\|WORKER\|STATIC] [--repo <url>] [--project <id>]` | Create a service. Names are unique per **account**; omitting `--project` leaves the service ungrouped
|
|
46
|
-
| `gheima services delete <service> [-y]` | Delete a service
|
|
47
|
-
| `gheima
|
|
48
|
-
| `gheima
|
|
49
|
-
| `gheima
|
|
50
|
-
| `gheima templates
|
|
70
|
+
| Command | Description |
|
|
71
|
+
| --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
72
|
+
| `gheima services [list]` | List services |
|
|
73
|
+
| `gheima services get <service>` | Show service detail |
|
|
74
|
+
| `gheima services create --name <name> [--type WEB\|WORKER\|STATIC] [--repo <url>] [--project <id>]` | Create a service. Names are unique per **account**; omitting `--project` leaves the service ungrouped |
|
|
75
|
+
| `gheima services delete <service> [-y]` | Delete a service |
|
|
76
|
+
| `gheima link <service>` | Link the current directory to a service: commands run anywhere inside it then default to that service. Writes `.gheima/project.json` and adds `.gheima/` to `.gitignore` |
|
|
77
|
+
| `gheima deploy [service] [--no-wait] [--timeout <min>]` | Deploy, stream the build, and exit 0 once it is live, or 8 if it fails. `--no-wait` only queues it |
|
|
78
|
+
| `gheima logs [service] [-f] [-b] [-s <text>]` | Show or tail runtime (`-b` → build) logs |
|
|
79
|
+
| `gheima templates [list]` | List marketplace templates |
|
|
80
|
+
| `gheima templates deploy <templateId> <name> [--project <id>]` | Deploy a one-click template |
|
|
51
81
|
|
|
52
82
|
### Configuration
|
|
53
83
|
|
|
54
|
-
| Command | Description
|
|
55
|
-
| ------------------------------------------------------------ |
|
|
56
|
-
| `gheima env
|
|
57
|
-
| `gheima env
|
|
58
|
-
| `gheima env
|
|
59
|
-
| `gheima env
|
|
60
|
-
| `gheima env
|
|
61
|
-
| `gheima env
|
|
62
|
-
| `gheima env-groups
|
|
63
|
-
| `gheima env-groups
|
|
84
|
+
| Command | Description |
|
|
85
|
+
| ------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
86
|
+
| `gheima env ls [service]` | List env var keys, values masked |
|
|
87
|
+
| `gheima env pull [service] [--file <path>] [-f] [--stdout]` | Write the values to `.env.local` (0600). Refuses to overwrite without `-f`, and prints values only with `--stdout`. Variables marked secret cannot be read back and are left out |
|
|
88
|
+
| `gheima env push [service] [--file <path>] [--replace] [-y]` | Upload a `.env` file. Merges by default; `--replace` drops variables not in the file (secret ones are kept) and needs `-y` without a terminal |
|
|
89
|
+
| `gheima env set <service> KEY=value` | Set an env var. Use `--stdin` or `--from-file <path>` with a bare `KEY` to keep the value out of shell history and `ps` |
|
|
90
|
+
| `gheima env rename <service> <key> <newKey>` | Rename an env var, keeping its value |
|
|
91
|
+
| `gheima env rm <service> <key> [-y]` | Remove an env var |
|
|
92
|
+
| `gheima env-groups [list]` | List reusable env var groups |
|
|
93
|
+
| `gheima env-groups create <name>` | Create an env group |
|
|
94
|
+
| `gheima env-groups import <groupId> <file> [--replace] [-y]` | Import a `.env` file into a group (merges by default; `--replace` wipes the group and prompts unless `-y`) |
|
|
95
|
+
| `gheima env-groups attach\|detach <groupId> <service>` | Attach or detach a group |
|
|
64
96
|
|
|
65
97
|
### Storage and data
|
|
66
98
|
|
|
@@ -119,14 +151,56 @@ them from the dashboard or tRPC. The CLI exposes no deploy-hook command.
|
|
|
119
151
|
|
|
120
152
|
## Global flags
|
|
121
153
|
|
|
122
|
-
`--json
|
|
123
|
-
|
|
154
|
+
`--json`, `--profile <name>`, `--url <url>`, `--key <key>`, `-v/--version`, `-h/--help`
|
|
155
|
+
(per command).
|
|
156
|
+
|
|
157
|
+
**Which credential wins:** `--key` → `GHEIMA_API_KEY` → the profile (`--profile`, else the
|
|
158
|
+
current one). The URL follows the same order: `--url` → `GHEIMA_URL` → profile → default.
|
|
159
|
+
`gheima whoami` says which source supplied the key; `whoami --json` puts it under `auth`.
|
|
160
|
+
|
|
161
|
+
## Scripts and CI
|
|
162
|
+
|
|
163
|
+
- **`--json`** works on every command. stdout carries exactly one JSON document, or NDJSON
|
|
164
|
+
(one object per line) for a stream such as `logs -f`. A command with nothing to return prints
|
|
165
|
+
`{"ok":true}`. Progress, warnings and errors go to stderr. An error under `--json` is
|
|
166
|
+
`{"error":{"code","message","status","requestId"}}` on stderr.
|
|
167
|
+
- **Without a terminal** (a pipe, a CI job, `CI` set) nothing prompts and nothing spins. A
|
|
168
|
+
command that would ask a question fails with exit code 2 and names the flag or argument to
|
|
169
|
+
pass. A destructive operation needs `--yes` (`-y`).
|
|
170
|
+
- **Colour:** `FORCE_COLOR` turns it on, then `NO_COLOR` turns it off, then `CI` turns it off.
|
|
171
|
+
Otherwise it's on only when both stdout and stderr are terminals.
|
|
172
|
+
- **Retries:** an operation the API dedupes is sent with an `Idempotency-Key`, and a retry
|
|
173
|
+
after a 5xx or a dropped connection reuses that key, so a flaky network never deploys twice.
|
|
174
|
+
`Retry-After` is honoured.
|
|
175
|
+
- **Proxy:** `HTTPS_PROXY`, `HTTP_PROXY` and `NO_PROXY` are honoured.
|
|
176
|
+
- **Update notice:** at most one line on stderr when a newer release exists, from a cache
|
|
177
|
+
refreshed in the background at most once a day. Never printed under `CI`, `--json` or
|
|
178
|
+
without a terminal; `GHEIMA_NO_UPDATE_CHECK=1` turns it off entirely.
|
|
179
|
+
- Errors print the API's `code` and the **request id**. Quote the request id to support.
|
|
180
|
+
|
|
181
|
+
### Exit codes
|
|
182
|
+
|
|
183
|
+
Stable: a code never changes meaning.
|
|
184
|
+
|
|
185
|
+
| Code | Meaning |
|
|
186
|
+
| ---- | -------------------------------------------------------------------------------------------- |
|
|
187
|
+
| 0 | Success |
|
|
188
|
+
| 1 | Any other error (including a 5xx from the API) |
|
|
189
|
+
| 2 | Usage: unknown flag, missing argument, or a prompt with no terminal (pass the flag it names) |
|
|
190
|
+
| 3 | Not authenticated, or not allowed (401 / 403) |
|
|
191
|
+
| 4 | Not found (404) |
|
|
192
|
+
| 5 | Conflict or validation (400 / 409 / 412 / 422 / 428) |
|
|
193
|
+
| 6 | Rate limited (429) |
|
|
194
|
+
| 7 | Network failure or timeout (no response, 408, 504; also `deploy --timeout`) |
|
|
195
|
+
| 8 | `gheima deploy` waited and the deployment did not go live (failed, cancelled, skipped) |
|
|
124
196
|
|
|
125
197
|
## Examples
|
|
126
198
|
|
|
127
199
|
```bash
|
|
128
200
|
gheima services --json | jq '.[].url'
|
|
129
|
-
gheima
|
|
201
|
+
gheima api services.delete '{"id":"svc_123"}' --yes # no terminal: destructive needs --yes
|
|
202
|
+
gheima logs my-app -f --json | jq -r .line # NDJSON, one entry per line
|
|
203
|
+
gheima link my-app && gheima deploy # later, just: gheima deploy
|
|
130
204
|
gheima logs my-app -f
|
|
131
205
|
gheima env set my-app DATABASE_URL=postgres://…
|
|
132
206
|
gheima env set my-app STRIPE_SECRET --stdin < secret.txt # keeps the value out of shell history
|
package/dist/bin.js
ADDED
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
// Entry point for the standalone binary. It runs the CLI unconditionally: inside a compiled
|
|
2
|
+
// binary `argv[1]` is a virtual path (`/$bunfs/root/gheima`), so the realpath comparison the
|
|
3
|
+
// npm entry uses to detect "am I the main module" can never match, and the binary would exit
|
|
4
|
+
// 0 having done nothing — the same failure @gheima/cli 0.3.0 shipped with through a symlink.
|
|
5
|
+
import { runCli } from './cli.js';
|
|
6
|
+
runCli();
|