@revoengine/cli 1.0.11 → 1.0.12

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 (81) hide show
  1. package/README.md +275 -479
  2. package/dist/src/cli.js +71 -5
  3. package/dist/src/client.d.ts +28 -12
  4. package/dist/src/client.js +234 -66
  5. package/dist/src/commands/component.d.ts +67 -0
  6. package/dist/src/commands/component.js +299 -27
  7. package/dist/src/commands/database-tables.d.ts +2 -0
  8. package/dist/src/commands/{database-schemas.js → database-tables.js} +21 -40
  9. package/dist/src/commands/database-views.js +21 -18
  10. package/dist/src/commands/endpoints.js +26 -16
  11. package/dist/src/commands/events.js +18 -20
  12. package/dist/src/commands/groups.js +13 -22
  13. package/dist/src/commands/index.d.ts +2 -1
  14. package/dist/src/commands/index.js +2 -1
  15. package/dist/src/commands/job-templates.js +21 -15
  16. package/dist/src/commands/metadata.js +58 -15
  17. package/dist/src/commands/migrate.d.ts +6 -0
  18. package/dist/src/commands/migrate.js +658 -0
  19. package/dist/src/commands/project.js +4 -4
  20. package/dist/src/commands/role-groups.js +14 -25
  21. package/dist/src/commands/schedules.js +19 -20
  22. package/dist/src/commands/terminal-browser.d.ts +16 -0
  23. package/dist/src/commands/terminal-browser.js +92 -0
  24. package/dist/src/commands/terminal-image.d.ts +7 -0
  25. package/dist/src/commands/terminal-image.js +40 -0
  26. package/dist/src/commands/terminal-patch-worker.d.ts +1 -0
  27. package/dist/src/commands/terminal-patch-worker.js +24 -0
  28. package/dist/src/commands/terminal-patch.d.ts +2 -0
  29. package/dist/src/commands/terminal-patch.js +156 -0
  30. package/dist/src/commands/terminal-sandbox.d.ts +8 -0
  31. package/dist/src/commands/terminal-sandbox.js +87 -0
  32. package/dist/src/commands/terminal-service.js +2 -2
  33. package/dist/src/commands/terminal.d.ts +31 -4
  34. package/dist/src/commands/terminal.js +360 -45
  35. package/dist/src/component-lock.d.ts +12 -2
  36. package/dist/src/component-lock.js +60 -1
  37. package/dist/src/diff-details.d.ts +8 -0
  38. package/dist/src/diff-details.js +152 -0
  39. package/dist/src/env-sync.js +8 -6
  40. package/dist/src/http-trace.d.ts +94 -0
  41. package/dist/src/http-trace.js +226 -0
  42. package/dist/src/metadata-backfill.d.ts +5 -4
  43. package/dist/src/metadata-backfill.js +82 -158
  44. package/dist/src/migration.d.ts +141 -0
  45. package/dist/src/migration.js +1632 -0
  46. package/dist/src/resource-inventory.d.ts +28 -0
  47. package/dist/src/resource-inventory.js +85 -0
  48. package/dist/src/resource-syncs/{database-schema-sync.d.ts → database-table-sync.d.ts} +13 -3
  49. package/dist/src/resource-syncs/{database-schema-sync.js → database-table-sync.js} +147 -62
  50. package/dist/src/resource-syncs/database-view-sync.d.ts +24 -2
  51. package/dist/src/resource-syncs/database-view-sync.js +156 -68
  52. package/dist/src/resource-syncs/endpoint-sync.d.ts +27 -0
  53. package/dist/src/resource-syncs/endpoint-sync.js +362 -82
  54. package/dist/src/resource-syncs/event-sync.d.ts +27 -0
  55. package/dist/src/resource-syncs/event-sync.js +123 -26
  56. package/dist/src/resource-syncs/group-sync.d.ts +7 -0
  57. package/dist/src/resource-syncs/group-sync.js +60 -14
  58. package/dist/src/resource-syncs/job-template-sync.d.ts +21 -0
  59. package/dist/src/resource-syncs/job-template-sync.js +91 -30
  60. package/dist/src/resource-syncs/role-group-sync.d.ts +7 -0
  61. package/dist/src/resource-syncs/role-group-sync.js +47 -9
  62. package/dist/src/resource-syncs/schedule-sync.d.ts +30 -1
  63. package/dist/src/resource-syncs/schedule-sync.js +114 -20
  64. package/dist/src/resource-syncs/util.d.ts +3 -0
  65. package/dist/src/resource-syncs/util.js +8 -6
  66. package/dist/src/resource-target.d.ts +11 -0
  67. package/dist/src/resource-target.js +48 -0
  68. package/dist/src/sync-output.d.ts +29 -1
  69. package/dist/src/sync-output.js +139 -2
  70. package/dist/src/tracked-resources.d.ts +1 -1
  71. package/dist/src/tracked-resources.js +8 -6
  72. package/dist/src/types.d.ts +3 -0
  73. package/dist/src/ui.js +18 -9
  74. package/dist/src/utils.d.ts +2 -0
  75. package/dist/src/utils.js +17 -0
  76. package/dist/src/workspace-diff.d.ts +25 -0
  77. package/dist/src/workspace-diff.js +75 -0
  78. package/package.json +9 -6
  79. package/dist/src/commands/database-schemas.d.ts +0 -2
  80. /package/dist/src/{database-schema-artifacts.d.ts → database-table-artifacts.d.ts} +0 -0
  81. /package/dist/src/{database-schema-artifacts.js → database-table-artifacts.js} +0 -0
package/README.md CHANGED
@@ -1,693 +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
- Add a project connection. The new project becomes active immediately:
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
- revo projects add local --url http://localhost:3000
28
- revo projects list
37
+ revo auth login
29
38
  revo auth status
39
+ revo auth logout
30
40
  ```
31
41
 
32
- To use the original `default` connection instead, save its credentials:
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.
43
+
44
+ You can also provide the values without prompts:
33
45
 
34
46
  ```bash
35
- revo auth login
47
+ revo auth login \
48
+ --url https://api.revoengine.com \
49
+ --token "$SOURCE_REVO_TOKEN"
36
50
  ```
37
51
 
38
- `revo auth login` opens a masked interactive terminal prompt for your API key and saves the `default` login. If you are already logged in, the CLI warns and asks you to `revo auth logout` first. For named connections, use `revo projects add <name>`.
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.
39
53
 
40
- 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.
54
+ ### Saved projects
41
55
 
42
- Check the active session:
56
+ Save a connection and make it active for ordinary commands, including repository pull, plan, diff, and deploy:
43
57
 
44
58
  ```bash
45
- revo auth status
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
46
64
  ```
47
65
 
48
- Connect this computer as an Agent Gateway terminal with the same CLI installation and login:
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:
49
71
 
50
72
  ```bash
51
73
  revo terminal connect --workspace "$HOME/projects/my-project" --name "Work Mac"
52
74
  revo terminal status
53
- revo --version
54
75
  ```
55
76
 
56
- Pairing appears in AI Agents → Terminals for approval and access configuration; personal Vault settings also shows the grant. `revo terminal connect` runs in the foreground; stop it with Ctrl+C after approval if you want to move it into the background. Install a per-user background service for the approved terminal: LaunchAgent on macOS or `systemd --user` on Linux.
57
-
58
- Each registration has a stable `agentTerminalId` and a model reference token `[AGENT_TERMINAL/<agentTerminalId>](Name)`. Existing local `runner.json` entries with `deviceId` are read with the same ID, so they do not need to be paired again. Access defaults to `restricted: true`; the owner can explicitly grant access to users, groups, or the entire instance.
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.
59
78
 
60
79
  ```bash
61
80
  revo terminal service install --workspace "$HOME/projects/my-project"
62
81
  revo terminal service uninstall --workspace "$HOME/projects/my-project"
82
+ revo terminal disconnect --workspace "$HOME/projects/my-project"
63
83
  ```
64
84
 
65
- The service starts at login, reconnects automatically, and pins the environment active at installation (or an explicit `--project <name>`). Install one service per workspace/profile; pass the same `--project` to uninstall after switching environments. 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. The runner uses your OS permissions; the workspace controls the starting directory, not OS sandbox access. A personal API key is required.
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.
66
86
 
67
- Remove stored credentials:
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.
68
88
 
69
- ```bash
70
- revo auth logout
71
- ```
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`.
72
90
 
73
- Show the command reference:
91
+ ### Environment variables
74
92
 
75
- ```bash
76
- revo --help
77
- ```
78
-
79
- Initialize a project for ambient low-code editor globals:
93
+ Environment variables are the recommended authentication method for CI/CD:
80
94
 
81
95
  ```bash
82
- revo project init
83
- revo project init ./app
84
- revo project init ./app --identity-mode stableKey --stable-key-name resourceKey --resources component
85
- revo project init ./app --identity-mode componentId
86
- revo project update ./app
87
- ```
88
-
89
- 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.
90
-
91
- 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.
92
-
93
- `--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`.
96
+ export REVO_URL="https://api.revoengine.com"
97
+ export REVO_TOKEN="$SOURCE_REVO_TOKEN"
94
98
 
95
- ```json
96
- {
97
- "componentIdentity": {
98
- "mode": "stableKey",
99
- "metadataProperty": "resourceKey"
100
- }
101
- }
99
+ revo -i
100
+ revo diff
102
101
  ```
103
102
 
104
- 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:
105
104
 
106
- 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`, `endpoint`, `group`, `role-group`, `job-template`, `schedule`, `event`, `database-schema`, or `database-view`; when omitted it defaults to `all`. Project initialization backfills missing stable-key metadata for the established resource families while preserving existing keys. Database Schema and Database View backfill are deliberately excluded from automatic initialization because large catalogs and metadata-only database updates require an explicit operator review. Init prints the exact follow-up plan command. Pass `--no-metadata-backfill` when initialization must not write any remote metadata.
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` |
107
111
 
108
- Backfill stable-key metadata for tracked resources with an explicit plan/apply flow:
112
+ ### Command-line flags
113
+
114
+ Flags are useful for one-off commands and override all other runtime configuration:
109
115
 
110
116
  ```bash
111
- revo metadata plan --project test
112
- revo metadata apply --project test --yes
117
+ revo \
118
+ --url https://api.revoengine.com \
119
+ --instance "$REVO_INSTANCE_ID" \
120
+ --token "$REVO_API_TOKEN" \
121
+ pull --all --yes
113
122
  ```
114
123
 
115
- Backfill only writes resources missing the configured stable-key metadata unless `--force` is passed. Generated resource keys use `category/name#<random-hex>`. Database Schema and Database View keys are immutable once present, even with `--force`. Database View backfill reads the current view and uses the deployed full `PUT` API with the same definition, type, version, and ACL, changing only user metadata to add the Stable Key. Because this is a full view update, run it in a reviewed maintenance window. Database Schema backfill also plans column keys in `definition[].metadata.<stable-key-name>` for root tables only, using `category/table/column#<random-hex>`; existing, malformed, or duplicate column keys are never overwritten, including with `--force`. Partition definitions inherit their root table's columns and never receive independent column keys.
116
-
117
- ### Database Schemas
124
+ Global connection flags:
118
125
 
119
- Database Schemas use an explicit SOURCE bootstrap followed by a portable pull:
120
-
121
- ```bash
122
- revo metadata plan --project test --resources database-schema
123
- revo metadata apply --project test --resources database-schema --yes
124
- # Generate Stable Keys only for root schemas and leave partitions unmanaged:
125
- revo metadata plan --project test --resources database-schema --skip-partitions
126
- revo metadata apply --project test --resources database-schema --skip-partitions --yes
127
- revo database-schemas pull --all --project test
128
- # Fail when any active schema or partition remains unmanaged:
129
- revo database-schemas pull --all --project test --strict
130
- # Compare desired manifests, the selected lock baseline, and live E2E without writes:
131
- revo database-schemas plan --all --project e2e
132
- revo database-schemas plan --all --project e2e --json
133
- # Review only root schemas; partitions are excluded from the API catalog, workspace comparison, and strict coverage:
134
- revo database-schemas plan --all --project e2e --skip-partitions
135
- # Add one cached bulk size request for table/index/audit risk context:
136
- revo database-schemas plan --all --project e2e --with-stats
137
- # CI convergence and Stable Key coverage gate:
138
- revo database-schemas plan --all --project e2e --strict
139
- # Create, safely update, and verify managed root schemas and their partitions:
140
- revo database-schemas push --all --project e2e --yes
141
- # Or create one reviewed graph node by Stable Key:
142
- revo database-schemas push 'Sales/Orders#1234abcd' --project e2e --yes
143
- # Only after reviewing safe remote content drift; --force never bypasses manual DDL migration:
144
- revo database-schemas push --all --project e2e --yes --force
145
- # Destructive prune of previously managed partitions only:
146
- revo database-schemas push --all --project e2e --yes --force --prune-partitions
147
- # Destructive removal of reviewed target-only root schemas (no active partitions or Database View dependencies):
148
- revo database-schemas push --all --project e2e --yes --force --prune-orphans
149
- # After a reviewed deletion on the source, remove stale local desired manifests and locks only:
150
- revo database-schemas pull --all --project test --yes --force --prune-orphans
151
- ```
152
-
153
- The catalog is read in deterministic pages of 200 records. Pass `--skip-partitions` to `metadata plan` and `metadata apply` when only root Database Schemas should receive generated table Stable Keys; the CLI adds a server-side `parent isNull` filter and defensively excludes any partition returned by the API. Without this flag, root schemas and partitions remain in scope for table keys, while column-key backfill always remains root-only. Root manifests are written below `<workspace>/DatabaseSchemas/<category>/`; every managed partition has its own nested manifest under its parent and carries its own Stable Key plus `parentStableKey`. Partition manifests do not duplicate the inherited column definition.
154
-
155
- Manifests retain the complete non-reserved user metadata and portable column/partition configuration. Instance UUIDs, column definition IDs, versions, timestamps, records, details, users, ACL, audit settings, and tags are excluded. ACL, audit, and tags are returned only as pull diagnostics and are outside the portable hash; the lock retains only a root's source `restricted` boolean so first creation can safely reject a restricted source without storing target principals. Foreign references remain visible in the column definition with `migration.foreignReferences: "manual"` because they require operator migration. Missing Stable Keys are reported as unmanaged and skipped; duplicates, invalid keys, parent cycles, missing parents, and path collisions stop the pull before files change. A locally edited manifest is preserved unless `--force` is supplied. A normal pull never deletes local manifests. After reviewing source deletions, `pull --prune-orphans --yes --force` removes only local manifests and lock entries that no longer exist on the selected source; it never deletes any target table.
156
-
157
- `database-schemas plan` is fileless and read-only. It reports three-way states plus root/partition orphans, previously managed partition removals, unmanaged WIP resources, collisions, reconciled manual work, and `manual-schema-migration-required`. Pass `--skip-partitions` for a root-schema-only view: partitions are excluded server-side with `parent isNull`, local partition manifests are excluded too, and they do not contribute to `--strict` coverage. This view intentionally cannot report partition drift, lifecycle work, or unmanaged partitions. Table names, parent relationships, partition bounds, column removals, unsafe keyless column additions, and structural changes without exact column identity remain manual. Changes to an existing column are operational when desired and target definitions share one unique column Stable Key; this includes rename, type, default, nullability, array, primary-key, unique, and index fields. A required, defaulted, indexed, unique, or primary-key new column is also operational when its desired definition carries one unique Stable Key that is absent from the target. A rename is still blocked as manual when the table has an active Database View or foreign-reference declaration. Column presentation order, column metadata, and adding an explicitly nullable column without a default, primary key, unique constraint, index, or foreign reference remain safe definition changes. Every reported change includes an operational hint covering the relevant lock, scan, rewrite, index, validation, conversion, or data-loss risk. `--with-stats` performs exactly one cached bulk `/api/v1/databases/stats` request; the default plan avoids that database-size query. `--strict` accepts only converged resources and informational target-only orphans, and fails for drift, collisions, manual migrations, deletions, missing baselines, or incomplete Stable Key coverage.
158
-
159
- `database-schemas push` creates missing schemas and applies reviewed safe or controlled operational updates. It re-plans live state, then resolves an exact Stable Key match and fetches its current version immediately before every write; it never sends source UUIDs, rows, ACLs, audit or tags. Existing target column IDs are reattached first by a unique shared column Stable Key and otherwise by exact column name. With a unique shared key, the CLI imports changes to type, default, nullability, array, primary-key, unique, index, name, description, and metadata while preserving the target column identity. It also creates a required, defaulted, indexed, unique, or primary-key column when the new desired definition has one unique Stable Key absent from the target; no instance-local definition ID is sent for that new column. These structural writes can still fail when live data is incompatible and should be run in a reviewed maintenance window; every write is followed by an exact GET and portable-hash verification before the selected environment baseline is recorded. The write is still refused if an active Database View appears after planning a rename. Column drops, unsafe additions without a unique key, structural changes without a unique shared key, malformed or duplicate column keys, and foreign-reference deployment remain manual; `--force` can overwrite reviewed portable content drift but never bypasses those blockers. If an environment lock baseline was lost, `--force` first adopts an exactly matching target through GET-and-hash verification only; it sends no PUT. A reviewed safe difference without that baseline can also be aligned with `--force`. When a manually aligned target already matches the manifest, push verifies the live hash and advances only the selected lock baseline. Audited targets show an audit-trigger-rebuild warning, serialize writes, and retry one audit-lock conflict only after fresh validation. Root tables are created `restricted=false` and `audit=false`; a root pulled as restricted is reported as `access-policy-required` and skipped. Partitions follow root → child → nested-child order, reference the resolved target parent by name, and inherit definition, audit and ACL from that target parent. A failed or unavailable parent skips only its dependent branch, while unrelated creates continue. Removing a previously managed partition manifest produces `delete-partition`; deletion requires all of `--prune-partitions --yes --force`, is processed leaf-to-root, rechecks the live parent and active Database View dependencies, then records an environment tombstone after readback. A target-only root marked `orphan-root` can be deleted only with `--prune-orphans --yes --force`; it is revalidated by Stable Key and hash, and deletion is blocked when it has an active partition or Database View dependency. Unmanaged target-only partitions are never deleted. A tombstoned Stable Key is never recreated automatically, and overlapping replacement bounds require two separate pushes: prune the old partition first, then create the new partition with a new Stable Key.
160
-
161
- ### Database Views
162
-
163
- Database Views are migrated only after their Database Schemas and column Stable Keys converge on the target:
126
+ - `--project <name>` (or the compatible `--env <name>`)
127
+ - `--url <url>` or `--baseUrl <url>`
128
+ - `--instance <uuid>`
129
+ - `--token <apiKey>`
164
130
 
165
- ```bash
166
- revo metadata plan --project test --resources database-view
167
- revo metadata apply --project test --resources database-view --yes
168
- revo database-views pull --all --project test
169
- revo database-views plan --all --project e2e --strict
170
- revo database-views push --all --project e2e --yes
171
- # Or deploy one reviewed ordinary view by Stable Key:
172
- revo database-views push 'Reporting/high_value_customers#f00dbabe' --project e2e --yes
173
- # Materialized writes need their own explicit operational gate:
174
- revo database-views push --all --project e2e --yes --allow-materialized
175
- ```
131
+ Avoid putting tokens directly in shell history. Prefer environment variables for automation.
176
132
 
177
- The workspace contains `STRUCTURED` and `RAW_SQL` `VIEW` and `MATERIALIZED_VIEW` manifests below `<workspace>/DatabaseViews/`. A `RAW_SQL` manifest retains the SQL text and source schema Stable Keys, while a `STRUCTURED` manifest additionally retains referenced-column Stable Keys; neither retains instance IDs, generated lineage, versions, or source ACL principals. RAW_SQL preview and writes require the target's `databaseViewsRawSql` feature flag and `RESOURCE_ADMIN` permission. A materialized manifest retains the ordered `uniqueKey` and index columns but drops server-generated index names; independent index definitions are normalized deterministically. A plan is fileless: it resolves every source on the target, runs a bounded `take: 0` preview, reports materialization/quota risk and active refresh schedules, and blocks collisions, missing baselines, incompatible output, and any rename or type/mode transition. Materialized creates and updates require `--allow-materialized`; an active refresh schedule blocks an update and must be coordinated manually. Create re-plans live, previews again immediately before POST, and creates a private target view with empty users and groups. Updates fetch the exact live record, then send the full desired definition in a PUT with the current optimistic version while preserving its target-local ACL; preview and post-write hash verification are repeated before advancing the baseline. `--force` may overwrite reviewed portable content drift, but never identity, source-readiness, preview, ACL, rename, type, mode, schedule, or materialized-write-gate blockers. An identical target with a missing baseline is adopted by GET-and-hash verification without a PUT. A matching private view with an empty target-local ACL is `clean`; source ACLs are never copied, and access can be configured independently on the target. For the TEST → E2E operating procedure, including stable-key bootstrap, plan artifacts, target-local ACL work, materialized-view maintenance windows, and strict verification, see [the Database Views runbook](docs/runbooks/database-views-test-to-e2e.md).
133
+ ### Cross-environment migration
178
134
 
179
- Job templates use the same metadata bootstrap and workspace boundary. Generate keys on the source environment, then pull portable manifests into `<workspace>/JobTemplates`:
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.
180
136
 
181
137
  ```bash
182
- revo metadata plan --project test --resources job-template
183
- revo metadata apply --project test --resources job-template --yes
184
- revo job-templates pull --all --project test
185
- revo job-templates plan --all --project e2e
186
- revo job-templates plan --all --project e2e --json
187
- revo job-templates push --all --project e2e --yes
188
- # Only after reviewing remote-changed, conflict, or missing-lock:
189
- revo job-templates push --all --project e2e --yes --force
138
+ revo projects add source --url https://api.revoengine.com
139
+ revo projects add target --url https://api.revoengine.com
140
+ revo projects list
190
141
  ```
191
142
 
192
- ### Endpoints
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>`.
193
144
 
194
- ```bash
195
- # Establish Stable Key identity on SOURCE, then pull portable endpoint configuration to
196
- # <workspace>/Endpoints and extend .revoengine/revo.lock.json.
197
- revo metadata plan --project test --resources endpoint
198
- revo metadata apply --project test --resources endpoint --yes
199
- revo endpoints pull --all --project test
200
- revo endpoints plan --all --project e2e
201
- revo endpoints plan --all --project e2e --json
202
- revo endpoints push --all --project e2e --yes
203
- revo endpoints plan --all --project e2e --strict
204
- ```
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.
205
146
 
206
- Endpoint plan is fileless and read-only. It compares portable workspace manifests, the selected target-environment baseline in `.revoengine/revo.lock.json`, and the live target. Component dependencies are resolved only by exact stable key. Latest bindings require identical portable Component content in the workspace and target; pinned bindings require the pulled digest, workspace digest, and target digest to all match. Dependency mismatches block every Endpoint write and instruct the operator to align Components before Endpoints.
147
+ Runtime configuration precedence is:
207
148
 
208
- Push recomputes the live plan, resolves target Component UUIDs and versions only in memory, and rejects all hard blockers before the first write. Creates, updates, and exact Stable Key restores converge configuration first and then the desired active state. Every write is fetched again and compared by the full portable hash before the target lock baseline is updated. `--force` can accept reviewed three-way content drift, but cannot bypass identity, route, dependency, restore-safety, or concurrency checks. Target-only and unmanaged Endpoints remain untouched, and `--prune` is rejected.
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.
209
154
 
210
- For the complete **SOURCE** → **TARGET** operator flow, Component dependency gate,
211
- GitLab CI plan artifact, manual PROD approval, strict verification, and rollback,
212
- see [the Endpoint runbook](https://gitlab.com/revoengine/cli/-/blob/master/docs/runbooks/endpoint-source-to-target.md).
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.
213
156
 
214
- Job-template manifests keep portable `options` and legacy `inputs`, reference their component by component stable key, and exclude UUIDs, versions, audit data, pinned component versions, and `triggerUser`. When `triggerUser` is present, pull prints a warning because the execution principal must be configured independently per environment.
157
+ ## Project setup and portable identity
215
158
 
216
- Schedules support source bootstrap, portable pull, planning, and deployment for user-managed `JOB_TEMPLATE` targets and Materialized View refresh targets:
159
+ Initialize a repository before using repository deployment or full migrations:
217
160
 
218
161
  ```bash
219
- # Establish stable-key identity for the source schedules.
220
- revo metadata plan --project test --resources schedule
221
- revo metadata apply --project test --resources schedule --yes
222
-
223
- # Event bootstrap currently covers only JOB_TEMPLATE targets.
224
- revo metadata plan --project test --resources event
225
- revo metadata apply --project test --resources event --yes
226
-
227
- # Pull source Schedule definitions and their lock baselines.
228
- revo schedules pull --all --project test
229
-
230
- # Compare the local definitions, the E2E lock baseline, and live E2E schedules.
231
- revo schedules plan --all --project e2e
232
- revo schedules plan --all --project e2e --json
233
- revo schedules plan --all --project e2e --strict
234
-
235
- # Create disabled Schedules and safely update existing definitions.
236
- revo schedules push --all --project e2e --yes
237
- # Materialized View refresh definitions require an additional operational gate.
238
- revo schedules push --all --project e2e --yes --allow-materialized
239
- # Only after reviewing remote-changed, conflict, or missing-lock:
240
- revo schedules push --all --project e2e --yes --force --allow-materialized
241
-
242
- # Deliberately activate only candidates created or updated by this push.
243
- revo schedules push --all --project e2e --yes --allow-materialized --activate
162
+ revo project init . \
163
+ --identity-mode stableKey \
164
+ --stable-key-name stableKey \
165
+ --resources all
244
166
  ```
245
167
 
246
- Each manifest references either a Job Template by Stable Key or a Materialized View by Database View Stable Key plus `CONCURRENT` or `BLOCKING` refresh mode. It excludes Schedule UUIDs, dependency UUIDs, versions, source `active`, and `targetVersion`. Source `active` becomes an editable `activationCandidate`; Job Template `sourceTargetConfig` is retained for operator context only. Before a Schedule can be created or updated, its dependency must resolve to exactly one compatible live target by exact Stable Key. A target-kind transition is reported as a warning and conflict, and can be applied only after review with `--force`. Missing or ambiguous dependencies, ordinary Views, `AGENT`, unrelated `PLATFORM_OPERATION`, system-managed, deleted, and unmanaged Schedules remain blocking or explicit exclusions. `--strict` fails for drift, blockers, or exclusions; target-only orphans remain informational.
168
+ Initialization authenticates and downloads editor types from the instance's sandbox endpoint. It creates or updates:
169
+
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.
247
173
 
248
- Schedule push repeats its live preflight immediately before each write. Creates always send `active: false`; ordinary updates do not change the target activation state. Every create or update re-resolves the target Schedule and dependency, uses the live Schedule version for updates, re-fetches the result, verifies its portable hash, and then advances the selected environment baseline. Materialized View writes require `--allow-materialized`; that gate cannot be bypassed with `--force`. Deploy Database Views before their refresh Schedules. `remote-changed`, `conflict` (including target-kind transitions), and `missing-lock` require explicit `--force`. An exactly matching `missing-lock` target is re-read and adopted into the selected environment baseline without a PUT. There is no Schedule prune: target-only orphans remain untouched.
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.
249
175
 
250
- `schedules push --activate` is the optional final activation phase. It activates only candidates created or updated and verified in that same push, and never disables an already active target. Interactive use asks for a second confirmation; non-interactive use requires both `--yes` and `--activate`. Activation failures are isolated per Schedule.
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`.
251
177
 
252
- Events currently support the source pull step for `JOB_TEMPLATE` targets. After assigning Stable Keys to Events and their Job Templates, pull the portable source manifests and lock baselines:
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:
253
179
 
254
180
  ```bash
255
- revo metadata plan --project test --resources event
256
- revo metadata apply --project test --resources event --yes
257
- revo events pull --all --project test
258
- revo events plan --all --project e2e
259
- revo events plan --all --project e2e --json
260
- revo events plan --all --project e2e --strict
181
+ revo metadata plan --project source --json
182
+ revo metadata apply --project source --yes
183
+ ```
261
184
 
262
- # Create disabled Events and safely update their configuration.
263
- revo events push --all --project e2e --yes
264
- # Only after reviewing remote-changed, conflict, or missing-lock states:
265
- revo events push --all --project e2e --yes --force
185
+ You can limit the operation:
266
186
 
267
- # After the configuration phase completes, align active state with source.
268
- revo events push --all --project e2e --yes --activate
187
+ ```bash
188
+ revo metadata plan --project source --resources component,endpoint
189
+ revo metadata apply --project source --resources component,endpoint --yes
269
190
  ```
270
191
 
271
- The resulting `<workspace>/Events/**/event.json` manifests retain the Event name, category, description, type, filter, metadata, activation declaration, and API configuration fields that are portable. They replace `targetId` with the Job Template Stable Key and exclude instance UUIDs, target version/configuration, Event version, audits, execution history, and deletion fields. Events targeting `AGENT`, deleted Events, and Events whose target Job Template has no Stable Key are reported as exclusions and are not written. Pull preserves a locally changed Event manifest unless it is repeated with `--force`.
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.
272
193
 
273
- `events plan` is read-only. It compares each local Event with the selected environment's lock baseline and live target, then reports `clean`, `create`, `safe-update`, `remote-changed`, `conflict`, `missing-lock`, `activation-drift`, `orphan`, `collision`, and `skipped`. A difference only in `active` is always `activation-drift`, never a skip. Each Job Template Stable Key must resolve exactly once on the target; missing or ambiguous dependencies block the plan. Orphans and exclusions are reported but are not changed. `--strict` accepts only `clean`, informational `orphan`, and `skipped` states.
194
+ Use `--no-metadata-backfill` with `project init` when initialization must not write remote metadata.
274
195
 
275
- `events push` repeats the live preflight for every write and resolves `target.jobTemplateStableKey` to one exact target UUID and fresh version. Creates run before updates in Stable Key order and always send `active: false`; ordinary updates never change target activation. Each write is read back and verified against the full portable Event configuration before its environment baseline advances. The current Event API has no write contract for unknown `extensions`; they are retained by pull for visibility but block plan/push rather than risking a partial migration. `remote-changed`, `conflict`, and `missing-lock` require `--force`; invalid identity, unresolved dependencies, unmanaged targets, and API errors never become forceable. Orphans and skipped Events remain untouched.
196
+ ## 1. Repository workflow
276
197
 
277
- `events push --activate` is the optional second phase. It starts only after all configuration writes have verified successfully, then activates or disables verified Events to match source `active`. Interactive use asks for a second confirmation; non-interactive use requires `--yes --activate`. Activation results, including partial failures, are present in both terminal and JSON output.
198
+ Use this workflow when a Git repository is the reviewed source of truth.
278
199
 
279
- For the complete **SOURCE** → **TARGET** operator and CI sequence, including the required Component gate, plan artifact, and rollback procedure, see [the Job Template runbook](https://gitlab.com/revoengine/cli/-/blob/master/docs/runbooks/job-template-test-to-e2e.md). The commands in that runbook use TEST → E2E as a concrete example.
200
+ ```text
201
+ RevoEngine source -> revo pull -> repository -> revo diff -> revo plan -> revo deploy -> RevoEngine target
202
+ ```
280
203
 
281
- ### Group migration
204
+ ### Pull source state into the repository
282
205
 
283
- Groups use the same configured workspace and shared `.revoengine/revo.lock.json` as the other resource families. A Group manifest is stored below `<workspace>/Groups/` and contains only the portable name, category, description, user-owned metadata, and Stable Key. UUIDs, versions, members, user identifiers, member counts, leader, avatar, and access type are not persisted. The shared lock stores a `GROUP` owner only as another Group Stable Key. A source `USER` owner is recorded only as a manual-owner policy, never as a user UUID.
206
+ Authenticate to the source through flags, environment variables, or the stored login, then pull all resources:
284
207
 
285
208
  ```bash
286
- # Establish Stable Keys on the source environment. Existing keys are preserved.
287
- revo metadata plan --project test --resources group
288
- revo metadata apply --project test --resources group --yes
289
-
290
- # Pull portable source configuration and the TEST baseline.
291
- revo groups pull --all --project test
292
-
293
- # Compare the local desired state, E2E baseline, and live E2E Groups.
294
- revo groups plan --all --project e2e
295
- revo groups plan --all --project e2e --json
296
- revo groups plan --all --project e2e --strict
209
+ export REVO_URL="https://api.revoengine.com"
210
+ export REVO_TOKEN="$SOURCE_REVO_TOKEN"
297
211
 
298
- # Apply after review. Push recomputes the live plan and never consumes plan JSON.
299
- revo groups push --all --project e2e --yes
212
+ revo pull --all --yes
300
213
  ```
301
214
 
302
- `plan` reports missing `GROUP`-owned structures as `create` when the owner can be resolved on the target or created earlier in the same acyclic dependency graph. Missing source `USER`-owned structures are `manual-owner`: create them in the target UI with a target-local user owner and the exact source Stable Key, then run plan again. A same category/name target Group with a missing or different Stable Key is a blocking `collision`; the CLI never infers identity from its name.
303
-
304
- `push` resolves every source `GROUP` owner by Stable Key to its target UUID immediately before POST or PUT. Create sends `members: []`. Updates synchronize a source `GROUP` owner relationship, but preserve a target-local owner when the source policy is `USER`. Member data is never hashed, compared, or sent. Target-only Groups remain `orphan` and are never deleted. Cyclic owner graphs cannot be created through the current single-Group API when the target has no bootstrap Group, so plan blocks them before any write. After an explicitly reviewed manual bootstrap creates both cycle members with temporary target-local owners and exact Stable Keys, plan reports owner drift and push safely closes the cycle with target Group UUIDs. An atomic/deferred-owner backend contract remains the preferred fully automatic solution.
305
-
306
- For the complete **SOURCE** → **TARGET** operator flow, GitLab CI artifact
307
- template, bootstrap procedure, and rollback, see [the Group runbook](https://gitlab.com/revoengine/cli/-/blob/master/docs/runbooks/group-source-to-target.md).
308
-
309
- ### Role-group migration
310
-
311
- Role groups use the same lock-based `pull -> plan -> push` workflow as components. Generate stable keys on TEST first. Before deploying to another environment, copy the exact TEST `metadata.stableKey` to any matching role group that already exists there. Members and user UUIDs are always excluded.
312
-
313
- Role-group manifests are committed below `RoleGroups/` in the workspace configured by `revo project init`. For a project configured with `workspace: "backend"`, the files live below `backend/RoleGroups/`. Sync baselines live in the shared `.revoengine/revo.lock.json`; TEST, E2E and PROD hashes are isolated by environment name. Role-group lock entries contain no UUID or version.
215
+ Or pull only selected resource families:
314
216
 
315
217
  ```bash
316
- # Bootstrap missing role-group stable keys on the source environment.
317
- revo metadata plan --project test --resources role-group
318
- revo metadata apply --project test --resources role-group --yes
319
-
320
- # Pull the portable desired state into the configured workspace.
321
- revo role-groups pull --all --project test
322
-
323
- # Preview E2E without changing files, lock, or the environment.
324
- revo role-groups plan --all --project e2e
325
- revo role-groups plan --all --project e2e --json
326
-
327
- # Apply after review. Push recomputes the live plan and resolves target UUID/version.
328
- revo role-groups push --all --project e2e --yes
329
-
330
- # Verify convergence. Orphans and unrelated unmanaged groups remain untouched.
331
- revo role-groups plan --all --project e2e --strict
218
+ revo pull \
219
+ --resources database-table,database-view,component,job-template,endpoint \
220
+ --yes
332
221
  ```
333
222
 
334
- `plan` performs a three-way comparison between the local manifest, the selected environment baseline in `revo.lock.json`, and the live target. It reports `clean`, `create`, `safe-update`, `remote-changed`, `conflict`, `missing-lock`, `orphan`, `collision`, and `skipped`. JSON output may be retained as a CI review artifact, but it is never accepted as push input.
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.
335
224
 
336
- `push` resolves the current target UUID by stableKey and reads the current target version immediately before mutation. A matching resource is updated in place even when its UUID differs from TEST. Base fields use the optimistic-version `PUT`; role relationships are synchronized separately through the backend `roleAdd` and `roleDelete` operations. `--force` may adopt or overwrite reviewed content drift, but never bypasses missing/duplicate stable keys, unknown system roles, or ambiguous identity. Prune is disabled until the backend soft-delete contract is confirmed. To roll back an update, restore the previous manifest commit, run plan again, and push that desired state.
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.
337
226
 
338
- Artifacts from the earlier experimental `resource` workflow under `.revoengine/resources`, `.revoengine/plans`, and `.revoengine/resources.lock.json` are ignored with a warning and are not removed automatically. The old `revo resource ...` command is no longer part of the CLI surface.
227
+ ### Review and deploy the repository
339
228
 
340
- ## Common commands
229
+ Commit and review the generated files. Then authenticate to the target:
341
230
 
342
231
  ```bash
343
- revo endpoints
344
- revo project init ./app
345
- revo search CODE button
346
- revo search SIMPLE customer
347
- revo request GET /api/component/list
348
- revo request POST /api/component "{\"name\":\"Customer Card\"}"
349
- ```
350
-
351
- `revo search` accepts only two search types:
232
+ export REVO_URL="https://api.revoengine.com"
233
+ export REVO_TOKEN="$TARGET_REVO_TOKEN"
352
234
 
353
- - `CODE` searches code references.
354
- - `SIMPLE` searches everything.
235
+ revo diff
236
+ revo plan
237
+ revo deploy --yes
238
+ ```
355
239
 
356
- `revo request` accepts an optional positional `<BODY>` argument as a JSON string. The existing `--body` / `-d` flag still works as well.
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.
357
241
 
358
- ## Component sync
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.
359
243
 
360
- Pull one or more components by id:
244
+ The target can also come from a saved project (`revo plan --project target`), a stored login, or explicit CI credentials:
361
245
 
362
246
  ```bash
363
- revo component pull 6dfb536a-1111-4222-8333-123456789abc
364
- revo component pull 6dfb536a-1111-4222-8333-123456789abc 7afc7b98-4444-4555-8666-abcdefabcdef
247
+ revo --url "$REVO_API_URL" --instance "$REVO_INSTANCE_ID" --token "$REVO_API_TOKEN" plan --json
365
248
  ```
366
249
 
367
- Pull every available component:
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`.
368
251
 
369
- ```bash
370
- revo component pull --all
371
- revo component pull --all --yes
372
- revo component pull --all --force
373
- ```
374
-
375
- Preview sync status before changing local or remote state:
252
+ The deployment scope comes from `.revoengine/revo.json.trackedResources`:
376
253
 
377
254
  ```bash
378
- revo component plan --all
379
- revo component plan --all --json
380
- revo component plan --all --strict
255
+ revo project update \
256
+ --resources database-table,database-view,component,job-template,endpoint,schedule,event
381
257
  ```
382
258
 
383
- Push one or more local components:
259
+ For CI output, use JSON:
384
260
 
385
261
  ```bash
386
- revo component push 6dfb536a-1111-4222-8333-123456789abc
387
- revo component push --all
388
- revo component push --all --yes
389
- revo component push --all --force
262
+ revo diff --json
263
+ revo plan --json
264
+ revo deploy --yes --json
390
265
  ```
391
266
 
392
- For a migration from a saved source profile to another instance, use the same workspace workflow as Job Templates and Role Groups. Without `--project`, component commands use the active project. With `--project <name>`, they use that saved profile for one invocation and record a separate baseline under `components.<stableKey>.environments.<name>` in `.revoengine/revo.lock.json`. This profile-based workflow requires `componentIdentity.mode: "stableKey"` in `.revoengine/revo.json`; it refuses UUID-only identity so different instance UUIDs cannot be mistaken for missing components.
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.
393
268
 
394
- ```bash
395
- # Pull TEST into the workspace and record the TEST baseline.
396
- revo component pull --all --yes --project test
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.
397
270
 
398
- # Compare local source with live E2E and the E2E baseline.
399
- revo component plan --all --project e2e
400
- revo component plan --all --project e2e --json
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.
401
272
 
402
- # Create missing target components or safely update managed target components.
403
- revo component push --all --yes --project e2e
404
- ```
273
+ ## 2. Project-to-project migration
405
274
 
406
- The profile mode matches components by the configured stable key. It adopts an already identical target as the E2E baseline, creates a component missing from E2E, and blocks target drift without an E2E baseline. Commands targeting `default` retain their legacy lock behavior.
407
-
408
- Debug one local component in sandbox:
275
+ Use this workflow for a direct migration between two saved projects. It does not require committing the source snapshot to the repository.
409
276
 
410
277
  ```bash
411
- revo component debug 6dfb536a-1111-4222-8333-123456789abc
412
- revo component debug 6dfb536a-1111-4222-8333-123456789abc -d '{"filters":{}}'
413
- revo component debug 6dfb536a-1111-4222-8333-123456789abc --timeout 30 --memory 256
414
- revo component debug 6dfb536a-1111-4222-8333-123456789abc --stream
278
+ revo projects add source --url https://api.revoengine.com
279
+ revo projects add target --url https://api.revoengine.com
415
280
  ```
416
281
 
417
- `--raw-debug` saves the full request and source map as a private file under the CLI config directory and prints only its path to stderr. Delete that file when the investigation is finished.
418
-
419
- Pulled components are stored as a tree:
420
-
421
- ```text
422
- Components/
423
- Forms/
424
- Customer_Card-6dfb536a-1111-4222-8333-123456789abc/
425
- component.json
426
- elements/
427
- 1_template.ts
428
- 2_logic.ts
429
- ```
430
-
431
- Each component folder keeps its `component.json` manifest alongside an `elements/` directory with the source payload for every element.
432
- Components with `category: null` are stored under `Components/__no_category__/...` while the manifest keeps `"category": null`.
433
-
434
- 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.
435
-
436
- Bulk sync behavior:
437
-
438
- - `revo component pull --all` and `revo component push --all` require terminal confirmation unless `--yes` or `--force` is passed.
439
- - `--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.
440
- - `revo component pull --all` requests only active remote components where `deletedAt` is empty.
441
- - Pull compares local files, `.revoengine/revo.lock.json`, and the current remote component before overwriting anything.
442
- - Pull fast-forwards clean local files when the remote moved and the local copy still matches the lock.
443
- - Pull rejects conflicts when both local files and the remote changed since the lock baseline.
444
- - Pull writes stable source manifests and keeps remote version churn out of `Components/**/component.json`.
445
- - `revo component plan --all --strict` exits with an error when conflicts or missing lock entries are present.
446
- - Push checks the current remote component against the lock before saving local changes.
447
- - 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.
448
- - Push rejects stale remote state instead of trusting the version inside local component JSON.
449
- - Push treats backend `Not modified` responses as skipped instead of failing the whole run.
450
- - Push treats backend `404` responses as skipped with `doesn't exist remotely`; restore the component in RevoEngine before pushing local changes to it.
451
- - Debug posts the local `component.json` plus `elements/{order}_{key}.{js|ts}` source files to the authenticated sandbox `debug` endpoint.
452
- - `revo component debug --stream` posts to `debug/stream`, writes live `api.log()` frames to stderr, and writes the final raw result payload to stdout.
453
- - Debug responses are saved under `.revoengine/output/debug_<timestamp>.json`.
454
- - 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.
455
- - Sync logs show direction explicitly: `RevoEngine -> path` for pull and `RevoEngine <- path` for push.
456
- - Bulk runs print a summary such as `Deployed 54/67, Skipped 13/67 in 13s`.
457
-
458
- ## Projects
459
-
460
- Save named project connections and switch the active one for ordinary CLI commands. `revo project init` configures the local workspace:
282
+ Plan, run, and verify the migration:
461
283
 
462
284
  ```bash
463
- revo projects add develop --url https://api.dev.revong.com
464
- revo projects add e2e --url https://api.e2e.revong.com
465
- revo projects add prod --url https://app.revo.com
466
- revo projects list
467
- revo projects set develop
468
- revo auth status
469
- revo endpoints
470
- revo projects set default
471
- revo projects remove e2e
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
472
288
  ```
473
289
 
474
- `revo projects add` prompts for the API key, validates it against `/api/v1/me`, asks whether it is production, saves it, and makes it active. Use `--offline` to skip validation. `revo projects list` marks the active connection with `*`; `revo -i` and `revo auth status` show its name and API URL. `revo projects set <name>` switches the persistent default for subsequent commands. `revo projects set default` selects the original `revo auth login` credentials. An explicit `--project <name>` selects one profile for a single invocation without changing the active project. `--env` and `revo env` remain supported as compatibility aliases. Named profiles keep their own URL, key, and instance even when `REVO_URL`, `REVO_TOKEN`, or `REVO_INSTANCE` is set. Removing the active profile returns to `default`.
475
-
476
- `revo auth logout` clears only the original default login and keeps named project profiles and the active selection. Resource sync commands use the active named profile when `--project` is omitted; their existing requirement for a named profile remains. A production profile (stored as `"production": true` in `config.json`) requires an interactive confirmation before the first POST, PUT, PATCH, or DELETE in every CLI invocation. This protection cannot be bypassed with `--yes`, `--force`, or non-interactive CI.
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.
477
293
 
478
- Cross-environment component operations remain available as advanced commands:
294
+ Select a subset with a comma-separated or repeated `--resources` flag:
479
295
 
480
296
  ```bash
481
- revo env diff --from develop --to e2e
482
- revo env diff --from develop --to e2e --json
483
- revo env diff --from develop --to e2e --strict # CI drift gate: non-zero exit on any difference
484
- revo env diff --from develop --to e2e --prune # classify target-only components as deletes
485
- revo env diff --from develop --to e2e --key Forms/Card --category Shared
486
- ```
487
-
488
- 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.
297
+ revo migrate plan \
298
+ --from source \
299
+ --to target \
300
+ --resources component,job-template,endpoint \
301
+ --json
489
302
 
490
- 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`.
303
+ revo migrate run \
304
+ --from source \
305
+ --to target \
306
+ --resources database-table \
307
+ --yes \
308
+ --force
309
+ ```
491
310
 
492
- Mirror components from a source environment into a target:
311
+ Use `--skip-groups` to omit both `group` and `role-group`:
493
312
 
494
313
  ```bash
495
- revo env apply --from develop --to e2e # prints the plan, then asks for confirmation
496
- revo env apply --from develop --to e2e --dry-run # plan only, never writes
497
- revo env apply --from develop --to e2e --yes # confirm creates/updates non-interactively
498
- revo env apply --from develop --to e2e --yes --prune --force # full mirror including deletes
314
+ revo migrate plan --from source --to target --skip-groups
315
+ revo migrate run --from source --to target --skip-groups --yes
499
316
  ```
500
317
 
501
- Apply semantics:
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.
502
319
 
503
- - Creates run first, then updates, then deletes; failures are reported per component and the run continues.
504
- - `--yes` only confirms the bulk apply. Deletes additionally require `--force` (non-interactive) or a second dedicated confirmation (interactive), matching the component sync semantics.
505
- - Deletes only happen with `--prune`; without it, target-only components are reported as `orphan` and left alone.
506
- - 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.
507
- - 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`.
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.
508
321
 
509
- ## Environment sync runbook
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.
510
323
 
511
- 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.
324
+ ## 3. Supported resources
512
325
 
513
- 1. Initialize the local project metadata:
326
+ Full pull, deployment, and migration use this fixed dependency order:
514
327
 
515
- ```bash
516
- revo project init
517
- ```
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. |
518
339
 
519
- For CI or non-interactive setup:
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.
520
341
 
521
- ```bash
522
- revo project init --identity-mode stableKey --stable-key-name stableKey --resources all
523
- ```
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.
524
343
 
525
- This writes `.revoengine/revo.json` with:
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.
526
345
 
527
- - `componentIdentity.mode`: `stableKey` for portable identity or `componentId` for legacy instance-bound identity.
528
- - `componentIdentity.metadataProperty`: the component metadata property used in stable-key mode. Default: `stableKey`.
529
- - `trackedResources`: resource families the CLI should track. Default: `all`; this CLI currently tracks components.
346
+ ### Work with one resource family
530
347
 
531
- 2. Save environment profiles:
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:
532
349
 
533
350
  ```bash
534
- revo projects add test --url https://api.test.revong.com
535
- revo projects add dev --url https://api.dev.revong.com
536
- revo projects list
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
537
355
  ```
538
356
 
539
- For one-off commands without a saved profile, use `default` plus environment variables:
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`.
358
+
359
+ When migrating Schedules after Database Views, review the plan and use this full push with the active login (no `--project`):
540
360
 
541
361
  ```bash
542
- REVO_URL="https://api.dev.revong.com" REVO_TOKEN="$REVO_DEV_TOKEN" revo metadata plan --project default
362
+ revo schedules plan --all
363
+ revo schedules push --all --yes --force
543
364
  ```
544
365
 
545
- 3. Plan metadata backfill before writing anything:
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.
546
367
 
547
- ```bash
548
- revo metadata plan --project test
549
- revo metadata plan --project dev
550
- ```
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.
551
369
 
552
- Use JSON when reviewing exact resources:
370
+ Use `--project` to select a saved project explicitly (`--env` remains a compatible alias):
553
371
 
554
372
  ```bash
555
- revo metadata plan --project test --json
373
+ revo <command> pull --all --project source
374
+ revo <command> plan --all --project target
375
+ revo <command> push --all --project target --yes
556
376
  ```
557
377
 
558
- 4. Apply metadata backfill:
378
+ For example:
559
379
 
560
380
  ```bash
561
- revo metadata apply --project test --yes
562
- revo metadata apply --project dev --yes
381
+ revo endpoints pull --all --project source
382
+ revo endpoints plan --all --project target --json
383
+ revo endpoints push --all --project target --yes
563
384
  ```
564
385
 
565
- 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.
566
-
567
- 5. Verify metadata backfill:
386
+ Database Table and Database View pushes can also select one Stable Key:
568
387
 
569
388
  ```bash
570
- revo metadata plan --project test
571
- revo metadata plan --project dev
389
+ revo database-tables push 'Sales/Orders#1234abcd' --project target --yes
390
+ revo database-views push 'Sales/Revenue#1234abcd' --project target --yes
572
391
  ```
573
392
 
574
- Expected after a successful backfill:
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.
575
394
 
576
- ```text
577
- Plan: 0 to update, N already populated, 0 blocked.
578
- ```
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.
579
396
 
580
- 6. Preview environment drift:
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.
581
398
 
582
- ```bash
583
- revo env diff --from test --to dev
584
- revo env diff --from test --to dev --json
585
- ```
399
+ ### Database Table identity, DDL, and target-local policy
586
400
 
587
- Use `--strict` in CI:
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.
588
402
 
589
- ```bash
590
- revo env diff --from test --to dev --strict
591
- ```
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.
592
404
 
593
- 7. Apply non-destructive sync:
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.
594
406
 
595
- ```bash
596
- revo env apply --from test --to dev --dry-run
597
- revo env apply --from test --to dev --yes
598
- ```
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.
599
408
 
600
- Without `--prune`, target-only resources are reported as `orphan` and left untouched.
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.
601
410
 
602
- 8. Apply full mirror with orphan removal:
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.
603
412
 
604
- ```bash
605
- revo env diff --from test --to dev --prune
606
- revo env apply --from test --to dev --prune --dry-run
607
- revo env apply --from test --to dev --prune --yes --force
608
- ```
413
+ ### Database Table partitions and deletion
609
414
 
610
- Only use `--prune --force` after reviewing the plan. It deletes target resources that are missing from the source.
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.
611
416
 
612
- ## Configuration
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.
613
418
 
614
- The CLI selects a project from `--project <name>` or the active project. For a named project, it uses that project's URL, key, and instance; explicit `--url`, `--token`, and `--instance` flags can override individual values. Named projects do not inherit values from environment variables or the `default` login.
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.
615
420
 
616
- For `default`, the CLI reads configuration in this order:
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.
617
422
 
618
- 1. CLI flags such as `--url` and `--token`
619
- 2. Environment variables such as `REVO_URL` and `REVO_TOKEN`
620
- 3. Stored config in the OS config directory
423
+ ## Safety model
621
424
 
622
- This means environment variables override the locally stored `default` config, which supports CI and non-interactive automation.
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.
623
433
 
624
- Use `--url` for one-off local or dedicated API targets:
434
+ ## Other commands
625
435
 
626
436
  ```bash
627
- revo --url https://api.test.revong.com -i
628
- revo --url https://api.test.revong.com auth login
629
- revo --url https://api.revoengine.com endpoints
630
- ```
437
+ # List API endpoints
438
+ revo endpoints
631
439
 
632
- Use environment variables for CI/CD or shell profiles:
440
+ # Search platform content
441
+ revo search CODE button
442
+ revo search SIMPLE customer
633
443
 
634
- ```bash
635
- # TEST
636
- export REVO_URL="https://api.test.revong.com"
637
- export REVO_TOKEN="your-test-token"
638
- revo endpoints
444
+ # Make a low-level API request
445
+ revo request GET /api/component/list
446
+ revo request POST /api/component '{"name":"Customer Card"}'
639
447
 
640
- # PROD
641
- export REVO_URL="https://api.revoengine.com"
642
- export REVO_TOKEN="your-prod-token"
643
- revo endpoints
448
+ # Debug a local component in the sandbox
449
+ revo component debug <componentId> --stream
644
450
  ```
645
451
 
646
- Supported environment variables:
647
-
648
- - `REVO_URL` or `REVO_BASE_URL`
649
- - `REVO_TOKEN` or `REVO_API_KEY`
650
- - `REVO_NO_UPDATE_NOTIFIER`
651
- - `REVO_TRUSTED_SERVICE_ORIGINS` (comma-separated exact HTTPS origins for custom sandbox services)
652
- - `REVOENGINE_URL` or `REVOENGINE_BASE_URL`
653
- - `REVOENGINE_TOKEN` or `REVOENGINE_API_KEY`
452
+ Use low-level `request` carefully; it bypasses the higher-level migration planner.
654
453
 
655
- Authenticated API requests reject cross-origin pagination links and redirects. The sandbox service advertised by the authenticated profile may use a different origin: matching first-party API/sandbox hosts and `localhost` services are trusted automatically. For a custom sandbox, set `REVO_TRUSTED_SERVICE_ORIGINS` to its exact origin before running editor-type update or component debug. Do not include a path or credentials in this setting.
454
+ ## HTTP diagnostics
656
455
 
657
- Example for CI:
456
+ Enable a per-invocation HTTP trace in `.revoengine/revo.lock.json`:
658
457
 
659
- ```bash
660
- export REVO_URL="https://api.revoengine.com"
661
- export REVO_TOKEN="your-ci-token"
662
- revo endpoints
458
+ ```json
459
+ {
460
+ "schemaVersion": 2,
461
+ "diagnostics": {
462
+ "httpTrace": {
463
+ "enabled": true
464
+ }
465
+ }
466
+ }
663
467
  ```
664
468
 
665
- Stored config lives in:
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.
666
470
 
667
- - macOS and Linux: `~/.config/revoengine`
668
- - Windows: `%APPDATA%/revoengine`
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.
669
472
 
670
- ## Update notifications
671
-
672
- 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.
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.
673
474
 
674
- Disable the check for one run:
675
-
676
- ```bash
677
- revo --no-update-notifier endpoints
678
- ```
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.
679
476
 
680
- Disable it through the environment:
477
+ ## Update notifications
681
478
 
682
- ```bash
683
- export REVO_NO_UPDATE_NOTIFIER=1
684
- ```
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`.
685
480
 
686
481
  ## Local development
687
482
 
688
483
  ```bash
689
484
  npm install
485
+ npm run build
690
486
  npm run check
691
487
  npm test
692
- node ./bin/revo.ts --help
488
+ npm pack --dry-run
693
489
  ```