gzero-cli 0.1.0-preview.1 → 0.1.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.
Files changed (4) hide show
  1. package/LICENSE +37 -0
  2. package/README.md +116 -35
  3. package/dist/index.js +794 -109
  4. package/package.json +6 -4
package/LICENSE ADDED
@@ -0,0 +1,37 @@
1
+ GroundZero CLI License Agreement
2
+
3
+ Copyright (c) 2026 GroundZero. All rights reserved.
4
+
5
+ This software (the "Software") is proprietary to GroundZero and is licensed, not
6
+ sold. By downloading, installing, or using the Software you agree to these terms.
7
+
8
+ 1. License grant. Subject to your compliance with this agreement and the
9
+ GroundZero Terms of Service, GroundZero grants you a limited, non-exclusive,
10
+ non-transferable, revocable license to install and use the Software solely to
11
+ access and operate your own GroundZero account and services.
12
+
13
+ 2. Restrictions. You may not, and may not permit others to: (a) copy, modify,
14
+ translate, or create derivative works of the Software; (b) reverse engineer,
15
+ decompile, or disassemble the Software, or attempt to derive its source code,
16
+ except to the extent this restriction is prohibited by applicable law;
17
+ (c) rent, lease, lend, sell, sublicense, distribute, or otherwise transfer the
18
+ Software or make it available to any third party; or (d) remove or alter any
19
+ proprietary notices.
20
+
21
+ 3. Ownership. GroundZero and its licensors retain all right, title, and interest
22
+ in and to the Software, including all intellectual property rights. No rights
23
+ are granted except as expressly set out in this agreement.
24
+
25
+ 4. No warranty. THE SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND,
26
+ EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
27
+ MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT.
28
+
29
+ 5. Limitation of liability. TO THE MAXIMUM EXTENT PERMITTED BY LAW, GROUNDZERO
30
+ SHALL NOT BE LIABLE FOR ANY INDIRECT, INCIDENTAL, SPECIAL, CONSEQUENTIAL, OR
31
+ PUNITIVE DAMAGES, OR ANY LOSS OF PROFITS OR DATA, ARISING FROM OR RELATED TO
32
+ YOUR USE OF THE SOFTWARE.
33
+
34
+ 6. Termination. This license terminates automatically if you breach it. On
35
+ termination you must stop using the Software and delete all copies.
36
+
37
+ For questions about licensing, see https://gzer0.app/docs.
package/README.md CHANGED
@@ -1,11 +1,31 @@
1
- # gzero-cli
1
+ <div align="center">
2
2
 
3
- The GroundZero command line: deploy UIs and APIs, manage env vars, domains, and
4
- billing from your terminal or an AI agent. Built on [`@gzero/sdk`](../sdk).
3
+ ```
4
+ ╻
5
+ ╭─╯ ╰─╮ GroundZero
6
+ │ │ Deploy UIs & APIs from your terminal or an AI agent.
7
+ ╰─────╯ gzer0.app
8
+ ```
9
+
10
+ # GroundZero CLI
11
+
12
+ **Deploy UIs and APIs, manage env vars, domains, and billing, straight from your terminal or an AI agent.**
13
+
14
+ [![npm](https://img.shields.io/npm/v/gzero-cli?color=7C6FF0&label=npm&logo=npm&logoColor=white)](https://www.npmjs.com/package/gzero-cli)
15
+ [![node](https://img.shields.io/badge/node-%E2%89%A520-7C6FF0?logo=node.js&logoColor=white)](https://nodejs.org)
16
+ [![platforms](https://img.shields.io/badge/platform-linux%20%C2%B7%20macos%20%C2%B7%20windows-A594FF)](#install)
17
+ [![MCP ready](https://img.shields.io/badge/AI%20agents-MCP%20ready-5B4BE0)](#connect-an-ai-agent-mcp)
18
+
19
+ </div>
20
+
21
+ ---
22
+
23
+ Built on [`@gzero/sdk`](../sdk). Everything the dashboard does, scriptable, with a
24
+ device-code login and a config that plays nicely with CI.
5
25
 
6
26
  ## Install
7
27
 
8
- Requires Node.js 20+.
28
+ Requires **Node.js 20+**.
9
29
 
10
30
  ```bash
11
31
  npm install -g gzero-cli
@@ -15,6 +35,36 @@ npx gzero-cli --help
15
35
 
16
36
  Works on Linux, macOS, and Windows.
17
37
 
38
+ ## Quick start
39
+
40
+ Push your code to GitHub, then go from zero to live in two commands:
41
+
42
+ ```bash
43
+ gzero login # device-code sign in via your browser
44
+ gzero init # pick a repo, auto-detect the build, create + deploy
45
+ ```
46
+
47
+ `gzero init` walks you through it: choose a GitHub repo, pick web app or API,
48
+ attach it to a product (existing or new), and it scans the repo to detect the
49
+ framework, build command, and output folder for you. At the end it offers to
50
+ deploy.
51
+
52
+ Already have projects? Day-to-day it's just:
53
+
54
+ ```bash
55
+ gzero deploy # deploy a project and watch it go live
56
+ gzero status # check readiness, URL, and env vars
57
+ ```
58
+
59
+ `gzero deploy` on a brand-new account with no projects drops straight into the
60
+ `init` flow, then deploys. Run `gzero` with no arguments (or `gzero --help`) to
61
+ see the full command list.
62
+
63
+ > **Note**
64
+ > GroundZero builds and deploys from GitHub, so your code needs to be pushed to
65
+ > a GitHub repo first (the same as the dashboard). The CLI does not upload local
66
+ > files.
67
+
18
68
  ## Sign in
19
69
 
20
70
  ```bash
@@ -32,34 +82,46 @@ in the browser itself.
32
82
 
33
83
  ### Where the token is stored
34
84
 
35
- | OS | Path |
36
- |----|------|
37
- | Linux | `$XDG_CONFIG_HOME/gzero/config.json` or `~/.config/gzero/config.json` |
38
- | macOS | `~/.config/gzero/config.json` |
39
- | Windows | `%APPDATA%\gzero\config.json` (e.g. `C:\Users\you\AppData\Roaming\gzero\config.json`) |
85
+ | OS | Path |
86
+ | ------- | -------------------------------------------------------------------- |
87
+ | Linux | `$XDG_CONFIG_HOME/gzero/config.json` or `~/.config/gzero/config.json` |
88
+ | macOS | `~/.config/gzero/config.json` |
89
+ | Windows | `%APPDATA%\gzero\config.json` |
40
90
 
41
91
  `gzero login` prints the exact path after saving. The file is written with
42
92
  `0600` permissions on Unix.
43
93
 
44
94
  ## Commands
45
95
 
46
- ```
47
- gzero login Device-code sign in; saves an API token
48
- gzero logout Revoke the current token and clear local config
49
- gzero whoami Show the signed-in account
50
- gzero projects (alias: ls) List your projects
51
- gzero deploy [project] Trigger a deploy and follow it to completion
52
- gzero status [project] Active deploy, readiness, and env status
53
- gzero logs [project] Print the latest deploy's build log
54
- gzero env list [project] List env var keys
55
- gzero env set <project> <k> <v> Set an env var
56
- gzero domains add <project> <host> Attach a custom domain
57
- gzero billing Show plan, usage, and available add-ons
58
- gzero billing upgrade Open Stripe checkout (subscribe)
59
- gzero billing addon <id> Open Stripe checkout for an add-on
60
- gzero billing portal Open the Stripe billing portal
61
- gzero mcp Print config to connect an AI agent to the hosted MCP
62
- ```
96
+ | Command | Description |
97
+ | ------- | ----------- |
98
+ | `gzero login` | Device-code sign in; saves an API token |
99
+ | `gzero logout` | Revoke the current token and clear local config |
100
+ | `gzero whoami` | Show the signed-in account |
101
+ | `gzero init [repo]` | Create a project from a GitHub repo (interactive), then optionally deploy |
102
+ | `gzero projects` *(alias `ls`)* | List your projects |
103
+ | `gzero deploy [project]` | Trigger a deploy and follow it to completion (bootstraps `init` on an empty account) |
104
+ | `gzero status [project]` | Active deploy, readiness, and env status |
105
+ | `gzero logs [project]` | Print the latest deploy's build log |
106
+ | `gzero open [project]` | Open the project's live URL in your browser |
107
+ | `gzero rollback [project]` | Roll back to a previous successful deploy |
108
+ | `gzero promote [project]` | Promote a deploy to production |
109
+ | `gzero env list [project]` | List env var keys |
110
+ | `gzero env set <project> <key> <value>` | Set an env var |
111
+ | `gzero env rm <project> <key>` | Delete an env var |
112
+ | `gzero env import <project> <file>` | Bulk-import vars from a `.env` file |
113
+ | `gzero domains list [project]` | List custom domains |
114
+ | `gzero domains add <project> <host>` | Attach a custom domain |
115
+ | `gzero domains verify <project> <host>` | Re-check DNS and verify a domain |
116
+ | `gzero domains remove <project> <host>` | Remove a custom domain |
117
+ | `gzero billing` | Show plan, usage, and available add-ons |
118
+ | `gzero billing upgrade` | Open Stripe checkout (subscribe) |
119
+ | `gzero billing addon <id>` | Open Stripe checkout for an add-on |
120
+ | `gzero billing portal` | Open the Stripe billing portal |
121
+ | `gzero mcp` | Print config to connect an AI agent to the hosted MCP |
122
+
123
+ **`deploy` flags:** `-b, --branch <branch>`, `-e, --env <environment>`,
124
+ `-y, --yes` (acknowledge readiness warnings), `--no-follow` (return immediately).
63
125
 
64
126
  `[project]` accepts a project id, slug, or name. If omitted, the CLI uses your
65
127
  only project or prompts you to pick one.
@@ -71,10 +133,10 @@ by the CLI.
71
133
 
72
134
  Precedence: command-line flags, then environment variables, then the saved config.
73
135
 
74
- | Setting | Flag | Env var |
75
- |---------|------|---------|
76
- | API base URL | `--api-url <url>` | `GZERO_API_URL` |
77
- | API token | `--token <token>` | `GZERO_TOKEN` |
136
+ | Setting | Flag | Env var |
137
+ | ------------ | ---------------- | ---------------- |
138
+ | API base URL | `--api-url <url>` | `GZERO_API_URL` |
139
+ | API token | `--token <token>` | `GZERO_TOKEN` |
78
140
 
79
141
  The default API URL is `https://api.gzer0.app`. For local development against a
80
142
  dev server, point it at your local API:
@@ -85,10 +147,13 @@ GZERO_API_URL=http://localhost:3000 gzero login
85
147
 
86
148
  `GZERO_TOKEN` is handy for CI and other headless callers.
87
149
 
150
+ > **Note**
151
+ > Output is colorized when writing to a terminal. Set `NO_COLOR=1` to disable
152
+ > colors, or `FORCE_COLOR=1` to keep them when piping.
153
+
88
154
  ## Connect an AI agent (MCP)
89
155
 
90
- The MCP server is hosted by GroundZero, so there is nothing extra to install.
91
- Run:
156
+ The MCP server is hosted by GroundZero, so there is nothing extra to install:
92
157
 
93
158
  ```bash
94
159
  gzero mcp
@@ -102,13 +167,29 @@ for details.
102
167
  ## Examples
103
168
 
104
169
  ```bash
170
+ # Create a project from a specific repo and deploy it
171
+ gzero init acme/my-app
172
+
105
173
  # Deploy a specific branch to production and wait for it to go live
106
174
  gzero deploy my-app --branch main --env production
107
175
 
108
- # Set an env var, then redeploy
109
- gzero env set my-app DATABASE_URL "postgres://..."
176
+ # Import a whole .env file, then redeploy
177
+ gzero env import my-app .env.production
110
178
  gzero deploy my-app
111
179
 
112
- # Attach a custom domain
180
+ # Attach and verify a custom domain
113
181
  gzero domains add my-app app.example.com
182
+ gzero domains verify my-app app.example.com
183
+
184
+ # Roll back the last bad deploy
185
+ gzero rollback my-app
186
+
187
+ # Queue a deploy in CI without streaming logs
188
+ GZERO_TOKEN=$CI_TOKEN gzero deploy my-app --yes --no-follow
114
189
  ```
190
+
191
+ ---
192
+
193
+ <div align="center">
194
+ <sub>Part of <a href="https://gzer0.app">GroundZero</a> · <a href="https://gzer0.app/docs">Docs</a> · Built on <a href="../sdk"><code>@gzero/sdk</code></a></sub>
195
+ </div>