@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 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 # paste an API key; stored in ~/.config/gheima/config.json (0600)
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]` | Open the dashboard in a browser |
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 deploy [service]` | Trigger a deployment (id or name) |
48
- | `gheima logs <service> [-f] [-b] [-s <text>]` | Show or tail runtime (`-b` → build) logs |
49
- | `gheima templates [list]` | List marketplace templates |
50
- | `gheima templates deploy <templateId> <name> [--project <id>]` | Deploy a one-click template |
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 pull <service>` | List env var keys (values are never returned) |
57
- | `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` |
58
- | `gheima env rename <service> <key> <newKey>` | Rename an env var, keeping its value |
59
- | `gheima env rm <service> <key> [-y]` | Remove an env var |
60
- | `gheima env-groups [list]` | List reusable env var groups |
61
- | `gheima env-groups create <name>` | Create an env group |
62
- | `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`) |
63
- | `gheima env-groups attach\|detach <groupId> <service>` | Attach or detach a group |
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` (machine output, on every command), `--profile <name>`, `--url <url>`,
123
- `--key <key>`, `-v/--version`, `-h/--help` (per command). Commands exit non-zero on error.
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 deploy my-app
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();