@revoengine/cli 1.0.10 → 1.0.13
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/README.md +314 -239
- package/dist/src/cli.js +126 -9
- package/dist/src/client.d.ts +373 -6
- package/dist/src/client.js +1005 -53
- package/dist/src/commands/auth.js +4 -2
- package/dist/src/commands/component.d.ts +67 -0
- package/dist/src/commands/component.js +555 -164
- package/dist/src/commands/database-tables.d.ts +2 -0
- package/dist/src/commands/database-tables.js +169 -0
- package/dist/src/commands/database-views.d.ts +2 -0
- package/dist/src/commands/database-views.js +126 -0
- package/dist/src/commands/endpoints.js +124 -0
- package/dist/src/commands/env.js +44 -24
- package/dist/src/commands/events.d.ts +2 -0
- package/dist/src/commands/events.js +144 -0
- package/dist/src/commands/groups.d.ts +2 -0
- package/dist/src/commands/groups.js +160 -0
- package/dist/src/commands/index.d.ts +9 -0
- package/dist/src/commands/index.js +9 -0
- package/dist/src/commands/job-templates.d.ts +2 -0
- package/dist/src/commands/job-templates.js +107 -0
- package/dist/src/commands/metadata.js +75 -10
- package/dist/src/commands/migrate.d.ts +6 -0
- package/dist/src/commands/migrate.js +658 -0
- package/dist/src/commands/project.js +10 -3
- package/dist/src/commands/role-groups.d.ts +2 -0
- package/dist/src/commands/role-groups.js +141 -0
- package/dist/src/commands/schedules.d.ts +2 -0
- package/dist/src/commands/schedules.js +140 -0
- package/dist/src/commands/terminal-browser.d.ts +16 -0
- package/dist/src/commands/terminal-browser.js +92 -0
- package/dist/src/commands/terminal-image.d.ts +7 -0
- package/dist/src/commands/terminal-image.js +40 -0
- package/dist/src/commands/terminal-patch-worker.d.ts +1 -0
- package/dist/src/commands/terminal-patch-worker.js +24 -0
- package/dist/src/commands/terminal-patch.d.ts +2 -0
- package/dist/src/commands/terminal-patch.js +156 -0
- package/dist/src/commands/terminal-sandbox.d.ts +8 -0
- package/dist/src/commands/terminal-sandbox.js +87 -0
- package/dist/src/commands/terminal-service.d.ts +38 -0
- package/dist/src/commands/terminal-service.js +210 -0
- package/dist/src/commands/terminal.d.ts +49 -0
- package/dist/src/commands/terminal.js +826 -0
- package/dist/src/component-lock.d.ts +111 -3
- package/dist/src/component-lock.js +363 -15
- package/dist/src/config.d.ts +10 -2
- package/dist/src/config.js +49 -14
- package/dist/src/database-table-artifacts.d.ts +7 -0
- package/dist/src/database-table-artifacts.js +8 -0
- package/dist/src/diff-details.d.ts +8 -0
- package/dist/src/diff-details.js +152 -0
- package/dist/src/env-sync.d.ts +0 -3
- package/dist/src/env-sync.js +11 -25
- package/dist/src/http-trace.d.ts +94 -0
- package/dist/src/http-trace.js +226 -0
- package/dist/src/metadata-backfill.d.ts +18 -7
- package/dist/src/metadata-backfill.js +1002 -27
- package/dist/src/migration.d.ts +141 -0
- package/dist/src/migration.js +1632 -0
- package/dist/src/project.d.ts +2 -0
- package/dist/src/project.js +4 -17
- package/dist/src/prompt.js +10 -18
- package/dist/src/resource-inventory.d.ts +28 -0
- package/dist/src/resource-inventory.js +85 -0
- package/dist/src/resource-metadata.d.ts +1 -0
- package/dist/src/resource-metadata.js +3 -0
- package/dist/src/resource-syncs/database-table-sync.d.ts +127 -0
- package/dist/src/resource-syncs/database-table-sync.js +2374 -0
- package/dist/src/resource-syncs/database-view-sync.d.ts +146 -0
- package/dist/src/resource-syncs/database-view-sync.js +1405 -0
- package/dist/src/resource-syncs/endpoint-sync.d.ts +123 -0
- package/dist/src/resource-syncs/endpoint-sync.js +1563 -0
- package/dist/src/resource-syncs/event-sync.d.ts +126 -0
- package/dist/src/resource-syncs/event-sync.js +1046 -0
- package/dist/src/resource-syncs/group-sync.d.ts +93 -0
- package/dist/src/resource-syncs/group-sync.js +928 -0
- package/dist/src/resource-syncs/job-template-sync.d.ts +106 -0
- package/dist/src/resource-syncs/job-template-sync.js +843 -0
- package/dist/src/resource-syncs/role-group-sync.d.ts +90 -0
- package/dist/src/resource-syncs/role-group-sync.js +635 -0
- package/dist/src/resource-syncs/schedule-sync.d.ts +140 -0
- package/dist/src/resource-syncs/schedule-sync.js +1396 -0
- package/dist/src/resource-syncs/util.d.ts +22 -0
- package/dist/src/resource-syncs/util.js +118 -0
- package/dist/src/resource-target.d.ts +11 -0
- package/dist/src/resource-target.js +48 -0
- package/dist/src/runtime-view.d.ts +1 -0
- package/dist/src/runtime-view.js +6 -1
- package/dist/src/sync-output.d.ts +66 -0
- package/dist/src/sync-output.js +268 -0
- package/dist/src/tracked-resources.d.ts +1 -1
- package/dist/src/tracked-resources.js +28 -2
- package/dist/src/types.d.ts +227 -0
- package/dist/src/ui.d.ts +3 -0
- package/dist/src/ui.js +76 -18
- package/dist/src/utils.d.ts +4 -0
- package/dist/src/utils.js +81 -0
- package/dist/src/workspace-component.d.ts +2 -0
- package/dist/src/workspace-component.js +34 -0
- package/dist/src/workspace-diff.d.ts +25 -0
- package/dist/src/workspace-diff.js +75 -0
- package/dist/src/workspace-resource.d.ts +2 -0
- package/dist/src/workspace-resource.js +52 -0
- package/package.json +12 -4
package/README.md
CHANGED
|
@@ -1,414 +1,489 @@
|
|
|
1
1
|
# @revoengine/cli
|
|
2
2
|
|
|
3
|
-
Official
|
|
3
|
+
Official command-line interface for moving RevoEngine configuration between an instance, a Git repository, and another instance.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
The CLI has three main capabilities:
|
|
6
6
|
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
7
|
+
1. **Repository workflow** — pull an instance into version-controlled files, review changes, and deploy the repository to a target instance.
|
|
8
|
+
2. **Project migration** — plan, run, and verify a direct migration between two saved projects with `--from` and `--to`.
|
|
9
|
+
3. **Resource synchronization** — work with one supported resource family through its dedicated `pull`, `plan`, and `push` commands.
|
|
10
10
|
|
|
11
|
-
|
|
11
|
+
## Requirements and installation
|
|
12
12
|
|
|
13
|
-
-
|
|
14
|
-
-
|
|
13
|
+
- Node.js 24 or newer
|
|
14
|
+
- A RevoEngine API key
|
|
15
15
|
|
|
16
|
-
|
|
16
|
+
```bash
|
|
17
|
+
npm install -g @revoengine/cli
|
|
18
|
+
```
|
|
17
19
|
|
|
18
|
-
|
|
20
|
+
The package installs `revo` and the compatibility alias `revoengine`. The examples below use `revo`.
|
|
19
21
|
|
|
20
22
|
```bash
|
|
23
|
+
revo --version
|
|
24
|
+
revo --help
|
|
21
25
|
revo -i
|
|
22
26
|
```
|
|
23
27
|
|
|
24
|
-
|
|
28
|
+
## Authentication and connection settings
|
|
29
|
+
|
|
30
|
+
Commands that access RevoEngine need an API URL and API key. The instance ID is normally inferred from the authenticated `/api/v1/me` response. Repository pull, diff, plan, deploy, and resource commands using the active connection explicitly reject a configured instance ID that differs from the authenticated instance.
|
|
31
|
+
|
|
32
|
+
### Stored login
|
|
33
|
+
|
|
34
|
+
Use a stored login for local interactive work:
|
|
25
35
|
|
|
26
36
|
```bash
|
|
27
37
|
revo auth login
|
|
38
|
+
revo auth status
|
|
39
|
+
revo auth logout
|
|
28
40
|
```
|
|
29
41
|
|
|
30
|
-
`
|
|
31
|
-
|
|
32
|
-
The CLI validates the API key against `/api/v1/me` and infers the RevoEngine instance from the authenticated profile for tenant-scoped operations such as component push.
|
|
42
|
+
`auth login` prompts for a masked API key, validates it, and saves the `default` connection in the operating system's config directory. To replace an existing login, log out first.
|
|
33
43
|
|
|
34
|
-
|
|
44
|
+
You can also provide the values without prompts:
|
|
35
45
|
|
|
36
46
|
```bash
|
|
37
|
-
revo auth
|
|
47
|
+
revo auth login \
|
|
48
|
+
--url https://api.revoengine.com \
|
|
49
|
+
--token "$SOURCE_REVO_TOKEN"
|
|
38
50
|
```
|
|
39
51
|
|
|
40
|
-
|
|
52
|
+
Stored configuration is located under `$XDG_CONFIG_HOME/revoengine` (or `~/.config/revoengine`) on macOS and Linux and `%APPDATA%/revoengine` on Windows. `config.json` holds the default login, named projects, and the active project; `auth-state.json` is a separate validation cache. Logging out removes the default login but preserves named projects.
|
|
53
|
+
|
|
54
|
+
### Saved projects
|
|
55
|
+
|
|
56
|
+
Save a connection and make it active for ordinary commands, including repository pull, plan, diff, and deploy:
|
|
41
57
|
|
|
42
58
|
```bash
|
|
43
|
-
revo
|
|
59
|
+
revo projects add source --url https://api.revoengine.com
|
|
60
|
+
revo projects list
|
|
61
|
+
revo projects set source
|
|
62
|
+
revo projects set default
|
|
63
|
+
revo projects remove source
|
|
44
64
|
```
|
|
45
65
|
|
|
46
|
-
|
|
66
|
+
Use `--project <name>` to select a saved connection for one command without changing the active project. The `default` project uses the original stored login and environment variable precedence. `revo env` and `--env` remain compatible aliases. Adding a project prompts for a masked API key unless `--token` is supplied.
|
|
67
|
+
|
|
68
|
+
### Agent terminal
|
|
69
|
+
|
|
70
|
+
Pair a local workspace with AI Agents → Terminals, approve its grant there, and run the terminal in the foreground:
|
|
47
71
|
|
|
48
72
|
```bash
|
|
49
|
-
revo --
|
|
73
|
+
revo terminal connect --workspace "$HOME/projects/my-project" --name "Work Mac"
|
|
74
|
+
revo terminal status
|
|
50
75
|
```
|
|
51
76
|
|
|
52
|
-
|
|
77
|
+
An approved terminal can run as a per-user background service on macOS or Linux. The service uses the active project at installation, or an explicit `--project <name>`; use the same project when uninstalling after a switch.
|
|
53
78
|
|
|
54
79
|
```bash
|
|
55
|
-
revo project
|
|
56
|
-
revo
|
|
57
|
-
revo
|
|
58
|
-
revo project init ./app --identity-mode componentId
|
|
59
|
-
revo project update ./app
|
|
80
|
+
revo terminal service install --workspace "$HOME/projects/my-project"
|
|
81
|
+
revo terminal service uninstall --workspace "$HOME/projects/my-project"
|
|
82
|
+
revo terminal disconnect --workspace "$HOME/projects/my-project"
|
|
60
83
|
```
|
|
61
84
|
|
|
62
|
-
|
|
85
|
+
The service starts at login, reconnects automatically, and pins the selected project profile at installation (or an explicit `--project <name>`). Install one service per workspace/profile; pass the same `--project` to uninstall after switching projects. Uninstall stops the service but keeps the terminal grant and local registration. `revo terminal disconnect --workspace <path>` revokes the grant and removes its local credential; uninstall the service first. On macOS, service logs are in `~/Library/Logs/RevoEngine/`. On Linux, inspect them with `journalctl --user -u <unit-name>`; `install` prints the unit name. Linux user services normally stop after logout unless an administrator enables user lingering.
|
|
63
86
|
|
|
64
|
-
|
|
87
|
+
The Agent terminal runs ordinary commands in a local workspace sandbox: writes are limited to the registered workspace and a private temporary directory, network access is blocked, and commands receive a private `HOME`. A reviewed `workspace-network` request enables network access while retaining workspace write boundaries. `unrestricted` removes the sandbox for a specific approved command. macOS uses Seatbelt; Linux requires `bwrap` (bubblewrap) installed for sandboxed execution. Missing sandbox support fails closed. Workspace patches and stdin for a running process are supported. The terminal's Sandbox/Full access grant is a separate ceiling from Composer's approval policy. A personal API key is required.
|
|
65
88
|
|
|
66
|
-
|
|
89
|
+
Browser actions use Playwright's Chromium headless shell. The CLI's npm install downloads only that browser into Playwright's per-user cache; a separate Chrome installation is not required. If npm scripts were disabled or the download was interrupted, reinstall the CLI with scripts enabled before using Browser. Linux hosts still need Playwright's system libraries; an administrator can install them with `npx playwright install-deps chromium`.
|
|
67
90
|
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
91
|
+
### Environment variables
|
|
92
|
+
|
|
93
|
+
Environment variables are the recommended authentication method for CI/CD:
|
|
94
|
+
|
|
95
|
+
```bash
|
|
96
|
+
export REVO_URL="https://api.revoengine.com"
|
|
97
|
+
export REVO_TOKEN="$SOURCE_REVO_TOKEN"
|
|
98
|
+
|
|
99
|
+
revo -i
|
|
100
|
+
revo diff
|
|
75
101
|
```
|
|
76
102
|
|
|
77
|
-
|
|
103
|
+
Supported variables:
|
|
104
|
+
|
|
105
|
+
| Purpose | Preferred name | Compatible aliases |
|
|
106
|
+
| --- | --- | --- |
|
|
107
|
+
| API URL | `REVO_URL` | `REVO_BASE_URL`, `REVOENGINE_URL`, `REVOENGINE_BASE_URL` |
|
|
108
|
+
| Instance ID | `REVO_INSTANCE` | `REVOENGINE_INSTANCE` |
|
|
109
|
+
| API key | `REVO_TOKEN` | `REVO_API_KEY`, `REVOENGINE_TOKEN`, `REVOENGINE_API_KEY` |
|
|
110
|
+
| Disable update checks | `REVO_NO_UPDATE_NOTIFIER` | `NO_UPDATE_NOTIFIER` |
|
|
78
111
|
|
|
79
|
-
|
|
112
|
+
### Command-line flags
|
|
80
113
|
|
|
81
|
-
|
|
114
|
+
Flags are useful for one-off commands and override all other runtime configuration:
|
|
82
115
|
|
|
83
116
|
```bash
|
|
84
|
-
revo
|
|
85
|
-
|
|
117
|
+
revo \
|
|
118
|
+
--url https://api.revoengine.com \
|
|
119
|
+
--instance "$REVO_INSTANCE_ID" \
|
|
120
|
+
--token "$REVO_API_TOKEN" \
|
|
121
|
+
pull --all --yes
|
|
86
122
|
```
|
|
87
123
|
|
|
88
|
-
|
|
124
|
+
Global connection flags:
|
|
125
|
+
|
|
126
|
+
- `--project <name>` (or the compatible `--env <name>`)
|
|
127
|
+
- `--url <url>` or `--baseUrl <url>`
|
|
128
|
+
- `--instance <uuid>`
|
|
129
|
+
- `--token <apiKey>`
|
|
130
|
+
|
|
131
|
+
Avoid putting tokens directly in shell history. Prefer environment variables for automation.
|
|
132
|
+
|
|
133
|
+
### Cross-environment migration
|
|
89
134
|
|
|
90
|
-
|
|
135
|
+
Saved projects are required by `revo migrate --from/--to` and are also accepted through `--project` or the compatible `--env` alias. Examples use `source` and `target` for migration roles. Both may use the production API URL shown below, with separate API keys for their respective instances; the profile name itself does not select an API or set the production flag.
|
|
91
136
|
|
|
92
137
|
```bash
|
|
93
|
-
revo
|
|
94
|
-
revo
|
|
95
|
-
revo
|
|
96
|
-
revo search SIMPLE customer
|
|
97
|
-
revo request GET /api/component/list
|
|
98
|
-
revo request POST /api/component "{\"name\":\"Customer Card\"}"
|
|
138
|
+
revo projects add source --url https://api.revoengine.com
|
|
139
|
+
revo projects add target --url https://api.revoengine.com
|
|
140
|
+
revo projects list
|
|
99
141
|
```
|
|
100
142
|
|
|
101
|
-
`revo
|
|
143
|
+
`projects add` prompts for an API key, validates the profile, and asks whether the project is production. Use `--token <apiKey>` to supply the key directly or `--offline` to skip validation. For an explicitly named production profile, run `revo projects add prod --url https://api.revoengine.com` and answer yes to the production prompt. There is no `--production` flag. Remove an unused profile with `revo projects remove <name>`.
|
|
102
144
|
|
|
103
|
-
-
|
|
104
|
-
- `SIMPLE` searches everything.
|
|
145
|
+
A production profile requires an interactive confirmation before the first remote write in every invocation. `--yes`, `--force`, and non-interactive CI do not bypass this guard.
|
|
105
146
|
|
|
106
|
-
|
|
147
|
+
Runtime configuration precedence is:
|
|
107
148
|
|
|
108
|
-
|
|
149
|
+
1. command-line flags;
|
|
150
|
+
2. a selected named profile;
|
|
151
|
+
3. environment variables;
|
|
152
|
+
4. the stored default login;
|
|
153
|
+
5. `https://api.revoengine.com` as the default URL.
|
|
109
154
|
|
|
110
|
-
|
|
155
|
+
A named profile is isolated: it never inherits a URL, instance, or token from environment variables or the default login. The special profile name `default` uses the normal flag → environment variable → stored login chain, but full `revo migrate` commands require two real named profiles.
|
|
111
156
|
|
|
112
|
-
|
|
113
|
-
revo component pull 6dfb536a-1111-4222-8333-123456789abc
|
|
114
|
-
revo component pull 6dfb536a-1111-4222-8333-123456789abc 7afc7b98-4444-4555-8666-abcdefabcdef
|
|
115
|
-
```
|
|
157
|
+
## Project setup and portable identity
|
|
116
158
|
|
|
117
|
-
|
|
159
|
+
Initialize a repository before using repository deployment or full migrations:
|
|
118
160
|
|
|
119
161
|
```bash
|
|
120
|
-
revo
|
|
121
|
-
|
|
122
|
-
|
|
162
|
+
revo project init . \
|
|
163
|
+
--identity-mode stableKey \
|
|
164
|
+
--stable-key-name stableKey \
|
|
165
|
+
--resources all
|
|
123
166
|
```
|
|
124
167
|
|
|
125
|
-
|
|
168
|
+
Initialization authenticates and downloads editor types from the instance's sandbox endpoint. It creates or updates:
|
|
126
169
|
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
170
|
+
- `.revoengine/revo.json` — project settings, workspace path, identity mode, and tracked resources;
|
|
171
|
+
- `.revoengine/types/` — generated editor types;
|
|
172
|
+
- editor configuration, Git ignore entries, and local debug scaffolding.
|
|
173
|
+
|
|
174
|
+
Subsequent resource synchronization creates `.revoengine/revo.lock.json` baselines and directories such as `Components/`, `DatabaseTables/`, and `Endpoints/` in the configured workspace. With Stable Key identity, `project init` also backfills metadata for selected resource families except Database Tables; their keys require an explicit `metadata plan/apply` review.
|
|
175
|
+
|
|
176
|
+
Use `revo project update` to refresh an existing project. When the RevoEngine workspace is nested, pass its path, for example `revo project init ./backend`.
|
|
132
177
|
|
|
133
|
-
|
|
178
|
+
Stable Keys are the durable identity used across instances. UUIDs and versions remain instance-local and are not used to match portable resources. Before the first migration, inspect and apply missing keys on the source:
|
|
134
179
|
|
|
135
180
|
```bash
|
|
136
|
-
revo
|
|
137
|
-
revo
|
|
138
|
-
revo component push --all --yes
|
|
139
|
-
revo component push --all --force
|
|
181
|
+
revo metadata plan --project source --json
|
|
182
|
+
revo metadata apply --project source --yes
|
|
140
183
|
```
|
|
141
184
|
|
|
142
|
-
|
|
185
|
+
You can limit the operation:
|
|
143
186
|
|
|
144
187
|
```bash
|
|
145
|
-
revo
|
|
146
|
-
revo
|
|
147
|
-
revo component debug 6dfb536a-1111-4222-8333-123456789abc --timeout 30 --memory 256
|
|
148
|
-
revo component debug 6dfb536a-1111-4222-8333-123456789abc --stream
|
|
188
|
+
revo metadata plan --project source --resources component,endpoint
|
|
189
|
+
revo metadata apply --project source --resources component,endpoint --yes
|
|
149
190
|
```
|
|
150
191
|
|
|
151
|
-
|
|
192
|
+
Existing resources on another instance must use the exact same Stable Key as their source counterpart. Missing keys are treated as unmanaged; duplicate or ambiguous keys block writes. Database Table and Database View metadata changes deserve an explicit review because their backend update contracts are broader than ordinary metadata-only writes.
|
|
193
|
+
|
|
194
|
+
Use `--no-metadata-backfill` with `project init` when initialization must not write remote metadata.
|
|
195
|
+
|
|
196
|
+
## 1. Repository workflow
|
|
197
|
+
|
|
198
|
+
Use this workflow when a Git repository is the reviewed source of truth.
|
|
152
199
|
|
|
153
200
|
```text
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
2_logic.ts
|
|
161
|
-
```
|
|
162
|
-
|
|
163
|
-
Each component folder keeps its `component.json` manifest alongside an `elements/` directory with the source payload for every element.
|
|
164
|
-
Components with `category: null` are stored under `Components/__no_category__/...` while the manifest keeps `"category": null`.
|
|
165
|
-
|
|
166
|
-
Remote sync state is stored separately in `.revoengine/revo.lock.json`. Lock schema v2 records the configured identity strategy and, in stable-key mode, keys each entry by the configured metadata value while retaining both the repository-local and current remote UUID. The lock records the last remote component hash/version that this workspace was pulled from or successfully pushed to. It is a baseline, not the deployed source of truth; the server remains authoritative for deployed state and local component files remain the desired source.
|
|
167
|
-
|
|
168
|
-
Bulk sync behavior:
|
|
169
|
-
|
|
170
|
-
- `revo component pull --all` and `revo component push --all` require terminal confirmation unless `--yes` or `--force` is passed.
|
|
171
|
-
- `--yes` only confirms the bulk operation. `--force` bypasses lock-content safety, but never bypasses stable-key ownership: missing or duplicate configured identities are still blocked or ignored.
|
|
172
|
-
- `revo component pull --all` requests only active remote components where `deletedAt` is empty.
|
|
173
|
-
- Pull compares local files, `.revoengine/revo.lock.json`, and the current remote component before overwriting anything.
|
|
174
|
-
- Pull fast-forwards clean local files when the remote moved and the local copy still matches the lock.
|
|
175
|
-
- Pull rejects conflicts when both local files and the remote changed since the lock baseline.
|
|
176
|
-
- Pull writes stable source manifests and keeps remote version churn out of `Components/**/component.json`.
|
|
177
|
-
- `revo component plan --all --strict` exits with an error when conflicts or missing lock entries are present.
|
|
178
|
-
- Push checks the current remote component against the lock before saving local changes.
|
|
179
|
-
- In stable-key mode, push resolves the target remote UUID from metadata and remaps element IDs by element key before saving. Source-instance UUIDs are never sent as target identity.
|
|
180
|
-
- Push rejects stale remote state instead of trusting the version inside local component JSON.
|
|
181
|
-
- Push treats backend `Not modified` responses as skipped instead of failing the whole run.
|
|
182
|
-
- Push treats backend `404` responses as skipped with `doesn't exist remotely`; restore the component in RevoEngine before pushing local changes to it.
|
|
183
|
-
- Debug posts the local `component.json` plus `elements/{order}_{key}.{js|ts}` source files to the authenticated sandbox `debug` endpoint.
|
|
184
|
-
- `revo component debug --stream` posts to `debug/stream`, writes live `api.log()` frames to stderr, and writes the final raw result payload to stdout.
|
|
185
|
-
- Debug responses are saved under `.revoengine/output/debug_<timestamp>.json`.
|
|
186
|
-
- Debug includes local `CODE_TS_LIB` and `CODE_JS_LIB` components as temporary `extraLibs` overrides by default. Use `--no-extra-libs` when you want backend-saved libraries only.
|
|
187
|
-
- Sync logs show direction explicitly: `RevoEngine -> path` for pull and `RevoEngine <- path` for push.
|
|
188
|
-
- Bulk runs print a summary such as `Deployed 54/67, Skipped 13/67 in 13s`.
|
|
189
|
-
|
|
190
|
-
## Environments
|
|
191
|
-
|
|
192
|
-
Save named environment profiles once, then compare and mirror components between environments terraform-style:
|
|
201
|
+
RevoEngine source -> revo pull -> repository -> revo diff -> revo plan -> revo deploy -> RevoEngine target
|
|
202
|
+
```
|
|
203
|
+
|
|
204
|
+
### Pull source state into the repository
|
|
205
|
+
|
|
206
|
+
Authenticate to the source through flags, environment variables, or the stored login, then pull all resources:
|
|
193
207
|
|
|
194
208
|
```bash
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
revo env list
|
|
198
|
-
revo env remove e2e
|
|
199
|
-
```
|
|
209
|
+
export REVO_URL="https://api.revoengine.com"
|
|
210
|
+
export REVO_TOKEN="$SOURCE_REVO_TOKEN"
|
|
200
211
|
|
|
201
|
-
|
|
212
|
+
revo pull --all --yes
|
|
213
|
+
```
|
|
202
214
|
|
|
203
|
-
|
|
215
|
+
Or pull only selected resource families:
|
|
204
216
|
|
|
205
217
|
```bash
|
|
206
|
-
revo
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
revo env diff --from develop --to e2e --prune # classify target-only components as deletes
|
|
210
|
-
revo env diff --from develop --to e2e --key Forms/Card --category Shared
|
|
218
|
+
revo pull \
|
|
219
|
+
--resources database-table,database-view,component,job-template,endpoint \
|
|
220
|
+
--yes
|
|
211
221
|
```
|
|
212
222
|
|
|
213
|
-
|
|
223
|
+
`pull` requires either `--all` or `--resources`. It writes resources in dependency order and records the source baseline under the authenticated instance ID. Add `--skip-groups` to omit Group and Role Group resources from the selected scope.
|
|
214
224
|
|
|
215
|
-
|
|
225
|
+
A normal pull protects locally changed files and does not remove source-deleted manifests. After review, `pull --force` replaces managed resource directories and prunes managed manifests that no longer exist on the source. Keep hand-written files outside generated resource directories.
|
|
216
226
|
|
|
217
|
-
|
|
227
|
+
### Review and deploy the repository
|
|
228
|
+
|
|
229
|
+
Commit and review the generated files. Then authenticate to the target:
|
|
218
230
|
|
|
219
231
|
```bash
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
revo
|
|
232
|
+
export REVO_URL="https://api.revoengine.com"
|
|
233
|
+
export REVO_TOKEN="$TARGET_REVO_TOKEN"
|
|
234
|
+
|
|
235
|
+
revo diff
|
|
236
|
+
revo plan
|
|
237
|
+
revo deploy --yes
|
|
224
238
|
```
|
|
225
239
|
|
|
226
|
-
|
|
240
|
+
`diff` and `plan` compare the local repository workspace to the active target without changing resource files, baselines, or target resources. Authentication caching and enabled HTTP tracing may still write local diagnostic files. `diff` shows content differences, including unified line diffs for Component source and RAW_SQL queries. It omits warnings, blockers, unchanged resources, and readiness checks, so success does not mean deployment is safe or the target is converged. It rejects `--force`; use `plan --force` to review gated operations.
|
|
227
241
|
|
|
228
|
-
|
|
229
|
-
- `--yes` only confirms the bulk apply. Deletes additionally require `--force` (non-interactive) or a second dedicated confirmation (interactive), matching the component sync semantics.
|
|
230
|
-
- Deletes only happen with `--prune`; without it, target-only components are reported as `orphan` and left alone.
|
|
231
|
-
- Element identity is preserved on update: source elements are matched to the target's elements by key, so the target keeps its own element ids.
|
|
232
|
-
- After every create/update the CLI re-fetches the target component and verifies its content hash against the source; mismatches are flagged as `verification mismatch`.
|
|
242
|
+
`plan` reports ordered create, update, adopt, excluded, and blocked operations with warnings and a readiness verdict; it exits unsuccessfully on blockers. `--hints` adds informational details. Sensitive fields in change details are redacted. `diff --json` returns a content-diff report, while `plan --json` returns the full deployment plan. `deploy` recomputes the live plan, applies resources in dependency order, and verifies writes by reading them back.
|
|
233
243
|
|
|
234
|
-
|
|
244
|
+
The target can also come from a saved project (`revo plan --project target`), a stored login, or explicit CI credentials:
|
|
235
245
|
|
|
236
|
-
|
|
246
|
+
```bash
|
|
247
|
+
revo --url "$REVO_API_URL" --instance "$REVO_INSTANCE_ID" --token "$REVO_API_TOKEN" plan --json
|
|
248
|
+
```
|
|
249
|
+
|
|
250
|
+
`plan --strict` exits unsuccessfully when create or update operations are pending. Omit `--strict` in a CI pre-deployment job that is expected to approve deployable changes. The repository plan always evaluates all tracked resource families and their dependencies; `--changed --base` remains specific to `component plan`.
|
|
237
251
|
|
|
238
|
-
|
|
252
|
+
The deployment scope comes from `.revoengine/revo.json.trackedResources`:
|
|
239
253
|
|
|
240
254
|
```bash
|
|
241
|
-
revo project
|
|
255
|
+
revo project update \
|
|
256
|
+
--resources database-table,database-view,component,job-template,endpoint,schedule,event
|
|
242
257
|
```
|
|
243
258
|
|
|
244
|
-
For CI
|
|
259
|
+
For CI output, use JSON:
|
|
245
260
|
|
|
246
261
|
```bash
|
|
247
|
-
revo
|
|
262
|
+
revo diff --json
|
|
263
|
+
revo plan --json
|
|
264
|
+
revo deploy --yes --json
|
|
248
265
|
```
|
|
249
266
|
|
|
250
|
-
|
|
267
|
+
Repository deployment uses desired-source-wins upsert: it can adopt a missing baseline or overwrite target content drift with the repository state. Its Database Table policy permits supported table renames, column additions and changes, and copying foreign-reference declarations as metadata. Copying those declarations does not create physical SQL foreign-key constraints.
|
|
268
|
+
|
|
269
|
+
`deploy --force` additionally approves supported high-impact operations reported by `plan`, including column removal, managed partition deletion, Materialized View Schedule writes, Schedule target-type changes, and Group or Role Group writes. Review them with `revo plan --force` before deployment. Force does not bypass invalid identity, missing dependencies, unsupported DDL, ambiguity, or failed verification. Root-table orphan deletion is available only through the dedicated table push.
|
|
251
270
|
|
|
252
|
-
|
|
253
|
-
- `componentIdentity.metadataProperty`: the component metadata property used in stable-key mode. Default: `stableKey`.
|
|
254
|
-
- `trackedResources`: resource families the CLI should track. Default: `all`; this CLI currently tracks components.
|
|
271
|
+
To remove target Components that no longer have local manifests, review `revo component plan --all --prune` and run `revo component push --all --prune --yes --force`. Prune matches target Components by the configured identity (Stable Key when enabled), even when their instance UUID or content differs from an old lock baseline. Components without that identity remain unmanaged. Before deletion, the CLI rechecks that no local manifest appeared and that the live target still matches the freshly computed plan; it verifies removal from the active catalog before clearing any selected lock baseline. `component plan --all --strict` reports drift but never deletes resources.
|
|
255
272
|
|
|
256
|
-
2.
|
|
273
|
+
## 2. Project-to-project migration
|
|
274
|
+
|
|
275
|
+
Use this workflow for a direct migration between two saved projects. It does not require committing the source snapshot to the repository.
|
|
257
276
|
|
|
258
277
|
```bash
|
|
259
|
-
revo
|
|
260
|
-
revo
|
|
261
|
-
revo env list
|
|
278
|
+
revo projects add source --url https://api.revoengine.com
|
|
279
|
+
revo projects add target --url https://api.revoengine.com
|
|
262
280
|
```
|
|
263
281
|
|
|
264
|
-
|
|
282
|
+
Plan, run, and verify the migration:
|
|
265
283
|
|
|
266
284
|
```bash
|
|
267
|
-
|
|
285
|
+
revo migrate plan --from source --to target
|
|
286
|
+
revo migrate run --from source --to target --yes
|
|
287
|
+
revo migrate verify --from source --to target
|
|
268
288
|
```
|
|
269
289
|
|
|
270
|
-
|
|
290
|
+
- `plan` pulls a fresh source snapshot into a temporary project and compares it with the live target, leaving the real workspace and lock unchanged. `migrate run --dry-run` follows this same read-only flow.
|
|
291
|
+
- `run` force-pulls the selected source families into the configured workspace, replacing managed local files and pruning source-deleted local manifests, then performs plan → ordered writes → readback verification. Preserve intended local edits before running it.
|
|
292
|
+
- `verify` pulls the source again into a temporary project and fails on blockers or remaining changes.
|
|
293
|
+
|
|
294
|
+
Select a subset with a comma-separated or repeated `--resources` flag:
|
|
271
295
|
|
|
272
296
|
```bash
|
|
273
|
-
revo
|
|
274
|
-
|
|
297
|
+
revo migrate plan \
|
|
298
|
+
--from source \
|
|
299
|
+
--to target \
|
|
300
|
+
--resources component,job-template,endpoint \
|
|
301
|
+
--json
|
|
302
|
+
|
|
303
|
+
revo migrate run \
|
|
304
|
+
--from source \
|
|
305
|
+
--to target \
|
|
306
|
+
--resources database-table \
|
|
307
|
+
--yes \
|
|
308
|
+
--force
|
|
275
309
|
```
|
|
276
310
|
|
|
277
|
-
Use
|
|
311
|
+
Use `--skip-groups` to omit both `group` and `role-group`:
|
|
278
312
|
|
|
279
313
|
```bash
|
|
280
|
-
revo
|
|
314
|
+
revo migrate plan --from source --to target --skip-groups
|
|
315
|
+
revo migrate run --from source --to target --skip-groups --yes
|
|
281
316
|
```
|
|
282
317
|
|
|
283
|
-
|
|
318
|
+
The migration model is source-wins upsert. Missing target resources are created and changed resources are updated. Target-only resources are reported as exclusions and are not deleted. A failed phase prevents all later phases from writing; earlier verified writes are not rolled back. Named migration includes Materialized View and access-group writes in its selected scope without the additional repository force gates; destructive column removal still requires `--force`. Production-profile confirmation still applies.
|
|
319
|
+
|
|
320
|
+
Plans project earlier phase results into later dependencies: a Schedule can plan against a Job Template or Materialized View that an earlier phase will create. After each phase verifies its writes, the next phase resolves the actual target UUIDs and versions again before writing. A failed readback stops subsequent phases; `verify` uses a fresh source pull to detect remaining changes.
|
|
321
|
+
|
|
322
|
+
`revo env diff/apply` is a separate, component-only synchronization command retained for focused component mirroring. Use `revo migrate` for the complete multi-resource workflow.
|
|
323
|
+
|
|
324
|
+
## 3. Supported resources
|
|
325
|
+
|
|
326
|
+
Full pull, deployment, and migration use this fixed dependency order:
|
|
327
|
+
|
|
328
|
+
| Order | Resource selector | Dedicated command | Workspace directory | Important behavior |
|
|
329
|
+
| ---: | --- | --- | --- | --- |
|
|
330
|
+
| 1 | `database-table` | `database-tables` | `DatabaseTables/` | Tables, columns, and partitions; destructive DDL remains guarded. |
|
|
331
|
+
| 2 | `database-view` | `database-views` | `DatabaseViews/` | STRUCTURED and RAW_SQL views, including materialized views; target schemas must be ready first. |
|
|
332
|
+
| 3 | `component` | `component` | `Components/` | Portable code, libraries, and elements. Libraries are deployed before executable components. |
|
|
333
|
+
| 4 | `job-template` | `job-templates` | `JobTemplates/` | Resolves Component dependencies by Stable Key. Pull skips WIP templates without a Stable Key or with an unkeyed Component and reports each skip. |
|
|
334
|
+
| 5 | `endpoint` | `endpoints` | `Endpoints/` | Resolves Component dependencies and route ordering. |
|
|
335
|
+
| 6 | `schedule` | `schedules` | `Schedules/` | Targets Job Templates or Materialized Views. New schedules are inactive by default. |
|
|
336
|
+
| 7 | `event` | `events` | `Events/` | Supports Job Template event targets. Manifests retain `custom: true/false` alongside `type`; new events are inactive by default. |
|
|
337
|
+
| 8 | `group` | `groups` | `Groups/` | Group owners use Stable Keys; users and memberships remain target-local. |
|
|
338
|
+
| 9 | `role-group` | `role-groups` | `RoleGroups/` | Role assignments run last; members and user identifiers remain target-local. |
|
|
339
|
+
|
|
340
|
+
`--resources all` selects all nine families. Singular, plural, and common compact aliases are accepted where the command parser documents them, but the selectors above are the canonical values.
|
|
341
|
+
|
|
342
|
+
Existing `database-schema` selectors and `revo database-schemas` commands remain accepted as compatibility aliases. New table manifests use `DatabaseTables/**/database-table.json`; older `DatabaseSchemas/**/database-schema.json` files remain readable and are relocated by the next successful table pull. A locally edited manifest still needs `--force` before pull replaces it. The manifest `kind` and `databaseSchemas` lock and plan keys retain their existing schema names for format compatibility.
|
|
343
|
+
|
|
344
|
+
Older Event manifests without `custom` must be refreshed with `revo events pull` from the source environment or edited to set `custom` explicitly. The pull upgrades an unchanged, locked manifest without `--force`. Check the `type` too: a legacy `CUSTOM_EXPORT` event now uses `type: "EXPORT", custom: true` when that is the source definition. An Event plan blocks manifests with no `custom` classifier.
|
|
345
|
+
|
|
346
|
+
### Work with one resource family
|
|
347
|
+
|
|
348
|
+
Every resource family has a dedicated synchronization flow. With a stored login or `REVO_URL` and `REVO_TOKEN`, omit `--project` to use the active connection:
|
|
284
349
|
|
|
285
350
|
```bash
|
|
286
|
-
revo
|
|
287
|
-
|
|
351
|
+
revo database-tables pull --all
|
|
352
|
+
# Edit a file in the configured workspace.
|
|
353
|
+
revo database-tables plan --all
|
|
354
|
+
revo database-tables push --all --yes
|
|
288
355
|
```
|
|
289
356
|
|
|
290
|
-
|
|
357
|
+
For resource families other than legacy component sync, the active connection's baseline is stored under its authenticated instance ID. Switching the active login therefore does not reuse another instance's baseline. `pull` protects local edits; use `--force` only after reviewing the replacement. Run commands from the repository containing `.revoengine/revo.json`.
|
|
291
358
|
|
|
292
|
-
|
|
359
|
+
When migrating Schedules after Database Views, review the plan and use this full push with the active login (no `--project`):
|
|
293
360
|
|
|
294
361
|
```bash
|
|
295
|
-
revo
|
|
296
|
-
revo
|
|
362
|
+
revo schedules plan --all
|
|
363
|
+
revo schedules push --all --yes --force
|
|
297
364
|
```
|
|
298
365
|
|
|
299
|
-
|
|
366
|
+
`--force` permits adopting a missing Schedule baseline or overwriting reviewed target drift. It also approves a reviewed transition between Job Template and Materialized View targets under one Schedule Stable Key. Materialized View refresh Schedules are included with the other Schedules and identify their Database View by Stable Key and refresh mode, never by a source UUID. User-managed `JOB_TEMPLATE` and `PLATFORM_OPERATION` schedules of kind `refresh_materialized_view` are supported. Other platform operations, `AGENT`, and system-managed Schedules are excluded; `--strict` treats exclusions as incomplete coverage.
|
|
300
367
|
|
|
301
|
-
|
|
302
|
-
Plan: 0 to update, N already populated.
|
|
303
|
-
```
|
|
368
|
+
Pull initializes each Schedule's editable activation candidate from the source. A new target Schedule is created inactive, while a configuration update preserves its target activation state. `schedules push --all --yes --activate` activates only candidates created or updated and verified during that push; unchanged Schedules are not activated. Interactive activation asks for a second confirmation. Repository `deploy` and named `migrate` leave this activation step to the dedicated command.
|
|
304
369
|
|
|
305
|
-
|
|
370
|
+
Use `--project` to select a saved project explicitly (`--env` remains a compatible alias):
|
|
306
371
|
|
|
307
372
|
```bash
|
|
308
|
-
revo
|
|
309
|
-
revo
|
|
373
|
+
revo <command> pull --all --project source
|
|
374
|
+
revo <command> plan --all --project target
|
|
375
|
+
revo <command> push --all --project target --yes
|
|
310
376
|
```
|
|
311
377
|
|
|
312
|
-
|
|
378
|
+
For example:
|
|
313
379
|
|
|
314
380
|
```bash
|
|
315
|
-
revo
|
|
381
|
+
revo endpoints pull --all --project source
|
|
382
|
+
revo endpoints plan --all --project target --json
|
|
383
|
+
revo endpoints push --all --project target --yes
|
|
316
384
|
```
|
|
317
385
|
|
|
318
|
-
|
|
386
|
+
Database Table and Database View pushes can also select one Stable Key:
|
|
319
387
|
|
|
320
388
|
```bash
|
|
321
|
-
revo
|
|
322
|
-
revo
|
|
389
|
+
revo database-tables push 'Sales/Orders#1234abcd' --project target --yes
|
|
390
|
+
revo database-views push 'Sales/Revenue#1234abcd' --project target --yes
|
|
323
391
|
```
|
|
324
392
|
|
|
325
|
-
|
|
393
|
+
Database View plans show a line diff for changed RAW_SQL queries, including unchanged context and red/green removed and added lines in color terminals.
|
|
326
394
|
|
|
327
|
-
|
|
395
|
+
Preview failures use `validation-failed`, preserve the definition diff, and show the backend message, HTTP status, definition mode, and timeout information. RAW_SQL failures also suggest checking whether the instance enables RAW SQL Database Views. They block deployment of the affected view even with `--force`; `database-views push` continues with independent views but exits unsuccessfully if validation failed. An unchanged view skips planning preview only when its target hash and source-table dependency fingerprint match the environment lock; old locks still require preview. Pull and verified push update this fingerprint, while plan remains fileless. Creates and updates always revalidate immediately before writing.
|
|
328
396
|
|
|
329
|
-
|
|
330
|
-
revo env diff --from test --to dev --prune
|
|
331
|
-
revo env apply --from test --to dev --prune --dry-run
|
|
332
|
-
revo env apply --from test --to dev --prune --yes --force
|
|
333
|
-
```
|
|
397
|
+
RAW_SQL validation sends `take: 0` without an `output` overlay, using the backend's `LIMIT 0` path. STRUCTURED validation sends `take: 1` and `output: { take: 1, count: false }` so the current backend limits returned rows. Queries that aggregate or sort large source sets can still be expensive; true schema-only validation requires a backend change. Each preview has a 30-second request timeout and is not retried.
|
|
334
398
|
|
|
335
|
-
|
|
399
|
+
### Database Table identity, DDL, and target-local policy
|
|
336
400
|
|
|
337
|
-
|
|
401
|
+
Table Stable Keys match resources across instances; a table name is the physical SQL name. Dedicated `database-tables plan/push` leaves table renames and column removals for manual handling, even with `--force`. Repository `plan/deploy` and named `migrate` use a broader source-wins policy: they can rename tables and apply supported column changes, while column removal requires `--force`. Table kind, partition parent or bounds, unsupported array changes, and ambiguous identities remain blocked. Every accepted write needs portable readback verification before its lock baseline advances.
|
|
338
402
|
|
|
339
|
-
|
|
403
|
+
Root-table columns can carry unique, non-empty Stable Keys in `definition[].metadata.<stable-key-name>`. `metadata plan/apply` can backfill missing root-column keys; partitions inherit the root definition. Existing column keys are immutable even with `--force`, and malformed or duplicate keys block backfill. A shared key matches columns before exact-name fallback, and writes attach the live target column ID. Source column IDs and reserved `__*` metadata never become portable column identity.
|
|
340
404
|
|
|
341
|
-
|
|
342
|
-
2. A named environment profile when a command is invoked with `--from`/`--to` (profiles resolve exclusively and are not mixed with environment variables or the stored default login)
|
|
343
|
-
3. Environment variables such as `REVO_URL` and `REVO_TOKEN`
|
|
344
|
-
4. Stored config in the OS config directory
|
|
405
|
+
Dedicated push allows reviewed key-matched changes to existing columns, including name, type, default, nullability, array, primary-key, unique, and index fields. These operations can scan, lock, rewrite, or validate live data. Exact-name matching remains a fallback for safe presentation changes and an ordinary nullable column addition; it never guesses a rename. A required, defaulted, indexed, unique, or primary-key addition needs a unique column Stable Key. Structural changes to an existing unkeyed column and unkeyed operational additions remain manual. Active Database Views block dependent column renames, removals, type changes, and array changes at plan time and again before the write.
|
|
345
406
|
|
|
346
|
-
|
|
407
|
+
Database Table manifests own the complete non-reserved user metadata object. Push replaces target user metadata with the manifest's object, including deliberate key removals, while platform-reserved `__*` fields remain server-owned. Audit history and the source `audit` setting are target-local: updates preserve the target audit setting and new tables start with audit disabled.
|
|
347
408
|
|
|
348
|
-
|
|
409
|
+
Access control is also target-local. Pull records a root table's source `restricted` flag as `sourceRestricted` in the shared lock, outside its portable manifest and hash. New roots use that flag but copy no source ACL user or group IDs; existing target access is preserved on update, and partitions inherit the target parent's policy. Assign target principals separately. Dedicated push blocks creation when an older lock lacks the restriction snapshot; pull again to capture it. Orchestrated deployment permits that create and defaults an unknown restriction to false, so preserve the lock alongside manifests when source restriction matters.
|
|
349
410
|
|
|
350
|
-
|
|
351
|
-
revo --url https://api.test.revong.com -i
|
|
352
|
-
revo --url https://api.test.revong.com auth login
|
|
353
|
-
revo --url https://api.revoengine.com endpoints
|
|
354
|
-
```
|
|
411
|
+
Non-empty `foreignReferences` remain visible in manifests. Dedicated push classifies a create or change carrying them as a manual schema migration, even with `--force`; an identical target can remain clean. Repository deploy and named migrate can copy the declarations with a warning, but the backend does not create physical SQL foreign-key constraints. Verify and apply physical constraints separately when required.
|
|
355
412
|
|
|
356
|
-
|
|
413
|
+
### Database Table partitions and deletion
|
|
357
414
|
|
|
358
|
-
|
|
359
|
-
# TEST
|
|
360
|
-
export REVO_URL="https://api.test.revong.com"
|
|
361
|
-
export REVO_TOKEN="your-test-token"
|
|
362
|
-
revo endpoints
|
|
415
|
+
Review `database-tables plan --all` before a destructive push. `database-tables plan --all --skip-partitions` is a root-only report: it excludes local and remote partitions even under `--strict`. Pull and push still include managed partitions, so use a full plan before partition work. A changed range, value set, or hash bound creates a replacement partition with a new Stable Key. Restoring the same physical partition keeps its key. Replacement takes two verified pushes: remove the old key, then create the new one. The CLI does not attempt an overlapping delete and create in one push or reuse a key still owned by a recoverable deleted target.
|
|
363
416
|
|
|
364
|
-
|
|
365
|
-
export REVO_URL="https://api.revoengine.com"
|
|
366
|
-
export REVO_TOKEN="your-prod-token"
|
|
367
|
-
revo endpoints
|
|
368
|
-
```
|
|
417
|
+
`database-tables push --all --prune-partitions --yes --force` removes only previously managed partitions whose local manifests were removed. It deletes from leaves to root, refuses to remove a parent with an active child, and records a tombstone in the selected environment's lock after verified deletion. Unknown target-only partitions stay untouched. `database-tables push '<stableKey>' --prune-orphans --yes --force` can remove a target-only root with that Stable Key without a prior baseline. Before either remote deletion, the CLI rechecks live identity and dependencies; active child partitions or Database Views referencing the table block it. A successful delete is verified before the lock changes.
|
|
369
418
|
|
|
370
|
-
|
|
419
|
+
`database-tables pull --prune-orphans --yes --force` removes local manifests missing from the source; it never deletes target tables. Dedicated plan reports root orphans without accepting `--prune-orphans`. Repository `deploy --force` can delete previously managed partitions but not root orphans. Named `migrate` does not prune remote tables or partitions.
|
|
371
420
|
|
|
372
|
-
- `
|
|
373
|
-
- `REVO_TOKEN` or `REVO_API_KEY`
|
|
374
|
-
- `REVO_NO_UPDATE_NOTIFIER`
|
|
375
|
-
- `REVOENGINE_URL` or `REVOENGINE_BASE_URL`
|
|
376
|
-
- `REVOENGINE_TOKEN` or `REVOENGINE_API_KEY`
|
|
421
|
+
Resource plans support `--json` for automation and generally support `--strict` as a convergence gate. Human-readable plans show changes by default and hide informational details such as dependency readiness, component hashes, owners, and size statistics; add `--hints` to show them in individual plans, `revo plan`, and `revo migrate plan`. JSON plans still include the complete diagnostic data. Run `revo --help` for resource-specific safety flags such as `--activate`, `--skip-partitions`, and prune controls.
|
|
377
422
|
|
|
378
|
-
|
|
423
|
+
## Safety model
|
|
424
|
+
|
|
425
|
+
- `plan`, `diff`, and `verify` do not write target resources.
|
|
426
|
+
- `--yes` confirms a bulk operation; it does not relax consistency checks.
|
|
427
|
+
- `--force` approves only explicitly supported risky or drifted operations; it is not a universal bypass.
|
|
428
|
+
- Writes resolve the target UUID and version immediately before mutation and verify the portable result afterward.
|
|
429
|
+
- Stable Keys cross environments; source UUIDs, versions, members, users, ACLs, and other target-local identities do not.
|
|
430
|
+
- New Schedules and Events are created inactive; ordinary updates preserve target activation. Dedicated `schedules push --all --yes --activate` activates only flagged candidates written and verified in that push, not unchanged Schedules. `events push --all --yes --activate` aligns verified Events with manifest activation intent, including disabling them; configuration failures skip Event activation. Interactive activation requires an additional confirmation. `deploy` and `migrate` do not run this activation phase.
|
|
431
|
+
- Groups and Role Groups are intentionally late phases because they can affect ownership and access.
|
|
432
|
+
- Lock data is stored in `.revoengine/revo.lock.json`; API tokens are never persisted in the project.
|
|
433
|
+
|
|
434
|
+
## Other commands
|
|
379
435
|
|
|
380
436
|
```bash
|
|
381
|
-
|
|
382
|
-
export REVO_TOKEN="your-ci-token"
|
|
437
|
+
# List API endpoints
|
|
383
438
|
revo endpoints
|
|
384
|
-
```
|
|
385
439
|
|
|
386
|
-
|
|
440
|
+
# Search platform content
|
|
441
|
+
revo search CODE button
|
|
442
|
+
revo search SIMPLE customer
|
|
387
443
|
|
|
388
|
-
|
|
389
|
-
|
|
444
|
+
# Make a low-level API request
|
|
445
|
+
revo request GET /api/component/list
|
|
446
|
+
revo request POST /api/component '{"name":"Customer Card"}'
|
|
390
447
|
|
|
391
|
-
|
|
448
|
+
# Debug a local component in the sandbox
|
|
449
|
+
revo component debug <componentId> --stream
|
|
450
|
+
```
|
|
392
451
|
|
|
393
|
-
|
|
452
|
+
Use low-level `request` carefully; it bypasses the higher-level migration planner.
|
|
394
453
|
|
|
395
|
-
|
|
454
|
+
## HTTP diagnostics
|
|
396
455
|
|
|
397
|
-
|
|
398
|
-
|
|
456
|
+
Enable a per-invocation HTTP trace in `.revoengine/revo.lock.json`:
|
|
457
|
+
|
|
458
|
+
```json
|
|
459
|
+
{
|
|
460
|
+
"schemaVersion": 2,
|
|
461
|
+
"diagnostics": {
|
|
462
|
+
"httpTrace": {
|
|
463
|
+
"enabled": true
|
|
464
|
+
}
|
|
465
|
+
}
|
|
466
|
+
}
|
|
399
467
|
```
|
|
400
468
|
|
|
401
|
-
|
|
469
|
+
Each enabled invocation writes `.revoengine/logs/http-trace/<timestamp>.json` and prints its report path to stderr. A trace entry covers one client request and its entire retry loop, including waits; it records the final status and duration. Finalization waits up to five seconds for outstanding requests and marks any that remain incomplete.
|
|
402
470
|
|
|
403
|
-
|
|
404
|
-
|
|
405
|
-
|
|
471
|
+
Traces retain only known static API route segments, method, status, timing, payload byte counts, and diagnostic stage or resource labels. They omit URL origins and query strings, dynamic IDs and names, Stable Keys, profile names, headers, correlation values, bodies, error messages, and command arguments. An error contributes its class name only. This keeps credentials and instance-specific identifiers out of trace reports.
|
|
472
|
+
|
|
473
|
+
Inventory reads bound concurrent detail requests to roughly 10 per helper call; this is not a global per-host rate limit. Most resource readers use bounded batches or the shared order-preserving worker pool. Database View inventory deduplicates active list IDs, fetches complete details, excludes deleted readbacks, and sorts by ID. Failed detail reads fail the inventory instead of silently producing a partial snapshot.
|
|
474
|
+
|
|
475
|
+
Client requests default to no transport retries and there is no global retry flag. Database View detail reads opt into two retries, for up to three attempts. Opted-in requests can retry transport or response-read errors and HTTP 429, 502, 503, or 504; HTTP 500 is retried only for GET, HEAD, and OPTIONS. Aborted requests are not retried. Backoff starts at 100 ms with jitter, respects a bounded numeric `Retry-After`, and shares one request timeout across attempts. This opt-in behavior can also apply to mutations, so resource-specific write recovery still performs its own fresh live validation before retrying.
|
|
476
|
+
|
|
477
|
+
## Update notifications
|
|
478
|
+
|
|
479
|
+
Interactive runs check npm for a newer version at most once every 24 hours. Disable the check with `--no-update-notifier` or `REVO_NO_UPDATE_NOTIFIER=1`.
|
|
406
480
|
|
|
407
481
|
## Local development
|
|
408
482
|
|
|
409
483
|
```bash
|
|
410
484
|
npm install
|
|
485
|
+
npm run build
|
|
411
486
|
npm run check
|
|
412
487
|
npm test
|
|
413
|
-
|
|
488
|
+
npm pack --dry-run
|
|
414
489
|
```
|