RePlatform CLI
replatform is the non-interactive process supervisor for a RePlatform migration. It starts
an installed coding agent, gives it the active migration project, observes durable migration
artifacts, and exposes run control from another terminal.
It is not a second migration engine. The installed wix-replatform skill still chooses
the next stage and performs migration work; existing receipts remain the only proof of
completion. The CLI provides the outer lifecycle: start, observe, answer human checkpoints,
cancel, and resume.
Start here
From an installed skill (npx skills add wix/skills/skills/wix-replatform) nothing else needs
installing: the CLI's only third-party dependency, commander, ships in vendor/. It needs
Node.js 22.12 or newer.
node <skill>/scripts/replatform.js --help
node <skill>/scripts/replatform.js run <project> --agent codexIf the bundled copy cannot load, the CLI exits 1 and preflight blocks on
toolkit_dependencies, both with the same fix: reinstall the skill and check the Node.js version.
The CLI never prompts for stdin, opens an editor or pager, or begins a vendor login flow. Required human work becomes a durable request that can be inspected and continued later.
Common lifecycle
# Start and receive normalized JSONL events (the default).
replatform run migrations/example --agent codex
# Check a live or completed run from another terminal.
replatform status <project-or-run-id>
replatform tail <project-or-run-id> --follow
# Read the persisted work plan, active task, and agent topology.
replatform tasks <project-or-run-id> --format json
# Read the identity currently authenticated in the local Wix CLI before a destination action.
replatform account
# Read a required human action, then provide the permitted response.
replatform requests <project-or-run-id>
replatform show <project-or-run-id> <request-id>
replatform answer --project <project> --request-id <request-id> --choice approved --continue
# A manual action has no approval choice. Complete the stated prerequisite first, then
# acknowledge it; the resumed stage verifies the prerequisite itself.
replatform answer --project <project> --request-id <request-id> --acknowledge --continue
# Stop only a supervisor that owns an active run, preserving migration recovery artifacts.
replatform cancel <project-or-run-id>Output and liveness
run, resume, and answer --continue default to --format jsonl. The first event carries
the run ID and the final event has type: "result". Use --format json for exactly one final
result object, or --format text for a concise human result. --format event-stream is an
alias for jsonl.
When a run needs a person, its user_action_requested event carries the full safe action
summary: why it is needed (message and userAction.prompt), response mode, permitted choices,
and reviewable artifacts. A JSONL consumer can therefore render the decision without reading a
project file; show remains available for the complete durable request or artifact contents.
Foreground runs emit a truthful liveness heartbeat every 60s when no newer observable
progress exists. Detached runs default to no heartbeat. Set --status-interval off to disable
foreground heartbeats, or choose a value from 10s to 5m. --events-file <path> mirrors
normalized JSONL events to a file. Raw adapter JSONL is retained at
state/runner/vendor-events.ndjson by default; --vendor-events <path> overrides that
diagnostic path. Codex collaboration events are decoded into the durable worker topology. A
reported pending_init state is reconciled against the child's own Codex session output and
terminal event, plus a newly written state/handoffs/*.json file. The runner emits
worker_start_timeout and retries only when the child has produced none of those signals for
the configured bound; tune the bound with --worker-startup-timeout <duration>.
Human checkpoints
requests lists every pending action with its response mode and a copyable next command.
choiceaccepts only one declared--choicevalue.choiceand a manual--acknowledgealso accept an optional--noteto record the operator's context without changing the selected decision or acknowledgement.textaccepts--textor--text-file.noneis a manual prerequisite. Run the stated external action, then use--acknowledge; this records the operator statement but does not replace deterministic verification by the resumed migration stage.
Some declared choices carry a narrowly scoped durable effect. For example, choosing
switch_to_standard after a quick-import preflight changes managementImportMode to standard
before --continue resumes. The event and result include that request's choices; the CLI never
infers an effect from a label alone.
show can display the action itself or an explicitly reviewable artifact. It never exposes
arbitrary project files. If it truncates a large artifact, it prints the exact emitted and total
byte counts.
Source and delivery choices
run --help describes every supported value. In brief:
--source-mode public_contentreads public pages and content.authenticated_apiuses standard source API access.private_datarequires protected source credentials.files_onlyimports supplied--filepaths.--delivery-mode managementmigrates backend data;websitemigrates the frontend only;management_and_websiteperforms both.--management-import-mode standarduses the full discovery and mapping flow;quickuses a bounded public adapter and plan.--site-type headless|studio|harmonychooses the type of a new destination site (with--destination new). Headless is a website developed in code; Studio and Harmony are websites designed in a Wix editor. There is no default: without it, a new-site run raises a durable site-type request before anything is created. The type cannot be changed later.--notification-mute on|offis valid only with--destination existing:<site-id>.onmutes all site notifications, including customer emails, until someone unmutes; the live business may miss real notifications meanwhile.offleaves them on, so customers and the owner may get emails for imported records. There is no default: without it, the run asks before the first write. A new site is always muted.--site-business-type store|bookings|otheris valid only with--site-type harmony. It records the business context for the run; it does not change how the site is created: Harmony always starts from the blank template (Harmony site generation is not used).- Before the first Studio or Harmony site is created, a request shows the account the Wix CLI is logged into and the site name; nothing is created until that account is confirmed.
- Destination recovery requests (uncertain creation, editor or publication checks) are answered like any other request; an answer only triggers one new bounded check, never a second site. RePlatform never publishes or unpublishes an Editor site.
Safety and recovery
Every run writes a run ID before it launches an agent. A run is not complete because an agent
said so: aggregate completion receipts must validate. Cancellation is a durable state change;
it requests graceful shutdown before forced termination, never labels a partial import as
completed, and preserves recovery artifacts for a later replatform resume.
A run stopped on a blocker (run.json status: blocked) stays stopped: run ends with the
run_blocked route and its resumeFrom, ahead of pending questions. answer --continue
records the answer but does not release this hold. Resolve the blocker, then
replatform resume <project> sets the status back to running and routes again;
orchestration-state.js transition --state <state> --phase <phase> --status running
also releases it. Transitions without --status preserve the hold.
The final JSON includes router.resumeFrom, router.resumeWith, and a typed blocker
with its artifact, owner and required input; text output displays the note and next action.
Stop transitions persist the blocker in orchestration/run.json. A legacy hold without a
reason stays held with run_blocked_details_required; its runner result durably records
the instruction to supply the reason, evidence and attempted recovery before resuming.
Missing recovery history is null, never an invented successful retry. Held route/run
checks leave telemetry waits open and do not create execution sessions.
Run replatform doctor to check available adapters and local prerequisites without printing
credentials.
With --agent auto, the runner follows the invoking Codex or Claude Code session when that
environment is detectable. Otherwise it selects an installed and authenticated adapter and
records the selected adapter and reason in the runner events and receipt. An explicit
--agent codex or --agent claude always wins.
replatform account reports the identity returned by the local wix whoami command. It is a
live check, not a migration artifact: confirm that identity is authorized before acknowledging a
destination-creation action.
Local browser console
replatform-console is an optional loopback-only browser control surface for this CLI:
node <bundle>/scripts/replatform-console.jsIt prints a tokenized 127.0.0.1 URL. Keep that URL private: its token authorizes local
control requests. The console starts the same non-interactive CLI commands, renders the
persisted work state alongside the normalized event stream, presents durable human actions, and reads only artifacts that show
already permits. It never accepts credentials or exposes vendor diagnostics. --port <port>
chooses a port; the server refuses any non-loopback host.
The Work panel reads state/runner/task-state.json through replatform tasks, so it survives
console reloads and restarts. It records router work and direct agent processes; extra workers
appear only when an adapter reports their structured topology, including a visible Starting
state while a vendor sub-worker is initializing. The observed activity feed remains diagnostic
evidence and never marks work complete by itself.
For destination-creation acknowledgements, the console also displays the identity reported by the local Wix CLI and requires that check to succeed before it enables acknowledgement. The identity is shown only in the token-protected dialog and is never saved to migration artifacts.
For reconnectable consumers, tail --since <event-id> replays events strictly after that
event. tail --since <duration> uses an inclusive time window. show --format json returns
the declared artifact media type plus cursor/nextCursor byte offsets for bounded reads, and
projects --format json lists valid migration projects under the configured migrations root.