@gheima/cli 0.5.0 → 0.7.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,76 @@
1
1
  # @gheima/cli
2
2
 
3
+ ## 0.7.0
4
+
5
+ ### Minor Changes
6
+
7
+ - 9067536: **`gheima run <service> -- <cmd>`** runs a one-off command (a migration, a seed) in a fresh container from the service's live image and environment, waits for it, prints its log and exits with the command's own exit code, or **9** when the run ended without one (refused, timed out). `--timeout <seconds>` (default 300, at most 3600) bounds the command; `--no-wait` only queues it. Under `--json`, stdout is one document holding the run and its log.
8
+
9
+ ### Patch Changes
10
+
11
+ - d011c04: **Breaking (types only):** response types now say what the API actually sends. `ServiceSummary.url` and `.branch`, and `Service.projectId`, `.subdomain` and `.repoBranch` are `string | null` (a service need not sit in a project, and has no URL until it is routed). `Service` no longer declares `branch`, which the single-service response never carried — use `repoBranch`. `QueueSummary.keyPrefix` is `string | null`, and `ActivityEvent` is read from the API contract: `metadata` is `unknown` (narrow it before use) and `actorName` is added. Code that compiled against 0.3.0 may need a null check; nothing changes at runtime.
12
+
13
+ `gheima open --live` now says the service has no live URL yet instead of trying to open `null`.
14
+
15
+ - Updated dependencies [d011c04]
16
+ - @gheima/sdk@0.4.0
17
+
18
+ ## 0.6.0
19
+
20
+ ### Minor Changes
21
+
22
+ - One-off runs: `gheima services create-run <id> --command <command>`, `services runs`,
23
+ `services get-run` and `services run-logs`.
24
+
25
+ - **`gheima link <service>`** binds a directory to a service (`.gheima/project.json`, found
26
+ from any subdirectory, and added to `.gitignore`). `deploy`, `logs`, `env ls/pull/push` and
27
+ `open` then default to it.
28
+ - **`gheima deploy` now waits:** it streams the build and exits 0 once the deployment is live,
29
+ or **8** with the reason if it fails, is cancelled or is skipped. `--no-wait` keeps the old
30
+ behaviour; `--timeout <minutes>` (default 30) exits 7. **Behaviour change:** a script that
31
+ relied on `deploy` returning at once needs `--no-wait`.
32
+ - **`gheima env pull`** now writes the values to `.env.local` (mode 0600). It refuses to
33
+ overwrite without `--force`, and prints values only with `--stdout`. **Behaviour change:**
34
+ the old key listing is now `gheima env ls`.
35
+ - **`gheima env push`** uploads a `.env` file. It merges by default; `--replace` needs `--yes`
36
+ without a terminal. Values round-trip exactly through `pull` and `push`.
37
+ - `gheima open` opens the linked service's dashboard page, and `--live` opens its live URL.
38
+
39
+ - **Scriptable.** `--json` on every command puts exactly one JSON document on stdout, or
40
+ NDJSON for `logs -f`. A command with nothing to return prints `{"ok":true}`, and an error
41
+ is JSON on stderr. Without a terminal, nothing prompts: a command that would ask fails with
42
+ exit code 2 and names the flag to pass, and a destructive operation needs `--yes`, now also
43
+ required on every `DELETE`. `NO_COLOR`, `FORCE_COLOR` and `CI` are honoured.
44
+ - **Documented exit codes:** 0 ok, 1 error, 2 usage, 3 auth, 4 not found, 5 conflict or
45
+ validation, 6 rate limited, 7 network or timeout. Before, every failure exited 1. See the
46
+ README.
47
+ - Errors show the API's `code` and the request id.
48
+ - Deploys and creates retry safely after a 5xx or a dropped connection, reusing one
49
+ `Idempotency-Key` (from `@gheima/sdk`).
50
+ - `HTTPS_PROXY`, `HTTP_PROXY` and `NO_PROXY` are honoured.
51
+ - A one-line notice on stderr when a newer release exists, checked in the background at
52
+ most once a day. Silent under `CI`, `--json` or without a terminal;
53
+ `GHEIMA_NO_UPDATE_CHECK=1` turns it off.
54
+ - `whoami --json` includes which source supplied the key (`auth.source`).
55
+ - **Fixed:** API requests now identify as `gheima-cli/<version>`. They sent no user agent,
56
+ so the audit log recorded CLI actions as the plain `API` surface.
57
+ - **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
58
+ fails with `EBADENGINE` under `engine-strict`, and may break at runtime otherwise.
59
+
60
+ - 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.
61
+
62
+ 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.
63
+
64
+ ### Patch Changes
65
+
66
+ - The version is now baked in at build time (`src/version.ts`) instead of read from
67
+ `package.json` at runtime, and `dist/bin.js` is the entry for the standalone binary. No
68
+ change for npm installs.
69
+ - Sends `Gheima-Version` on every request, through `@gheima/sdk`.
70
+ - Updated dependencies
71
+ - @gheima/contracts@0.2.0
72
+ - @gheima/sdk@0.3.0
73
+
3
74
  ## 0.5.0
4
75
 
5
76
  ### Minor Changes
package/README.md CHANGED
@@ -9,7 +9,15 @@ 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, unless you use the standalone binary, which needs nothing:
13
+
14
+ ```bash
15
+ curl -fsSL https://gheima.ma/install.sh | sh # macOS / Linux, checksum-verified, to ~/.local/bin
16
+ brew install gheima/tap/gheima # or Homebrew
17
+ ```
18
+
19
+ Windows: download `gheima-windows-x64.exe` from the
20
+ [latest release](https://github.com/gheima/cli/releases/latest).
13
21
 
14
22
  ## Authentication
15
23
 
@@ -36,7 +44,8 @@ and approving it would hand them a key on your account.
36
44
  The login expires after ten minutes and each code can be used once.
37
45
 
38
46
  Resolution order for every command: `--key` → `GHEIMA_API_KEY` → stored profile
39
- (`--profile` or the current one). Base URL: `--url` → `GHEIMA_URL` → profile.
47
+ (`--profile` or the current one). Base URL: `--url` → `GHEIMA_URL` → profile, defaulting to `https://api.gheima.ma/v1`. A URL
48
+ that does not end in `/v1` is a dashboard origin and gets `/api/v1` appended, as before.
40
49
 
41
50
  ### `command not found: gheima` after a global install
42
51
 
@@ -61,34 +70,38 @@ This bites anyone who set a custom npm prefix to avoid `sudo` without also exten
61
70
  | `gheima status` | Account + resource counts |
62
71
  | `gheima spend-cap` | Show the monthly spend cap and this month's spend |
63
72
  | `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 |
73
+ | `gheima open [resource] [--live]` | Open the dashboard, the linked service in it, or with `--live` its live URL |
65
74
  | `gheima completion [bash\|zsh\|fish]` | Print a shell-completion script |
66
75
 
67
76
  ### Services
68
77
 
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 |
78
+ | Command | Description |
79
+ | --------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
80
+ | `gheima services [list]` | List services |
81
+ | `gheima services get <service>` | Show service detail |
82
+ | `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 |
83
+ | `gheima services delete <service> [-y]` | Delete a service |
84
+ | `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` |
85
+ | `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 |
86
+ | `gheima logs [service] [-f] [-b] [-s <text>]` | Show or tail runtime (`-b` → build) logs |
87
+ | `gheima run <service> [--timeout <s>] [--no-wait] -- <cmd>` | Run a one-off command (a migration, a seed) in a fresh container from the service's live image and environment, print its log, and exit with its exit code. The words after `--` are joined and run by the remote `/bin/sh -c`, so quote the whole command when an argument holds spaces: `gheima run web -- 'psql -c "select 1"'`. Admins only; 10 runs an hour per service |
88
+ | `gheima templates [list]` | List marketplace templates |
89
+ | `gheima templates deploy <templateId> <name> [--project <id>]` | Deploy a one-click template |
79
90
 
80
91
  ### Configuration
81
92
 
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 |
93
+ | Command | Description |
94
+ | ------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
95
+ | `gheima env ls [service]` | List env var keys, values masked |
96
+ | `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 |
97
+ | `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 |
98
+ | `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` |
99
+ | `gheima env rename <service> <key> <newKey>` | Rename an env var, keeping its value |
100
+ | `gheima env rm <service> <key> [-y]` | Remove an env var |
101
+ | `gheima env-groups [list]` | List reusable env var groups |
102
+ | `gheima env-groups create <name>` | Create an env group |
103
+ | `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`) |
104
+ | `gheima env-groups attach\|detach <groupId> <service>` | Attach or detach a group |
92
105
 
93
106
  ### Storage and data
94
107
 
@@ -147,14 +160,59 @@ them from the dashboard or tRPC. The CLI exposes no deploy-hook command.
147
160
 
148
161
  ## Global flags
149
162
 
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.
163
+ `--json`, `--profile <name>`, `--url <url>`, `--key <key>`, `-v/--version`, `-h/--help`
164
+ (per command).
165
+
166
+ **Which credential wins:** `--key` → `GHEIMA_API_KEY` → the profile (`--profile`, else the
167
+ current one). The URL follows the same order: `--url` → `GHEIMA_URL` → profile → default.
168
+ `gheima whoami` says which source supplied the key; `whoami --json` puts it under `auth`.
169
+
170
+ ## Scripts and CI
171
+
172
+ - **`--json`** works on every command. stdout carries exactly one JSON document, or NDJSON
173
+ (one object per line) for a stream such as `logs -f`. A command with nothing to return prints
174
+ `{"ok":true}`. Progress, warnings and errors go to stderr. An error under `--json` is
175
+ `{"error":{"code","message","status","requestId"}}` on stderr.
176
+ - **Without a terminal** (a pipe, a CI job, `CI` set) nothing prompts and nothing spins. A
177
+ command that would ask a question fails with exit code 2 and names the flag or argument to
178
+ pass. A destructive operation needs `--yes` (`-y`).
179
+ - **Colour:** `FORCE_COLOR` turns it on, then `NO_COLOR` turns it off, then `CI` turns it off.
180
+ Otherwise it's on only when both stdout and stderr are terminals.
181
+ - **Retries:** an operation the API dedupes is sent with an `Idempotency-Key`, and a retry
182
+ after a 5xx or a dropped connection reuses that key, so a flaky network never deploys twice.
183
+ `Retry-After` is honoured.
184
+ - **Proxy:** `HTTPS_PROXY`, `HTTP_PROXY` and `NO_PROXY` are honoured.
185
+ - **Update notice:** at most one line on stderr when a newer release exists, from a cache
186
+ refreshed in the background at most once a day. Never printed under `CI`, `--json` or
187
+ without a terminal; `GHEIMA_NO_UPDATE_CHECK=1` turns it off entirely.
188
+ - Errors print the API's `code` and the **request id**. Quote the request id to support.
189
+
190
+ ### Exit codes
191
+
192
+ Stable: a code never changes meaning.
193
+
194
+ | Code | Meaning |
195
+ | ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
196
+ | 0 | Success |
197
+ | 1 | Any other error (including a 5xx from the API) |
198
+ | 2 | Usage: unknown flag, missing argument, or a prompt with no terminal (pass the flag it names) |
199
+ | 3 | Not authenticated, or not allowed (401 / 403) |
200
+ | 4 | Not found (404) |
201
+ | 5 | Conflict or validation (400 / 409 / 412 / 422 / 428) |
202
+ | 6 | Rate limited (429) |
203
+ | 7 | Network failure or timeout (no response, 408, 504; also `deploy --timeout`) |
204
+ | 8 | `gheima deploy` waited and the deployment did not go live (failed, cancelled, skipped) |
205
+ | 9 | `gheima run` ended without the command reporting an exit code (refused, timed out). Otherwise `run` exits with the command's own code, which can be any of these numbers: a command that exits 6 is not a rate limit, so after `run` branch on the command's codes, not this table |
152
206
 
153
207
  ## Examples
154
208
 
155
209
  ```bash
156
210
  gheima services --json | jq '.[].url'
157
- gheima deploy my-app
211
+ gheima api services.delete '{"id":"svc_123"}' --yes # no terminal: destructive needs --yes
212
+ gheima logs my-app -f --json | jq -r .line # NDJSON, one entry per line
213
+ gheima link my-app && gheima deploy # later, just: gheima deploy
214
+ gheima run my-app -- npx prisma migrate deploy # exits with the migration's own code
215
+ gheima run my-app -- 'psql -c "select count(*) from users"' # quote it whole: the remote shell splits it
158
216
  gheima logs my-app -f
159
217
  gheima env set my-app DATABASE_URL=postgres://…
160
218
  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();