@gheima/cli 0.5.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 +56 -0
- package/README.md +72 -26
- package/dist/bin.js +6 -0
- package/dist/cli.js +401 -82
- package/dist/client.js +18 -7
- package/dist/config.js +1 -1
- package/dist/device-login.js +8 -7
- 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,61 @@
|
|
|
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
|
+
|
|
3
59
|
## 0.5.0
|
|
4
60
|
|
|
5
61
|
### Minor Changes
|
package/README.md
CHANGED
|
@@ -9,7 +9,7 @@ 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
|
|
|
@@ -36,7 +36,8 @@ and approving it would hand them a key on your account.
|
|
|
36
36
|
The login expires after ten minutes and each code can be used once.
|
|
37
37
|
|
|
38
38
|
Resolution order for every command: `--key` → `GHEIMA_API_KEY` → stored profile
|
|
39
|
-
(`--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.
|
|
40
41
|
|
|
41
42
|
### `command not found: gheima` after a global install
|
|
42
43
|
|
|
@@ -61,34 +62,37 @@ This bites anyone who set a custom npm prefix to avoid `sudo` without also exten
|
|
|
61
62
|
| `gheima status` | Account + resource counts |
|
|
62
63
|
| `gheima spend-cap` | Show the monthly spend cap and this month's spend |
|
|
63
64
|
| `gheima spend-cap:set [-c <mad>] [-a <pct>]` | Set or clear the monthly cap (MAD) and alert threshold; omit or `none` to clear |
|
|
64
|
-
| `gheima open [resource]`
|
|
65
|
+
| `gheima open [resource] [--live]` | Open the dashboard, the linked service in it, or with `--live` its live URL |
|
|
65
66
|
| `gheima completion [bash\|zsh\|fish]` | Print a shell-completion script |
|
|
66
67
|
|
|
67
68
|
### Services
|
|
68
69
|
|
|
69
|
-
| Command | Description
|
|
70
|
-
| --------------------------------------------------------------------------------------------------- |
|
|
71
|
-
| `gheima services [list]` | List services
|
|
72
|
-
| `gheima services get <service>` | Show service detail
|
|
73
|
-
| `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
|
|
74
|
-
| `gheima services delete <service> [-y]` | Delete a service
|
|
75
|
-
| `gheima
|
|
76
|
-
| `gheima
|
|
77
|
-
| `gheima
|
|
78
|
-
| `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 |
|
|
79
81
|
|
|
80
82
|
### Configuration
|
|
81
83
|
|
|
82
|
-
| Command | Description
|
|
83
|
-
| ------------------------------------------------------------ |
|
|
84
|
-
| `gheima env
|
|
85
|
-
| `gheima env
|
|
86
|
-
| `gheima env
|
|
87
|
-
| `gheima env
|
|
88
|
-
| `gheima env
|
|
89
|
-
| `gheima env
|
|
90
|
-
| `gheima env-groups
|
|
91
|
-
| `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 |
|
|
92
96
|
|
|
93
97
|
### Storage and data
|
|
94
98
|
|
|
@@ -147,14 +151,56 @@ them from the dashboard or tRPC. The CLI exposes no deploy-hook command.
|
|
|
147
151
|
|
|
148
152
|
## Global flags
|
|
149
153
|
|
|
150
|
-
`--json
|
|
151
|
-
|
|
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) |
|
|
152
196
|
|
|
153
197
|
## Examples
|
|
154
198
|
|
|
155
199
|
```bash
|
|
156
200
|
gheima services --json | jq '.[].url'
|
|
157
|
-
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
|
|
158
204
|
gheima logs my-app -f
|
|
159
205
|
gheima env set my-app DATABASE_URL=postgres://…
|
|
160
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();
|