CLI Reference

The primary binary is hostshift. Migration behavior lives in the Go CLI; there is no Node migration runtime or compatibility entrypoint.

All commands that can mutate the target default to dry-run mode unless --apply is passed.

Global Behavior

HostShift uses system OpenSSH. Set HOSTSHIFT_SSH_CONFIG when tests or automation need a temporary SSH config:

HOSTSHIFT_SSH_CONFIG=/tmp/hostshift-ssh-config hostshift plan --profile profile.yaml --target new-server --json

Target commands can be wrapped with non-interactive sudo by setting HOSTSHIFT_TARGET_SUDO=1. Source commands are never sudo-wrapped by HostShift.

version

Prints the CLI version.

hostshift version

doctor

Validates source and target SSH aliases and prints the active source-safety contract.

hostshift doctor --source old-server --target new-server --json

Important output fields:

• sourceWillBeModified: false
• sourcePolicy: strict-read-only
• version
• source
• target

discover

Reads allowlisted facts from the source and writes a v2 profile with safe workload candidates.

hostshift discover \
  --source old-server \
  --name customer-migration \
  --profile customer-migration.profile.yaml \
  --json

Required flags:

• --source: SSH alias for the source.
• --name: profile name.

Optional flags:

• --profile: output path. Defaults to <name>.profile.yaml.
• --json: machine-readable output.

discover fails if a required fact cannot be read. Optional facts are preserved in output with their error so operators can decide whether they matter for the migration. Generated workload candidates still require operator review before approved: true.

plan

Builds the action and stream plan from a profile.

hostshift plan --profile examples/web-stack-v2.yaml --target new-server --json

Required flags:

• --profile: v1 or v2 profile path.

Optional flags:

• --target: override the target SSH alias in the profile.
• --json: machine-readable output.

The plan contains:

• actions: local or target commands grouped by phase.
• streams: source-to-target data streams for file, image, and database movement.
• blockers: conditions that prevent apply.
• warnings: non-blocking risks, for example cross-distribution compatibility warnings.
• sourceWillBeModified: false.

explain

Builds the same plan and returns an AI-friendly review summary without applying anything.

hostshift explain --profile examples/web-stack-v2.yaml --target new-server --json

Required flags:

• --profile: v1 or v2 profile path.

Optional flags:

• --target: override the target SSH alias in the profile.
• --json: machine-readable output.

The explanation contains blocker and warning summaries, workload and stream counts, target impact counts, safe next actions for a human operator, and source safety notes for AI clients.

review

Builds the same plan and returns structured migration findings for AI-assisted profile review without applying anything.

hostshift review --profile examples/web-stack-v2.yaml --target new-server --json

Required flags:

• --profile: v1 or v2 profile path.

Optional flags:

• --target: override the target SSH alias in the profile.
• --json: machine-readable output.

The review output contains:

• status: blocked, needs-review, or ready-for-dry-run
• findings: blocker, warning, and info records with workload-aware recommendations
• findings[].suggestedProfilePatch: optional YAML snippet that an operator can review and adapt
• operatorChecklist: human review steps before any apply command
• aiBrief: constraints AI clients must follow, including no MCP apply operations
• sourceWillBeModified: false

review checks for missing evidence such as container workloads without HTTP/application checks, databases without scalar verification, service workloads without serviceActive, Nginx config transfer without nginxConfig, and database workloads that may need secret environment variable names.

Suggested snippets are advisory. HostShift does not write them into the profile automatically, and AI clients should present them for human review instead of applying them.

prepare

Plans or applies target preparation actions.

hostshift prepare --profile profile.yaml --target new-server --json
hostshift prepare --profile profile.yaml --target new-server --apply --state-dir .hostshift --run-id prep-001 --json

Typical prepare actions:

• install target package capabilities through the platform adapter
• write target UFW rules
• write target OpenSSH keepalive drop-ins
• write target MySQL bind-address drop-ins
• validate Docker Compose configuration
• disable the default Nginx site when Nginx config is migrated

sync

Plans or applies data streams.

hostshift sync --profile profile.yaml --target new-server --json
hostshift sync --profile profile.yaml --target new-server --apply --state-dir .hostshift --run-id sync-001 --json

Sync streams are validated source read commands piped into validated target write commands. Examples:

• tar --create into tar --extract
• docker image save into docker image load
• mysqldump into mysql
• pg_dump into pg_restore

verify

Plans or applies target-side verification checks.

hostshift verify --profile profile.yaml --target new-server --json
hostshift verify --profile profile.yaml --target new-server --apply --state-dir .hostshift --run-id verify-001 --json

Verification actions run only on the target. They cover HTTP health, Laravel DB connectivity, file assertions, database scalar assertions, service status, firewall rule checks, and Nginx config validation.

cutover

Plans or applies target-only cutover actions.

hostshift cutover --profile profile.yaml --target new-server --json
hostshift cutover --profile profile.yaml --target new-server --apply --confirm START-MIGRATION --state-dir .hostshift --run-id cutover-001 --json

Dry-run output includes:

• confirmationCode
• sourceWillBeModified: false
• target-only cutover actions such as docker compose up -d --build and standalone docker run

Apply refuses blockers and requires the exact confirmation code. DNS remains manual.

rollback

Reports rollback guidance and target rollback metadata.

hostshift rollback --profile profile.yaml --json

Rollback output always states sourceChanged: false because HostShift never mutates the source. Automatic rollback is intentionally disabled; operators should keep DNS on the source and inspect target-side rollback metadata before stopping target services.

capabilities

Prints a local catalog for AI clients and operators without connecting to source or target hosts.

hostshift capabilities --json

The report includes supported releases, target package capability mappings, workload types, check types, source fact names, and AI safety guidance. It always reports sourceWillBeModified: false and applyToolsExposed: false.

mcp stdio

Runs the HostShift MCP server over stdin/stdout for AI clients.

hostshift mcp stdio

The MCP server exposes discovery, planning, explanation, structured review, dry-run, cutover dry-run, local profile migration, source policy introspection, capability catalog inspection, and rollback metadata tools. It also exposes the hostshift_migration_operator prompt and local hostshift://source-safety, hostshift://migration-workflow, and hostshift://capabilities resources. It does not expose apply tools.

mcp doctor

Validates the MCP tool surface and Claude Desktop config example without running remote commands.

hostshift mcp doctor --json
hostshift mcp doctor --claude-config integrations/claude/claude_desktop_config.example.json --json

The report includes protocol version, exposed tool, prompt, and resource names, whether any apply tool is exposed, and whether the Claude config points to hostshift mcp stdio.

profile migrate

Reads a v1 profile and writes a v2 profile.

hostshift profile migrate --input examples/profile.yaml --output profile.v2.yaml

The migration maps v1 composeProjects, standaloneContainers, fileSets, databases, healthChecks, and applicationChecks into v2 workloads and checks.

status

Reads saved run state.

hostshift status --state-dir .hostshift --run-id sync-001 --json

State lives at:

<state-dir>/runs/<run-id>/state.json

If --state-dir is omitted, HostShift uses HOSTSHIFT_STATE_DIR or the OS user config directory.

Phase commands return the effective runId; when --run-id is omitted, HostShift generates one before writing state.

resume

Loads a run state, rebuilds the phase plan, verifies its fingerprint, and reports completed and pending steps without changing state.

hostshift resume \
  --profile migration.profile.yaml \
  --state-dir .hostshift \
  --run-id sync-001 \
  --json

Continue only the pending steps:

hostshift resume \
  --profile migration.profile.yaml \
  --state-dir .hostshift \
  --run-id sync-001 \
  --apply \
  --json

Resume refuses changed profiles, targets, blockers, or generated commands. Completed action and stream IDs are not replayed. State is persisted atomically before and after every remote operation.

When an operation failed or the process stopped while it was running, HostShift treats that action as potentially partial. Preview the run first, inspect the target, then explicitly confirm the exact retry:

hostshift resume \
  --profile migration.profile.yaml \
  --state-dir .hostshift \
  --run-id sync-001 \
  --apply \
  --retry-failed target.workload.mysql.app.dump \
  --json

Cutover resume also requires the normal --confirm <code> value. Runs created before plan fingerprints were introduced cannot be resumed safely; start a new phase run instead.

policy source

Prints the source policy contract.

hostshift policy source

Forbidden source-side behavior includes sudo, package installation, service management, file writes, snapshot creation, maintenance mode, and firewall changes.

sbom

Writes an SPDX 2.3 JSON SBOM from the Go module graph.

hostshift sbom --output dist/hostshift.sbom.spdx.json --json

Optional flags:

• --output: output path. Defaults to dist/hostshift.sbom.spdx.json.
• --json: machine-readable summary output.

matrix docker

Lists or explains the Docker integration matrix without running containers.

hostshift matrix docker --list
hostshift matrix docker --list-images
hostshift matrix docker --pair 'ubuntu22->debian12' --json

Optional flags:

• --list: list source and target pairs.
• --list-images: list unique fixture base images.
• --pair: filter to one pair such as ubuntu22->debian12; quote it in shells because > is a redirection operator.
• --json: machine-readable output.

Real Docker execution still uses HOSTSHIFT_RUN_DOCKER_MATRIX=1 make test-integration-docker.

docker-e2e

Runs the Go-backed Docker integration runner used by tests/integration/docker/run-matrix.sh.

hostshift docker-e2e --list
hostshift docker-e2e --list-images
hostshift docker-e2e --pair 'ubuntu22->debian12'
HOSTSHIFT_RUN_DOCKER_MATRIX=1 hostshift docker-e2e --pair 'ubuntu22->debian12'

Optional flags:

• --list: list source and target pairs.
• --list-images: list unique fixture base images.
• --pair: filter to one pair. Quote values containing >.
• --pull-images: pre-pull required fixture base images.

matrix vm

Lists or explains the real VM e2e matrix without booting VMs.

hostshift matrix vm --list
hostshift matrix vm --pair 'ubuntu22->debian12' --json
hostshift matrix vm --provider lima --json

Optional flags:

• --list: list source and target pairs.
• --pair: filter to one pair such as ubuntu22->debian12; quote it in shells because > is a redirection operator.
• --provider: VM provider. Currently lima.
• --json: machine-readable output.

Real VM execution still uses HOSTSHIFT_RUN_VM_E2E=1 make test-e2e-vm for provider preflight and HOSTSHIFT_RUN_VM_E2E=1 bash tests/e2e/vm/run-vm-e2e.sh --apply for the apply workflow.

vm-e2e

Runs the Go-backed VM e2e runner used by tests/e2e/vm/run-vm-e2e.sh.

hostshift vm-e2e --list
hostshift vm-e2e --pair 'ubuntu22->debian12' --emit-dir /tmp/hostshift-vm
HOSTSHIFT_RUN_VM_E2E=1 hostshift vm-e2e --pair 'ubuntu22->debian12' --apply

Optional flags:

• --list: list source and target pairs.
• --pair: filter to one pair. Quote values containing >.
• --provider: VM provider. Currently lima.
• --emit-dir: write rendered workspaces under a chosen directory.
• --apply: boot VMs and run the live HostShift workflow when HOSTSHIFT_RUN_VM_E2E=1 is set.