@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 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]` | 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 |
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 deploy [service]` | Trigger a deployment (id or name) |
76
- | `gheima logs <service> [-f] [-b] [-s <text>]` | Show or tail runtime (`-b` → build) logs |
77
- | `gheima templates [list]` | List marketplace templates |
78
- | `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 |
79
81
 
80
82
  ### Configuration
81
83
 
82
- | Command | Description |
83
- | ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------- |
84
- | `gheima env pull <service>` | List env var keys (values are never returned) |
85
- | `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` |
86
- | `gheima env rename <service> <key> <newKey>` | Rename an env var, keeping its value |
87
- | `gheima env rm <service> <key> [-y]` | Remove an env var |
88
- | `gheima env-groups [list]` | List reusable env var groups |
89
- | `gheima env-groups create <name>` | Create an env group |
90
- | `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`) |
91
- | `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 |
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` (machine output, on every command), `--profile <name>`, `--url <url>`,
151
- `--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) |
152
196
 
153
197
  ## Examples
154
198
 
155
199
  ```bash
156
200
  gheima services --json | jq '.[].url'
157
- 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
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();