@abruncloud/cli 0.1.0 → 0.1.2

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 (3) hide show
  1. package/README.md +133 -184
  2. package/dist/abrun.js +22 -22
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -1,261 +1,210 @@
1
- # abrun cli
1
+ # Abrun CLI
2
2
 
3
- CLI for the abrun platform.
3
+ Command line tools for managing Abrun projects, apps, deployments, databases, and tokens.
4
4
 
5
- ## Model
6
-
7
- The CLI is flow-first.
8
-
9
- There is no separate command action layer. A command is an ordered onion stack:
10
-
11
- ```text
12
- input -> resolve auth -> resolve user -> resolve project -> resolve resource -> perform operation -> render output
5
+ ```sh
6
+ npm install -g @abruncloud/cli
13
7
  ```
14
8
 
15
- Examples:
9
+ After installation, the `abrun` command is available globally:
16
10
 
17
- ```text
18
- abrun login
19
- => [withState, login]
20
-
21
- abrun app create <name>
22
- => [withState, withSelectedAuth, withProject, createApp, printCreatedApp]
23
-
24
- abrun app domain add <app> <hostname>
25
- => [withState, withSelectedAuth, withProject, withApp, addDomain, printDomain]
11
+ ```sh
12
+ abrun --help
26
13
  ```
27
14
 
28
- Resolver onions usually start with `with*`.
29
- Terminal onions use verbs like `createApp`, `restartApp`, `verifyDomain`, or `printCreatedApp`.
30
- The runtime API client is also an onion now, so flows explicitly add `withClient` where they need an authenticated or project-scoped client instance.
31
-
32
- ## SDK
33
-
34
- The /api SDK is generated from `docs/openapi.yaml` into `apps/sdk/src/api-client`.
15
+ ## Login
35
16
 
36
- Regenerate it with:
17
+ Start with browser-based login:
37
18
 
38
- ```bash
39
- cd ../.. && bun run generate:sdk
19
+ ```sh
20
+ abrun login
40
21
  ```
41
22
 
42
- CLI code should import the public SDK from `@abruncloud/sdk`:
23
+ You can also use an API token for automation:
43
24
 
44
- ```ts
45
- import { HttpClient, V1, type Project } from '@abruncloud/sdk'
25
+ ```sh
26
+ ABRUN_TOKEN=abrn_... abrun apps
46
27
  ```
47
28
 
48
- The CLI runtime injects auth/project context through `src/lib/runtime.ts`.
49
-
50
- ## Current Commands
29
+ Useful auth commands:
51
30
 
52
- ```text
53
- abrun login
54
- abrun logout
31
+ ```sh
55
32
  abrun whoami
56
-
33
+ abrun logout
57
34
  abrun auth list
58
35
  abrun auth use <auth>
59
36
  abrun auth remove <auth>
37
+ ```
38
+
39
+ ## Projects
60
40
 
41
+ Select the project you want commands to use by default:
42
+
43
+ ```sh
61
44
  abrun project list
62
45
  abrun project use <project>
63
46
  abrun project current
47
+ ```
64
48
 
65
- abrun app list
66
- abrun app inspect <app>
49
+ You can override the selected project per command:
50
+
51
+ ```sh
52
+ abrun --project <project> apps
53
+ ```
54
+
55
+ ## Apps
56
+
57
+ Create and manage applications:
58
+
59
+ ```sh
67
60
  abrun app create <name>
68
- abrun app update <app>
69
- abrun app delete <app>
61
+ abrun apps
62
+ abrun app inspect <app>
70
63
  abrun app start <app>
71
64
  abrun app stop <app>
72
65
  abrun app restart <app>
73
- abrun app status <app>
74
- abrun app logs <app> [--follow]
66
+ abrun app logs <app> --follow
75
67
  abrun app shell <app>
76
- abrun app deploy <app> [path]
77
- abrun deploy <app> [path]
78
-
79
- abrun app disk list <app>
80
- abrun app disk inspect <app> <disk>
81
- abrun app disk create <app> <name> --size <gb>
82
- abrun app disk mount <app> <disk> <mountPath>
83
- abrun app disk unmount <app> <disk>
84
- abrun app disk expand <app> <disk> --size <gb>
85
- abrun app disk delete <app> <disk>
86
-
87
- abrun app env list <app>
88
- abrun app env set <app> KEY=VALUE
89
- abrun app env unset <app> KEY
90
-
91
- abrun app domain list <app>
92
- abrun app domain add <app> <hostname>
93
- abrun app domain delete <app> <hostname>
94
- abrun app domain verify <app> <hostname>
95
- abrun app domain check <app> <hostname>
96
-
97
- abrun app deployment list <app>
98
- abrun app deployment inspect <app> <deployment>
99
- abrun app deployment logs <app> <deployment>
100
- abrun app deployment watch <app> <deployment>
101
- abrun app deployment cancel <app> <deployment>
102
- abrun app deployment redo <app> <deployment>
103
-
104
- abrun db list
105
- abrun db inspect <database>
106
- abrun db create <name>
107
- abrun db update <database>
108
- abrun db delete <database>
109
- abrun db start <database>
110
- abrun db stop <database>
111
- abrun db logs <database> [--follow]
112
- abrun db tunnel <database> --port <port> [--host <host>]
113
- abrun db credentials <database> --show-password
114
- abrun db backup list <database>
115
- abrun db backup create <database>
68
+ abrun app delete <app>
116
69
  ```
117
70
 
118
- Global flags:
71
+ Deploy source from the current directory:
119
72
 
120
- ```text
121
- --endpoint <url>
122
- --auth <auth>
123
- --project <project>
124
- --json
73
+ ```sh
74
+ abrun deploy <app>
125
75
  ```
126
76
 
127
- Auth resolution order:
77
+ Deploy source from another path:
128
78
 
129
- ```text
130
- explicit flags -> ABRUN_TOKEN -> saved local state
79
+ ```sh
80
+ abrun deploy <app> ./path/to/source
131
81
  ```
132
82
 
133
- `ABRUN_TOKEN` is a normal API token and always wins over saved local auth. It is sent as:
83
+ Deploy an existing image:
134
84
 
135
- ```text
136
- Authorization: Bearer <token>
85
+ ```sh
86
+ abrun deploy <app> --image registry.example.com/app:latest
137
87
  ```
138
88
 
139
- `abrun login` uses browser approval by default. The CLI calls `POST /api/auth/cli-login`, opens the returned browser URL, polls with the private `pollToken`, and stores only the returned API token after approval. Browser codes and poll tokens are not stored.
140
-
141
- Email/password login is still available when `--email` or `--password` is provided, and uses `POST /api/auth/login`.
89
+ Common deploy flags:
142
90
 
143
- Project selection is local CLI state. `abrun project use <project>` accepts a project ID or immutable slug, resolves it through `GET /api/projects`, and stores the resolved `projectID`. Project-scoped collection requests send:
144
-
145
- ```text
146
- X-Project-ID: <projectID>
91
+ ```sh
92
+ abrun deploy <app> --port 3000
93
+ abrun deploy <app> --message "Release checkout fixes"
94
+ abrun deploy <app> --logs
147
95
  ```
148
96
 
149
- `abrun app deploy` and `abrun deploy` are CLI-first deploy actions. Source deploys default to the current working directory, or use `[path]` when provided. Image deploys use the same `/deploy` endpoint with `--image`.
150
-
151
- ## Deploy Flow
152
-
153
- `abrun app deploy <app> [path]` performs a local source sync before creating the deployment:
154
-
155
- 1. scans the selected source directory recursively
156
- 2. respects nested `.gitignore` and `.abrunignore` files
157
- 3. always excludes a hard denylist such as `.git`, `.abrun`, `node_modules`, common cache folders, and `.env*`
158
- 4. sends the current file manifest to `POST /api/apps/{appID}/deploy`
159
- 5. if the server returns `sync_required`, prints the requested file count
160
- 6. creates a tar archive with only the required changed files
161
- 7. uploads that archive through `POST /api/apps/{appID}/upload`
162
- 8. retries `POST /api/apps/{appID}/deploy` with the same file manifest
163
- 9. polls rollout status, prints build/deployment logs, then exits when the rollout reaches a terminal state
97
+ Deployment commands:
164
98
 
165
- Deploy flags:
166
-
167
- ```text
168
- --image <image> Deploy an image instead of source
169
- --port <port> Update runtime port for this deploy
170
- --message <text> Deployment message
171
- --logs Follow app logs after a successful deploy
99
+ ```sh
100
+ abrun app deployment list <app>
101
+ abrun app deployment inspect <app> <deployment>
102
+ abrun app deployment logs <app> <deployment>
103
+ abrun app deployment watch <app> <deployment>
104
+ abrun app deployment cancel <app> <deployment>
105
+ abrun app deployment redo <app> <deployment>
172
106
  ```
173
107
 
174
- Image deploys call `POST /api/apps/{appID}/deploy` directly and do not scan or upload local files.
108
+ ## App Settings
175
109
 
176
- ## Runtime Streams
110
+ Environment variables:
177
111
 
178
- Runtime log commands use the new API:
179
-
180
- ```text
181
- GET /api/apps/{appID}/logs
182
- GET /api/databases/{databaseID}/logs
112
+ ```sh
113
+ abrun app env list <app>
114
+ abrun app env set <app> KEY=VALUE
115
+ abrun app env unset <app> KEY
183
116
  ```
184
117
 
185
- `abrun db tunnel` keeps the process attached, listens on the requested local host and port, and opens one authorized websocket tunnel per local TCP client connection. It prints the database name, engine, and local address only; credentials are available through the explicit credentials command.
118
+ Domains:
186
119
 
187
- `--follow` adds `stream=true` and reads Server-Sent Events. `--tail`, `--since`, `--filter`, and `--previous` map to the API log query parameters.
120
+ ```sh
121
+ abrun app domain list <app>
122
+ abrun app domain add <app> <hostname>
123
+ abrun app domain verify <app> <hostname>
124
+ abrun app domain check <app> <hostname>
125
+ abrun app domain delete <app> <hostname>
126
+ ```
188
127
 
189
- `abrun app shell <app>` uses `GET /api/apps/{appID}/console` as a WebSocket console and sends normal bearer auth. The current API requires session authentication for console access, so raw `ABRUN_TOKEN` API tokens are rejected for shell sessions.
128
+ Disks:
190
129
 
191
- Operationally the platform now has only two deploy pipelines:
130
+ ```sh
131
+ abrun app disk list <app>
132
+ abrun app disk create <app> <name> --size <gb>
133
+ abrun app disk mount <app> <disk> <mountPath>
134
+ abrun app disk unmount <app> <disk>
135
+ abrun app disk expand <app> <disk> --size <gb>
136
+ abrun app disk delete <app> <disk>
137
+ ```
192
138
 
193
- - `image`: release an existing image directly
194
- - `source`: build from managed source, then release the produced image
139
+ ## Databases
195
140
 
196
- CLI and Git deployments are both source-ingest paths into the same managed-source pipeline. The internal deployment `method` still records whether a source deployment came from `cli` or `git`, but builder and release behavior no longer diverge on that distinction.
141
+ Create and manage databases:
197
142
 
198
- ### Source Metadata
143
+ ```sh
144
+ abrun db create <name>
145
+ abrun dbs
146
+ abrun db inspect <database>
147
+ abrun db start <database>
148
+ abrun db stop <database>
149
+ abrun db logs <database> --follow
150
+ abrun db credentials <database> --show-password
151
+ abrun db delete <database>
152
+ ```
199
153
 
200
- For CLI deploys:
154
+ Open a local TCP tunnel to a database:
201
155
 
202
- - commit author and default commit message are derived from the local git repository when available
203
- - commit SHA, commit subject, author name, and author email are attached to source metadata when available
204
- - `--message` overrides the git-derived deployment message without dropping commit/author metadata
156
+ ```sh
157
+ abrun db tunnel <database> --port 5432
158
+ ```
205
159
 
206
- ### Cancel Behavior
160
+ Backups:
207
161
 
208
- - `Ctrl+C` before deployment creation aborts the local diff/upload flow
209
- - `Ctrl+C` after deployment creation requests deployment cancellation
210
- - uploaded source changes remain in the managed repo even if the later build/deploy is cancelled
162
+ ```sh
163
+ abrun db backup list <database>
164
+ abrun db backup create <database>
165
+ ```
211
166
 
212
- ## Local Context
167
+ ## Tokens
213
168
 
214
- Saved auth and project context are stored in:
169
+ Manage personal access tokens:
215
170
 
216
- ```text
217
- ~/.abrun/config.yaml
171
+ ```sh
172
+ abrun token list
173
+ abrun token create <name>
174
+ abrun token delete <token>
218
175
  ```
219
176
 
220
- The CLI keeps project selection locally and forwards the resolved project ID through the runtime client. Slugs are accepted only as selectors; API requests use `projectID`.
221
-
222
- ## Binary Plan
177
+ ## Output And Flags
223
178
 
224
- Recommended release shape:
179
+ Global flags:
225
180
 
226
- ```text
227
- abrun-darwin-arm64
228
- abrun-darwin-amd64
229
- abrun-linux-amd64
230
- abrun-linux-arm64
231
- checksums.txt
181
+ ```sh
182
+ abrun --endpoint <url> <command>
183
+ abrun --auth <auth> <command>
184
+ abrun --project <project> <command>
185
+ abrun --token <token> <command>
186
+ abrun --json <command>
187
+ abrun -o json <command>
188
+ abrun -o yaml <command>
232
189
  ```
233
190
 
234
- Recommended commands:
191
+ Saved CLI context lives at:
235
192
 
236
193
  ```text
237
- abrun version
238
- abrun upgrade --check
239
- abrun upgrade
194
+ ~/.abrun/config.yaml
240
195
  ```
241
196
 
242
- Recommended self-upgrade flow:
197
+ ## Help
243
198
 
244
- 1. detect current version and platform
245
- 2. fetch release manifest
246
- 3. compare versions
247
- 4. download the matching artifact to a temp file
248
- 5. verify checksum
249
- 6. atomically replace the current binary
250
- 7. keep one backup for rollback on failure
199
+ Every command has built-in help:
251
200
 
252
- The CLI should never silently auto-upgrade. It should only suggest or perform upgrades when the user explicitly asks.
201
+ ```sh
202
+ abrun --help
203
+ abrun app --help
204
+ abrun deploy --help
205
+ abrun db --help
206
+ ```
253
207
 
254
- ## Development
208
+ ## Package
255
209
 
256
- ```bash
257
- bun install
258
- cd ../.. && bun run generate:sdk
259
- bun run check
260
- bun run build
261
- ```
210
+ This package publishes the built Node.js runtime for the `abrun` command. TypeScript source, tests, source maps, and development configuration are not included in the npm tarball.