CLI projects

A CLI project maps RevoEngine component definitions to a local workspace while keeping generated editor types and synchronization state separate from authored files.

Initialize a workspace

revo project init ./app \
  --identity-mode stableKey \
  --stable-key-name stableKey \
  --resources component

Run revo project as the short interactive form, or refresh an existing project with:

revo project update ./app

Initialization writes or refreshes:

.revoengine/
  revo.json
  types/
    revo.editor.d.ts
    revo.editor.definitions.json

The command also patches the workspace tsconfig.json or jsconfig.json and updates root .gitignore so generated editor bundles remain local by default. When the RevoEngine code lives in a nested directory, the root .revoengine/ directory remains the single state location and revo.json stores the workspace path. Component pull/push creates and updates .revoengine/revo.lock.json as synchronization state.

Identity strategy

New projects should use stableKey. The configured metadata value identifies the same logical component across instances even though component and element UUIDs differ.

{
  "componentIdentity": {
    "mode": "stableKey",
    "metadataProperty": "stableKey"
  }
}

Stable-key mode manages only components that contain the configured metadata property. Missing or duplicate keys block unsafe plan/pull/push operations. Use componentId mode only for a workspace intentionally bound to one instance. Plan and apply missing metadata explicitly:

revo metadata plan --env default
revo metadata apply --env default --yes

Pull, plan, and push

# Pull one component or all active components
revo component pull "$COMPONENT_ID"
revo component pull --all --yes

# Review local/remote state without writing
revo component plan --all
revo component plan --all --json
revo component plan --all --strict

# Push selected or all local components
revo component push "$COMPONENT_ID"
revo component push --all --yes

Pulled components use a stable tree:

Components/
  Forms/
    Customer_Card-<component-id>/
      component.json
      elements/
        1_template.ts
        2_logic.ts

Each component manifest is stored beside one source file per element. Components without a category are placed under Components/__no_category__/ while the manifest preserves category: null.

Conflict model

.revoengine/revo.lock.json records the last successfully pulled or pushed remote baseline. The CLI compares three states before overwriting anything:

current local component files;
the lock baseline;
current remote state.

A clean local copy can fast-forward when only the remote changed. If both sides changed, pull or push reports a conflict instead of choosing a winner. --force bypasses lock-content safety for an explicitly selected bulk operation, but it does not bypass missing or duplicate stable identity.

The lock file is synchronization evidence, not deployed source of truth. RevoEngine remains authoritative for deployed state; local component files are the desired source you are proposing.

Portable owners and execution policies

Use owner: { "type": "system" } for a Group or Service Account whose management owner is the built-in System account. An ordinary Service Account owner uses owner: { "type": "service-account", "stableKey": "operations-worker" }. The CLI resolves these references in the target instance. A Service Account manifest owner becomes management access; it does not grant execution roles. System itself is protected and is excluded from managed-account exports, updates, and pruning. A target without a valid physical System account is blocked before dependent writes. Endpoint execution identifies the Component. The separate executionPolicy chooses permission identity and business currentUser behavior:

{
  "executionPolicy": {
    "mode": "SERVICE_ACCOUNT",
    "serviceAccount": { "kind": "system" },
    "currentUser": "CALLER"
  }
}

For an ordinary executor, use serviceAccount: { "kind": "service-account", "stableKey": "operations-worker" }. Both Endpoints and Job Templates accept INHERIT, CALLER, or SERVICE_ACCOUNT; omit serviceAccount for the first two. Only Endpoints have the independent currentUser choice. Job code sees the captured executor and records the initiator separately. Instance execution defaults are target-local settings under Settings → Endpoints and are not copied by resource migration. Existing Job executionPrincipal manifests remain supported; use either that legacy reference or executionPolicy, not both. Writing an explicit policy clears the legacy executor alias. Configured SERVICE_ACCOUNT execution with administrator permissions requires approved Component and library code; see Endpoint configuration.

Debug local source

revo component debug "$COMPONENT_ID" \
  --body '{"customerId":"customer-1"}' \
  --timeout 30 \
  --memory 256 \
  --stream

Debug sends the local manifest and element files to Sandbox without first saving them as the remote component. In stream mode, live api.log() frames go to stderr and the terminal result goes to stdout. A copy of the result is stored under .revoengine/output/. Local JavaScript/TypeScript library components are included as transient overrides by default. Use --no-extra-libs when you intentionally want only server-saved active libraries.

Integrate

Model Context Protocol

Node.js SDK

CLI

VS Code

Initialize a workspace

Identity strategy

Pull, plan, and push

Conflict model

Portable owners and execution policies

Debug local source

​Initialize a workspace

​Identity strategy

​Pull, plan, and push

​Conflict model

​Portable owners and execution policies

​Debug local source

Initialize a workspace

Identity strategy

Pull, plan, and push

Conflict model

Portable owners and execution policies

Debug local source