@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.
Files changed (104) hide show
  1. package/README.md +314 -239
  2. package/dist/src/cli.js +126 -9
  3. package/dist/src/client.d.ts +373 -6
  4. package/dist/src/client.js +1005 -53
  5. package/dist/src/commands/auth.js +4 -2
  6. package/dist/src/commands/component.d.ts +67 -0
  7. package/dist/src/commands/component.js +555 -164
  8. package/dist/src/commands/database-tables.d.ts +2 -0
  9. package/dist/src/commands/database-tables.js +169 -0
  10. package/dist/src/commands/database-views.d.ts +2 -0
  11. package/dist/src/commands/database-views.js +126 -0
  12. package/dist/src/commands/endpoints.js +124 -0
  13. package/dist/src/commands/env.js +44 -24
  14. package/dist/src/commands/events.d.ts +2 -0
  15. package/dist/src/commands/events.js +144 -0
  16. package/dist/src/commands/groups.d.ts +2 -0
  17. package/dist/src/commands/groups.js +160 -0
  18. package/dist/src/commands/index.d.ts +9 -0
  19. package/dist/src/commands/index.js +9 -0
  20. package/dist/src/commands/job-templates.d.ts +2 -0
  21. package/dist/src/commands/job-templates.js +107 -0
  22. package/dist/src/commands/metadata.js +75 -10
  23. package/dist/src/commands/migrate.d.ts +6 -0
  24. package/dist/src/commands/migrate.js +658 -0
  25. package/dist/src/commands/project.js +10 -3
  26. package/dist/src/commands/role-groups.d.ts +2 -0
  27. package/dist/src/commands/role-groups.js +141 -0
  28. package/dist/src/commands/schedules.d.ts +2 -0
  29. package/dist/src/commands/schedules.js +140 -0
  30. package/dist/src/commands/terminal-browser.d.ts +16 -0
  31. package/dist/src/commands/terminal-browser.js +92 -0
  32. package/dist/src/commands/terminal-image.d.ts +7 -0
  33. package/dist/src/commands/terminal-image.js +40 -0
  34. package/dist/src/commands/terminal-patch-worker.d.ts +1 -0
  35. package/dist/src/commands/terminal-patch-worker.js +24 -0
  36. package/dist/src/commands/terminal-patch.d.ts +2 -0
  37. package/dist/src/commands/terminal-patch.js +156 -0
  38. package/dist/src/commands/terminal-sandbox.d.ts +8 -0
  39. package/dist/src/commands/terminal-sandbox.js +87 -0
  40. package/dist/src/commands/terminal-service.d.ts +38 -0
  41. package/dist/src/commands/terminal-service.js +210 -0
  42. package/dist/src/commands/terminal.d.ts +49 -0
  43. package/dist/src/commands/terminal.js +826 -0
  44. package/dist/src/component-lock.d.ts +111 -3
  45. package/dist/src/component-lock.js +363 -15
  46. package/dist/src/config.d.ts +10 -2
  47. package/dist/src/config.js +49 -14
  48. package/dist/src/database-table-artifacts.d.ts +7 -0
  49. package/dist/src/database-table-artifacts.js +8 -0
  50. package/dist/src/diff-details.d.ts +8 -0
  51. package/dist/src/diff-details.js +152 -0
  52. package/dist/src/env-sync.d.ts +0 -3
  53. package/dist/src/env-sync.js +11 -25
  54. package/dist/src/http-trace.d.ts +94 -0
  55. package/dist/src/http-trace.js +226 -0
  56. package/dist/src/metadata-backfill.d.ts +18 -7
  57. package/dist/src/metadata-backfill.js +1002 -27
  58. package/dist/src/migration.d.ts +141 -0
  59. package/dist/src/migration.js +1632 -0
  60. package/dist/src/project.d.ts +2 -0
  61. package/dist/src/project.js +4 -17
  62. package/dist/src/prompt.js +10 -18
  63. package/dist/src/resource-inventory.d.ts +28 -0
  64. package/dist/src/resource-inventory.js +85 -0
  65. package/dist/src/resource-metadata.d.ts +1 -0
  66. package/dist/src/resource-metadata.js +3 -0
  67. package/dist/src/resource-syncs/database-table-sync.d.ts +127 -0
  68. package/dist/src/resource-syncs/database-table-sync.js +2374 -0
  69. package/dist/src/resource-syncs/database-view-sync.d.ts +146 -0
  70. package/dist/src/resource-syncs/database-view-sync.js +1405 -0
  71. package/dist/src/resource-syncs/endpoint-sync.d.ts +123 -0
  72. package/dist/src/resource-syncs/endpoint-sync.js +1563 -0
  73. package/dist/src/resource-syncs/event-sync.d.ts +126 -0
  74. package/dist/src/resource-syncs/event-sync.js +1046 -0
  75. package/dist/src/resource-syncs/group-sync.d.ts +93 -0
  76. package/dist/src/resource-syncs/group-sync.js +928 -0
  77. package/dist/src/resource-syncs/job-template-sync.d.ts +106 -0
  78. package/dist/src/resource-syncs/job-template-sync.js +843 -0
  79. package/dist/src/resource-syncs/role-group-sync.d.ts +90 -0
  80. package/dist/src/resource-syncs/role-group-sync.js +635 -0
  81. package/dist/src/resource-syncs/schedule-sync.d.ts +140 -0
  82. package/dist/src/resource-syncs/schedule-sync.js +1396 -0
  83. package/dist/src/resource-syncs/util.d.ts +22 -0
  84. package/dist/src/resource-syncs/util.js +118 -0
  85. package/dist/src/resource-target.d.ts +11 -0
  86. package/dist/src/resource-target.js +48 -0
  87. package/dist/src/runtime-view.d.ts +1 -0
  88. package/dist/src/runtime-view.js +6 -1
  89. package/dist/src/sync-output.d.ts +66 -0
  90. package/dist/src/sync-output.js +268 -0
  91. package/dist/src/tracked-resources.d.ts +1 -1
  92. package/dist/src/tracked-resources.js +28 -2
  93. package/dist/src/types.d.ts +227 -0
  94. package/dist/src/ui.d.ts +3 -0
  95. package/dist/src/ui.js +76 -18
  96. package/dist/src/utils.d.ts +4 -0
  97. package/dist/src/utils.js +81 -0
  98. package/dist/src/workspace-component.d.ts +2 -0
  99. package/dist/src/workspace-component.js +34 -0
  100. package/dist/src/workspace-diff.d.ts +25 -0
  101. package/dist/src/workspace-diff.js +75 -0
  102. package/dist/src/workspace-resource.d.ts +2 -0
  103. package/dist/src/workspace-resource.js +52 -0
  104. package/package.json +12 -4
package/README.md CHANGED
@@ -1,414 +1,489 @@
1
1
  # @revoengine/cli
2
2
 
3
- Official CLI for RevoEngine Platform.
3
+ Official command-line interface for moving RevoEngine configuration between an instance, a Git repository, and another instance.
4
4
 
5
- ## Install
5
+ The CLI has three main capabilities:
6
6
 
7
- ```bash
8
- npm install -g @revoengine/cli
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
- The package installs two binaries:
11
+ ## Requirements and installation
12
12
 
13
- - `revo` is the primary documented command.
14
- - `revoengine` is kept as a compatible alias.
13
+ - Node.js 24 or newer
14
+ - A RevoEngine API key
15
15
 
16
- ## Quick start
16
+ ```bash
17
+ npm install -g @revoengine/cli
18
+ ```
17
19
 
18
- Inspect the local runtime and config path:
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
- Log in and save your default credentials:
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
- `revo auth login` opens an interactive terminal prompt for your API key. If you are already logged in, the CLI warns and asks you to `revo auth logout` first.
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
- Check the active session:
44
+ You can also provide the values without prompts:
35
45
 
36
46
  ```bash
37
- revo auth status
47
+ revo auth login \
48
+ --url https://api.revoengine.com \
49
+ --token "$SOURCE_REVO_TOKEN"
38
50
  ```
39
51
 
40
- Remove stored credentials:
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 auth logout
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
- Show the command reference:
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 --help
73
+ revo terminal connect --workspace "$HOME/projects/my-project" --name "Work Mac"
74
+ revo terminal status
50
75
  ```
51
76
 
52
- Initialize a project for ambient low-code editor globals:
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 project init ./app
57
- revo project init ./app --identity-mode stableKey --stable-key-name resourceKey --resources component
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
- This writes or refreshes root `.revoengine/types/revo.editor.d.ts`, `.revoengine/types/revo.editor.definitions.json`, and `.revoengine/revo.json`, patches the workspace `tsconfig.json` or `jsconfig.json`, and updates root `.gitignore` so the generated editor bundle stays local by default. Pass a path such as `./backend` when the RevoEngine workspace is nested; the path is saved as `.revoengine/revo.json.workspace` while root `.revoengine/` remains the single state directory.
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
- When compiler options are missing, project initialization sets `target: ES2022`, `module: ESNext`, and `moduleDetection: force`. Revo TypeScript elements are runtime-wrapped snippets, so module detection is required for top-level `await`; existing explicit compiler options are preserved.
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
- `--identity-mode stableKey|componentId` stores the component matching strategy in `.revoengine/revo.json`. New projects default to `stableKey`; existing projects without this setting retain legacy `componentId` matching. In stable-key mode, `--stable-key-name <name>` selects the metadata property and defaults to `stableKey`.
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
- ```json
69
- {
70
- "componentIdentity": {
71
- "mode": "stableKey",
72
- "metadataProperty": "resourceKey"
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
- Stable-key mode manages only components that contain the configured metadata property. Component UUIDs remain in API requests and lock diagnostics, but they are not used as durable identity. Duplicate stable-key values block plan, pull, and push. Use `--identity-mode componentId` only for a workspace that intentionally remains bound to one RevoEngine instance.
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
- During interactive init, the CLI asks for the stable key metadata name and which resource families it should track. Press Enter to use `stableKey` and track `all` resources. For non-interactive runs, `--resources <list>` accepts `all` or comma-separated resource names such as `component`; when omitted it defaults to `all`. Project initialization also backfills missing stable-key metadata for every tracked component while preserving existing keys. Pass `--no-metadata-backfill` only when initialization must not write remote component metadata.
112
+ ### Command-line flags
80
113
 
81
- Backfill stable-key metadata for tracked resources with an explicit plan/apply flow:
114
+ Flags are useful for one-off commands and override all other runtime configuration:
82
115
 
83
116
  ```bash
84
- revo metadata plan --env test
85
- revo metadata apply --env test --yes
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
- Backfill only writes resources missing the configured stable-key metadata unless `--force` is passed. Generated component keys use `category/name#<random-hex>`.
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
- ## Common commands
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 endpoints
94
- revo project ./app
95
- revo search CODE button
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 search` accepts only two search types:
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
- - `CODE` searches code references.
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
- `revo request` accepts an optional positional `<BODY>` argument as a JSON string. The existing `--body` / `-d` flag still works as well.
147
+ Runtime configuration precedence is:
107
148
 
108
- ## Component sync
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
- Pull one or more components by id:
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
- ```bash
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
- Pull every available component:
159
+ Initialize a repository before using repository deployment or full migrations:
118
160
 
119
161
  ```bash
120
- revo component pull --all
121
- revo component pull --all --yes
122
- revo component pull --all --force
162
+ revo project init . \
163
+ --identity-mode stableKey \
164
+ --stable-key-name stableKey \
165
+ --resources all
123
166
  ```
124
167
 
125
- Preview sync status before changing local or remote state:
168
+ Initialization authenticates and downloads editor types from the instance's sandbox endpoint. It creates or updates:
126
169
 
127
- ```bash
128
- revo component plan --all
129
- revo component plan --all --json
130
- revo component plan --all --strict
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
- Push one or more local components:
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 component push 6dfb536a-1111-4222-8333-123456789abc
137
- revo component push --all
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
- Debug one local component in sandbox:
185
+ You can limit the operation:
143
186
 
144
187
  ```bash
145
- revo component debug 6dfb536a-1111-4222-8333-123456789abc
146
- revo component debug 6dfb536a-1111-4222-8333-123456789abc -d '{"filters":{}}'
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
- Pulled components are stored as a tree:
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
- Components/
155
- Forms/
156
- Customer_Card-6dfb536a-1111-4222-8333-123456789abc/
157
- component.json
158
- elements/
159
- 1_template.ts
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
- revo env add develop --url https://api.dev.revong.com
196
- revo env add e2e --url https://api.e2e.revong.com
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
- `revo env add` prompts for the API key, validates it against `/api/v1/me`, and stores the profile (with the inferred instance) next to your default login in the OS config directory. Use `--offline` to skip validation. `revo auth logout` clears only the default login and keeps named environment profiles.
212
+ revo pull --all --yes
213
+ ```
202
214
 
203
- Compare two environments:
215
+ Or pull only selected resource families:
204
216
 
205
217
  ```bash
206
- revo env diff --from develop --to e2e
207
- revo env diff --from develop --to e2e --json
208
- revo env diff --from develop --to e2e --strict # CI drift gate: non-zero exit on any difference
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
- The special name `default` refers to your normal login (`revo auth login` / `REVO_TOKEN`), so `--from default --to e2e` works without saving a profile for the default.
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
- Components are matched across environments by a **stable key** stored in resource metadata by the platform. The metadata property defaults to `stableKey`; initialize a workspace with `revo project init --stable-key-name <name>` or pass `--stable-key-name <name>` to env commands to use a different property. `revo metadata apply` writes this value to `metadata` for components. Env sync reads `metadata`, `metaData`, and `resourceMetadata` for compatibility, but it does not generate stable keys while creating resources. Project metadata also stores `trackedResources`, defaulting to `all`; env commands read it or accept `--resources <list>` directly. For older components that do not have metadata yet, the CLI falls back to normalized `category/name`, because component ids and element ids are instance-local. Content comparison uses a portable hash that ignores ids, versions, and timestamps. Two components in one environment that share the same stable key are reported as a `collision` and block `apply` until resolved or scoped out with `--key`/`--category`.
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
- Mirror components from a source environment into a target:
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
- revo env apply --from develop --to e2e # prints the plan, then asks for confirmation
221
- revo env apply --from develop --to e2e --dry-run # plan only, never writes
222
- revo env apply --from develop --to e2e --yes # confirm creates/updates non-interactively
223
- revo env apply --from develop --to e2e --yes --prune --force # full mirror including deletes
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
- Apply semantics:
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
- - Creates run first, then updates, then deletes; failures are reported per component and the run continues.
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
- ## Environment sync runbook
244
+ The target can also come from a saved project (`revo plan --project target`), a stored login, or explicit CI credentials:
235
245
 
236
- Use this flow when preparing one environment to track and mirror resources with the CLI. The examples use `test` as the source and `dev` as the target.
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
- 1. Initialize the local project metadata:
252
+ The deployment scope comes from `.revoengine/revo.json.trackedResources`:
239
253
 
240
254
  ```bash
241
- revo project init
255
+ revo project update \
256
+ --resources database-table,database-view,component,job-template,endpoint,schedule,event
242
257
  ```
243
258
 
244
- For CI or non-interactive setup:
259
+ For CI output, use JSON:
245
260
 
246
261
  ```bash
247
- revo project init --identity-mode stableKey --stable-key-name stableKey --resources all
262
+ revo diff --json
263
+ revo plan --json
264
+ revo deploy --yes --json
248
265
  ```
249
266
 
250
- This writes `.revoengine/revo.json` with:
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
- - `componentIdentity.mode`: `stableKey` for portable identity or `componentId` for legacy instance-bound identity.
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. Save environment profiles:
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 env add test --url https://api.test.revong.com
260
- revo env add dev --url https://api.dev.revong.com
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
- For one-off commands without a saved profile, use `default` plus environment variables:
282
+ Plan, run, and verify the migration:
265
283
 
266
284
  ```bash
267
- REVO_URL="https://api.dev.revong.com" REVO_TOKEN="$REVO_DEV_TOKEN" revo metadata plan --env default
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
- 3. Plan metadata backfill before writing anything:
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 metadata plan --env test
274
- revo metadata plan --env dev
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 JSON when reviewing exact resources:
311
+ Use `--skip-groups` to omit both `group` and `role-group`:
278
312
 
279
313
  ```bash
280
- revo metadata plan --env test --json
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
- 4. Apply metadata backfill:
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 metadata apply --env test --yes
287
- revo metadata apply --env dev --yes
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
- Important: if the same resources already exist in multiple environments, do not treat independently generated random suffixes as interchangeable. `category/name#aaaa1111` and `category/name#bbbb2222` are different stable keys, even when the readable prefix matches. Pick a source of truth and make the target environment use the exact same metadata value, including casing, before running destructive sync.
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
- 5. Verify metadata backfill:
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 metadata plan --env test
296
- revo metadata plan --env dev
362
+ revo schedules plan --all
363
+ revo schedules push --all --yes --force
297
364
  ```
298
365
 
299
- Expected after a successful backfill:
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
- ```text
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
- 6. Preview environment drift:
370
+ Use `--project` to select a saved project explicitly (`--env` remains a compatible alias):
306
371
 
307
372
  ```bash
308
- revo env diff --from test --to dev
309
- revo env diff --from test --to dev --json
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
- Use `--strict` in CI:
378
+ For example:
313
379
 
314
380
  ```bash
315
- revo env diff --from test --to dev --strict
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
- 7. Apply non-destructive sync:
386
+ Database Table and Database View pushes can also select one Stable Key:
319
387
 
320
388
  ```bash
321
- revo env apply --from test --to dev --dry-run
322
- revo env apply --from test --to dev --yes
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
- Without `--prune`, target-only resources are reported as `orphan` and left untouched.
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
- 8. Apply full mirror with orphan removal:
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
- ```bash
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
- Only use `--prune --force` after reviewing the plan. It deletes target resources that are missing from the source.
399
+ ### Database Table identity, DDL, and target-local policy
336
400
 
337
- ## Configuration
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
- The CLI reads configuration in this order:
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
- 1. CLI flags such as `--url` and `--token`
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
- This means environment variables override the locally stored config, which is the intended setup for CI and non-interactive automation.
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
- Use `--url` for one-off local or dedicated API targets:
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
- ```bash
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
- Use environment variables for CI/CD or shell profiles:
413
+ ### Database Table partitions and deletion
357
414
 
358
- ```bash
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
- # PROD
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
- Supported environment variables:
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
- - `REVO_URL` or `REVO_BASE_URL`
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
- Example for CI:
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
- export REVO_URL="https://api.revoengine.com"
382
- export REVO_TOKEN="your-ci-token"
437
+ # List API endpoints
383
438
  revo endpoints
384
- ```
385
439
 
386
- Stored config lives in:
440
+ # Search platform content
441
+ revo search CODE button
442
+ revo search SIMPLE customer
387
443
 
388
- - macOS and Linux: `~/.config/revoengine`
389
- - Windows: `%APPDATA%/revoengine`
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
- ## Update notifications
448
+ # Debug a local component in the sandbox
449
+ revo component debug <componentId> --stream
450
+ ```
392
451
 
393
- When running in an interactive terminal, the CLI checks the npm registry at most once every 24 hours and prints a colored notice on stderr when a newer `@revoengine/cli` version is available.
452
+ Use low-level `request` carefully; it bypasses the higher-level migration planner.
394
453
 
395
- Disable the check for one run:
454
+ ## HTTP diagnostics
396
455
 
397
- ```bash
398
- revo --no-update-notifier endpoints
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
- Disable it through the environment:
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
- ```bash
404
- export REVO_NO_UPDATE_NOTIFIER=1
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
- node ./bin/revo.ts --help
488
+ npm pack --dry-run
414
489
  ```