@gheima/cli 0.4.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 ADDED
@@ -0,0 +1,120 @@
1
+ # @gheima/cli
2
+
3
+ ## 0.4.0
4
+
5
+ ### Minor Changes
6
+
7
+ - e0f459f: Every API operation is now reachable from the CLI, and `@gheima/contracts` is published.
8
+
9
+ The hand-written commands are unchanged — they own the experience, resolving a service by
10
+ name, printing tables, tailing logs and prompting before anything irreversible. What is new
11
+ is a generated layer beneath them, built from the contract registry at startup, which fills
12
+ in whatever the crafted commands do not cover and skips any path they already own. So a
13
+ capability added to the platform is callable from a terminal the moment it is declared, and
14
+ the generated layer shrinks as the crafted one grows.
15
+
16
+ There is also `gheima api <operation> [json]` for calling anything by id, and
17
+ `gheima api --list` to see what that is.
18
+
19
+ `@gheima/contracts` is published because the CLI and the MCP server both depend on it at
20
+ runtime; it was private, which would have made both of them uninstallable.
21
+
22
+ ### Patch Changes
23
+
24
+ - Updated dependencies [e0f459f]
25
+ - Updated dependencies [5f0cf38]
26
+ - @gheima/contracts@0.2.0
27
+ - @gheima/sdk@0.2.0
28
+
29
+ ## 0.3.0
30
+
31
+ ### Minor Changes
32
+
33
+ - First published release of the CLI. Adds the managed add-on, database-operations and
34
+ account command groups, and documents the full surface in the README.
35
+
36
+ **Added**
37
+
38
+ - `search` — managed search (Meilisearch): `list`, `create <name>`, `reveal <id>`,
39
+ `rotate-key <id>`, `rm <id>`.
40
+ - `queues` — managed job queues (BullMQ-ready Redis): `list`, `create <name>`,
41
+ `reveal <id>`, `rotate-password <id>`, `rm <id>`.
42
+ - `email` — transactional email: `domains`, `add <domain>`, `verify <id>`,
43
+ `send <domainId> <from> <to> <subject> <text>`.
44
+ - `sso` — OIDC connections: `list`, `add <emailDomain> <issuer> <clientId> <clientSecret>`,
45
+ `verify <id>`.
46
+ - `domains` is now a full group on a service: `list`, `add`, `verify`, `rm`
47
+ (was list-only).
48
+ - Database operations: `db:extensions <id>`, `db:enable-ext <id> <name>`,
49
+ `db:backup <id>`, `db:backup:set <id> <cron> [-k] [-z] [--disabled]`,
50
+ `db:backup:remove <id>`.
51
+ - Spend controls: `spend-cap` and `spend-cap:set [-c <mad>] [-a <pct>]`.
52
+ - `env-groups import --replace` to overwrite a group instead of merging.
53
+
54
+ **Fixed**
55
+
56
+ - The binary did nothing when installed. The entrypoint guard compared `import.meta.url`
57
+ to `process.argv[1]` verbatim; every package manager invokes a CLI through a bin
58
+ symlink, and the ESM loader resolves `import.meta.url` to the real path, so the guard
59
+ never matched and `gheima <anything>` exited 0 without parsing. Both sides are now
60
+ resolved with `realpathSync`, covered by a test that runs the built binary through a
61
+ symlink.
62
+ - `storage ls` walks every page instead of silently truncating a bucket at the first
63
+ one (`--page` keeps the old single-page behaviour).
64
+ - `storage get` refuses to overwrite an existing local file unless `--force` is given.
65
+ - `storage cp` / `storage get` stream to and from disk instead of buffering the whole
66
+ object in memory, so an object larger than the heap transfers.
67
+ - `env-groups import --replace` now confirms before wiping a group that may be attached
68
+ to many services, matching every other destructive command (`-y` to skip).
69
+ - Shell completion is generated from the program's own command list. The hand-kept copy
70
+ had drifted to 17 of 26 groups, so `search`, `queues`, `email`, `sso`, `templates`,
71
+ `env-groups`, `spend-cap` and the `db:*` commands never completed.
72
+ - `~/.config/gheima/config.json` is created 0600 rather than created 0644 and chmod'd
73
+ after, and its directory is 0700.
74
+ - `open` no longer routes through a shell on Windows.
75
+ - `gheima login` strips control bytes and escape sequences from the pasted key, so an
76
+ arrow key no longer corrupts it.
77
+
78
+ **Added**
79
+
80
+ - `env set <service> KEY --stdin` / `--from-file <path>`, to keep a secret off the
81
+ command line, where it lands in shell history and `ps`.
82
+
83
+ **Changed**
84
+
85
+ - Omitting `--project` on `services create` and `templates deploy` now leaves the service
86
+ **ungrouped**. No "Default" project is auto-created any more — services are
87
+ account-scoped and a project is an optional folder you can move a service into later.
88
+ Supersedes the 0.2.0 note.
89
+ - Service names are unique per **account**, not per project. A `services create` that
90
+ previously succeeded under a second project may now return `409 conflict`, naming the
91
+ conflicting fields in the error message.
92
+ - `engines.node` is now declared as `>=18`.
93
+
94
+ **Notes**
95
+
96
+ - Deploy-hook URLs are shown once, at creation or rotation, and cannot be re-revealed
97
+ (only a SHA-256 digest is stored). The CLI exposes no deploy-hook command — manage hooks
98
+ from the dashboard or tRPC.
99
+ - `db` / `databases` remains list-only; managed-database creation is dashboard/REST/SDK-only.
100
+ - `webhooks` prints an empty event list as `*`. The `'*'` wildcard no longer exists in the
101
+ API — an empty list means "subscribed to all events".
102
+
103
+ ## 0.2.0 (2026-07-25)
104
+
105
+ ### Breaking
106
+
107
+ - `templates deploy` signature changed: `gheima templates deploy <templateId> <name> [--project <id>]`
108
+ (was `gheima templates deploy <templateId> <project> <name>`). The project moved to an
109
+ optional `--project` flag — commander cannot express an optional positional between two
110
+ required ones. Scripts using the old three-positional form must be updated.
111
+
112
+ ### Changed
113
+
114
+ - `services create --project` is now optional. When omitted (here and in
115
+ `templates deploy`), the resource lands in the account's auto-created **Default** project.
116
+
117
+ ### Added
118
+
119
+ - `volumes` command group: `volumes list <service>`, `volumes add <service> <mountPath> [--name]`,
120
+ `volumes rm <service> <volumeId> [-y]` — persistent-volume management, matching the SDK/REST surface.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Gheima
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,139 @@
1
+ # @gheima/cli
2
+
3
+ Command-line interface for the [Gheima](https://gheima.ma) platform. Built on the
4
+ typed [`@gheima/sdk`](../sdk).
5
+
6
+ ```bash
7
+ npm install -g @gheima/cli # or: npx gheima <command>
8
+ gheima login
9
+ gheima services
10
+ ```
11
+
12
+ Requires Node.js 18 or newer.
13
+
14
+ ## Authentication
15
+
16
+ ```bash
17
+ gheima login # paste an API key; stored in ~/.config/gheima/config.json (0600)
18
+ gheima login --profile work # named profile
19
+ gheima whoami
20
+ gheima logout
21
+ ```
22
+
23
+ Resolution order for every command: `--key` → `GHEIMA_API_KEY` → stored profile
24
+ (`--profile` or the current one). Base URL: `--url` → `GHEIMA_URL` → profile.
25
+
26
+ ## Commands
27
+
28
+ ### Account
29
+
30
+ | Command | Description |
31
+ | -------------------------------------------- | ------------------------------------------------------------------------------- |
32
+ | `gheima whoami` | Show the account for the active key |
33
+ | `gheima status` | Account + resource counts |
34
+ | `gheima spend-cap` | Show the monthly spend cap and this month's spend |
35
+ | `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 |
37
+ | `gheima completion [bash\|zsh\|fish]` | Print a shell-completion script |
38
+
39
+ ### Services
40
+
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 |
51
+
52
+ ### Configuration
53
+
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 |
64
+
65
+ ### Storage and data
66
+
67
+ | Command | Description |
68
+ | ------------------------------------------------------------------ | ------------------------------------------------------------------------------- |
69
+ | `gheima db` | List databases (creation is dashboard/REST/SDK-only) |
70
+ | `gheima db:extensions <id>` | List curated Postgres extensions and whether each is enabled |
71
+ | `gheima db:enable-ext <id> <name>` | Enable an extension (e.g. `vector` for pgvector) |
72
+ | `gheima db:backup <id>` | Show a database backup schedule |
73
+ | `gheima db:backup:set <id> <cron> [-k <n>] [-z <tz>] [--disabled]` | Set a 5-field cron backup schedule |
74
+ | `gheima db:backup:remove <id>` | Remove a backup schedule |
75
+ | `gheima storage buckets` | List storage buckets |
76
+ | `gheima storage ls <bucket> [prefix] [--page]` | List objects (walks every page; `--page` stops after the first) |
77
+ | `gheima storage cp <file> <bucket> [key]` | Upload via presigned PUT |
78
+ | `gheima storage get <bucket> <key> [dest] [-f]` | Download via presigned GET (refuses to overwrite an existing file without `-f`) |
79
+ | `gheima storage rm <bucket> <key> [-y]` | Delete an object |
80
+ | `gheima volumes list <service>` | List persistent volumes on a service |
81
+ | `gheima volumes add <service> <mountPath> [--name <name>]` | Attach a volume (applies on next deploy) |
82
+ | `gheima volumes rm <service> <volumeId> [-y]` | Detach a volume (data retained) |
83
+
84
+ ### Managed add-ons
85
+
86
+ | Command | Description |
87
+ | ----------------------------------------------------------- | ------------------------------------------------------------------------- |
88
+ | `gheima search [list]` | List managed search (Meilisearch) instances |
89
+ | `gheima search create <name>` | Provision a search instance |
90
+ | `gheima search reveal <id>` | Reveal host, scoped API key, index prefix |
91
+ | `gheima search rotate-key <id>` | Rotate the scoped API key |
92
+ | `gheima search rm <id> [-y]` | Deprovision a search instance |
93
+ | `gheima queues [list]` | List managed job queues (BullMQ-ready Redis) |
94
+ | `gheima queues create <name>` | Provision a job queue |
95
+ | `gheima queues reveal <id>` | Reveal the Redis connection string + key prefix |
96
+ | `gheima queues rotate-password <id>` | Rotate the Redis password |
97
+ | `gheima queues rm <id> [-y]` | Deprovision a job queue |
98
+ | `gheima email domains` | List transactional-email sending domains |
99
+ | `gheima email add <domain>` | Register a sending domain (prints DNS records to add) |
100
+ | `gheima email verify <id>` | Re-check the DKIM DNS record |
101
+ | `gheima email send <domainId> <from> <to> <subject> <text>` | Send a plain-text email |
102
+ | `gheima cron` | List cron jobs |
103
+ | `gheima webhooks` | List webhooks (an empty event list prints `*` — subscribed to all events) |
104
+
105
+ ### Domains and access
106
+
107
+ | Command | Description |
108
+ | ----------------------------------------------------------------- | ------------------------------------------------------- |
109
+ | `gheima domains list <service>` | List custom domains on a service |
110
+ | `gheima domains add <service> <domain>` | Attach a custom domain (prints the DNS records to add) |
111
+ | `gheima domains verify <domainId>` | Re-check the TXT challenge and mark verified |
112
+ | `gheima domains rm <domainId> [-y]` | Detach a custom domain |
113
+ | `gheima sso [list]` | List SSO (OIDC) connections |
114
+ | `gheima sso add <emailDomain> <issuer> <clientId> <clientSecret>` | Register an OIDC provider (prints the DNS proof record) |
115
+ | `gheima sso verify <id>` | Re-check the DNS proof and activate the connection |
116
+
117
+ Deploy-hook URLs are shown once, at creation or rotation, and cannot be re-revealed — manage
118
+ them from the dashboard or tRPC. The CLI exposes no deploy-hook command.
119
+
120
+ ## Global flags
121
+
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.
124
+
125
+ ## Examples
126
+
127
+ ```bash
128
+ gheima services --json | jq '.[].url'
129
+ gheima deploy my-app
130
+ gheima logs my-app -f
131
+ gheima env set my-app DATABASE_URL=postgres://…
132
+ gheima env set my-app STRIPE_SECRET --stdin < secret.txt # keeps the value out of shell history
133
+ gheima db:backup:set db_123 "0 3 * * *" -k 14 -z Africa/Casablanca
134
+ gheima completion zsh > ~/.gheima-completion.zsh
135
+ ```
136
+
137
+ ## License
138
+
139
+ MIT