@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 +120 -0
- package/LICENSE +21 -0
- package/README.md +139 -0
- package/dist/cli.js +1298 -0
- package/dist/client.js +11 -0
- package/dist/completion.js +35 -0
- package/dist/config.js +75 -0
- package/dist/generated.js +207 -0
- package/dist/prompt.js +66 -0
- package/dist/ui.js +61 -0
- package/package.json +60 -0
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
|