MoveStack Help

Free preview first, licensed restore when it matters

MoveStack lets you scan, run doctor, create deploy snapshot previews, list snapshots, monitor and watch for free. Full backup, deploy, clone and restore run are licensed restore commands.

Getting startedFree vs licensedWorkflowsTargetsTroubleshootingAdvanced
Fast path
movestack scan
movestack doctor . --to staging
movestack snapshot create .

Start with the free preview path. Activate when you need the licensed restore path: full backups, deploy, clone or restore run.

Short version

Free preview first, licensed restore when you need real recovery

free preview
movestack scan
movestack doctor . --to staging
movestack snapshot create .
licensed restore
movestack activate <token> --issuer https://movestack.dev
movestack snapshot create . --mode full-backup
movestack deploy local/full-backup/my-app@... --to ssh:[email protected]:/srv/apps --target-subdir my-app --watch

Free vs Licensed

Free preview is for understanding; licensed is for restore value

Core now enforces this split. Free commands do not require activation. Licensed commands require entitlement, and deploy, clone and restore run also require a signed plan.

Free preview

Understand the product shape before buying. These commands do not require activation, entitlement or signed plans.

movestack scan
movestack doctor . --to staging
movestack snapshot create .
movestack snapshot list
movestack monitor staging
movestack watch staging
ScanDoctorDeploy snapshot previewSnapshot listMonitorWatch

Licensed restore flow

The restore value is licensed. Full backup needs entitlement; deploy, clone and restore run also need a signed plan.

movestack activate <token> --issuer https://movestack.dev
movestack snapshot create . --mode full-backup
movestack deploy local/full-backup/my-app@... --to ssh:[email protected]:/srv/apps --target-subdir my-app --watch
movestack clone prod --to staging --watch
movestack restore run ...
Full backup snapshotsDeployCloneRestore run

Getting Started

Start free, activate for licensed restore

The free preview path helps you understand the app and target. The licensed restore flow starts when you need full backups, deploy, clone or restore run.

1

Start free preview

Scan is free. Use it to understand the detected app, runtime and database shape before licensing.

movestack scan
2

Run doctor for a target

Doctor is free. It checks workload and target readiness without changing the target.

movestack doctor . --to staging
3

Create a deploy snapshot preview

Deploy snapshot preview is free. It is not the same thing as a full backup.

movestack snapshot create .
4

Activate once

Activation is required for full-backup, deploy, clone and restore run.

movestack activate <token> --issuer https://movestack.dev
5

Create a licensed full backup

Full-backup requires a license entitlement with snapshot_full_backup.

movestack snapshot create . --mode full-backup
6

List snapshots

Snapshot list is free and shows available deploy snapshots and backups.

movestack snapshot list
7

Deploy to staging

Deploy requires a license, entitlement and signed plan. Use the parent target path together with --target-subdir when one host carries multiple apps.

movestack deploy local/full-backup/my-app@... --to ssh:[email protected]:/srv/apps --target-subdir my-app --watch
8

Monitor the target

Shows current status after deploy or clone: service, healthcheck, proxy and public URL state.

movestack monitor staging
free preview
scan, doctor and deploy snapshot
doctor
checks readiness without changes
full-backup
licensed real backup
snapshot list
finds restorable snapshots
monitor
shows target state

Common Workflows

The commands operators use most

Use environment names like prod and staging. Think in environments first, transport second. On SSH hosts, keep the parent path separate from --target-subdir.

Backup this app

movestack snapshot create . --mode full-backup

Use full-backup when you need a real backup you can restore later.

Deploy to a target subdir

movestack deploy <snapshot-or-archive> --to ssh:[email protected]:/srv/apps --target-subdir my-app --watch

Deploy restores a snapshot or exported .tar.gz archive into a target environment. Use the parent host path and keep the app path in --target-subdir.

Clone prod to staging

movestack clone prod --to staging --watch

Clone copies one named environment into another, including app, database, environment and runtime state.

Watch deployment progress

movestack watch staging

Watch polls the same live state as monitor until the target is ready. It also tolerates transient SSH poll failures while the target is still converging.

Monitor a target

movestack monitor staging

Monitor shows the current state for service, healthcheck, proxy and public URL.

Auth and licensing

One activation command is enough for normal use

After activation, protected commands automatically fetch the entitlement and signed plan they need. Issuer auth can use bearer token or Basic Auth, but that is an operator detail.

movestack activate <token> --issuer https://movestack.dev
movestack auth status
movestack auth logout

Environment Targets

Use prod and staging as named environments

Targets can be local-backed or SSH-backed. They can carry host, parent path, source or target role, domains, database overrides, deploy overrides and an app-specific --target-subdir at deploy time.

prod
usually the source environment
staging
usually the target environment
parent path
the shared host path for the SSH target, for example /srv/apps
--target-subdir
the app-specific directory beneath the parent path, for example my-app
domain / domains[]
primary domain plus optional domain list
auto www
www.<primary-domain> is added for the primary domain

Target Config

Example environment target config

Remote is the transport. The user-facing model is the environment target.

movestack targets
{
  "targets": {
    "prod": {
      "type": "ssh",
      "host": "203.0.113.10",
      "path": "/srv/my-app",
      "role": "source",
      "domain": "example.com"
    },
    "staging": {
      "type": "ssh",
      "host": "108.181.66.218",
      "path": "/srv/my-app-staging",
      "role": "target",
      "domains": ["staging.example.com"],
      "database": {
        "name": "my_app_staging"
      }
    }
  }
}

Concepts

The core terms

These distinctions match how the CLI and core behave today.

Snapshot vs backup

Snapshot is the general restore unit. --mode full-backup is the real backup mode. --mode deploy creates a redeployable snapshot.

Deploy vs restore

Deploy is the user-facing restore command. restore dry-run and restore run are advanced/debug commands.

Monitor vs watch

Monitor shows current live state. Watch polls that same state until the target is ready, and it tolerates transient SSH poll issues during rollout.

Parent path vs target subdir

Use the parent target path for the shared host location and --target-subdir for the app-specific directory. This keeps one host usable for multiple apps and staging targets.

Doctor

Doctor checks workload and target readiness before deploy or clone. It reports missing packages, provisioning options and worker or cron signal state.

React/Vite preview runtime

Preview deployments for React or Vite style apps can now come up under the preview runtime by using vite preview when the app shape matches that runtime.

Worker and cron signals

Worker and cron workloads can expose heartbeat and last-success files so doctor can report not_configured, missing, stale or ok.

Status

What to watch during deploy or clone

Doctor, monitor and watch use direct status language so failures point to the right layer.

Runtime status

StatusTargetVerifyProgressProxyUpstreamPublic URLServiceHealthcheck

Doctor checks

StatusWorkloadSnapshot readinessTarget preflightTarget readinessMissing capabilitiesProvisioningCron signal status
Proxy, domains and verification
domain / domains[]
targets can define a primary domain or a domain list
www primary
www.<primary-domain> is added automatically
fallback host
SSH targets without a domain can fall back to host/IP
collision guard
existing site configs are not overwritten
fingerprint verify
database fingerprint verify checks restored data
Debian / AlmaLinux
current host validation covers Debian 12 and AlmaLinux
React / Vite preview
The preview runtime can now bring up React and Vite style apps with vite preview.
Worker and cron readiness

Doctor can report cron signal state

Cron components can write heartbeat and last-success signal files. Doctor uses those files to tell whether a scheduled workload is configured, missing, stale or healthy.

not_configuredmissingstaleok
Default heartbeat
.movestack/cron/<component>/heartbeat
Default last success
.movestack/cron/<component>/last-success
Optional age limits
heartbeat_max_age_seconds and last_success_max_age_seconds
Go helper API
pkg/signals.DefaultCronPaths, WriteHeartbeat and WriteLastSuccess

Troubleshooting

Common auth, SSH and readiness failures

Start with activation, then the signed plan, then the live monitor state, and only then SSH trust and target prerequisites.

Activation required

  • Run movestack activate <token> --issuer https://movestack.dev before protected commands.

Revoked license

  • The current license is revoked. Fetch a valid activation or contact the issuer.

Signed plan mismatch

  • The requested deploy, clone or restore run was not authorized for this target or snapshot.

Deploy looked failed but the app is already up

  • Run movestack monitor <target> to inspect the live target state before you assume the rollout failed.
  • If monitor shows Status: ready, Services: ok and Healthcheck: ok, treat the target as usable even if an earlier deploy report looked failed.
  • The earlier output may have captured a stale intermediate state. Monitor is the final source of truth for the current target.

SSH host key mismatch

  • The VPS may have been rebuilt.
  • Use the CLI-provided known_hosts cleanup and key scan commands.

SSH works from one runner but not another

  • Check source-IP allowlists, firewalls, NAT policy and VM egress rules before you assume the target itself is broken.
  • Current core output distinguishes real SSH timeouts from the older generic killed-process symptom, so read the timeout detail literally.

Doctor readiness failure

  • The target is missing required packages.
  • Re-run with provisioning enabled or install the reported packages first.

Advanced Commands

Keep low-level restore and license commands separate

These commands are real, but they are operator/debug paths rather than the main help flow.

Restore dry-run

movestack restore dry-run ...

Preview the lower-level restore plan for debugging.

Restore run

movestack restore run ...

Run the lower-level restore path directly when operator debugging requires it.

License internals

movestack license entitlement fetch ...

Low-level issuer commands are useful for debugging, but normal protected commands fetch entitlement and signed plans automatically.

License fetch

movestack license fetch ...

Fetch raw license data when debugging issuer connectivity.

Signed plan issue

movestack license plan issue ...

Issue a signed plan manually when validating issuer and entitlement behavior.

Feature Coverage

Current core coverage reflected on this page

These are the current help-page background capabilities from the core handoff.

Backup and archive

  • local snapshot / full-backup
  • local restore / verify
  • archive export / import
  • deploy from snapshot or .tar.gz archive

Targets and hosts

  • remote deploy to SSH targets
  • Debian 12 and AlmaLinux host validation
  • multi-site nginx on the same host
  • domain + domains[] with auto www primary domain

Verification and config

  • database fingerprint verify
  • multiline PEM / env file-ref support
  • doctor readiness checks
  • remote monitor / watch

License enforcement

  • activate / auth status / auth logout
  • issuer profiles
  • entitlement refresh
  • signed plan auto-fetch
  • hard enforcement for protected commands
Need help or have feedback?

Report bugs, request features or share your setup

Submit feedback
MoveStack Help and CLI Documentation | MoveStack