hs app migrate vs hs project migrate

Do not choose between `hs app migrate` and `hs project migrate` from memory. Start by inspecting the app: does the repo have `hsproject.json`, what `platformVersion` is recorded, and is the app public, Marketplace-oriented, project-based, or private? Confirm the latest CLI first; the current 2026.03 migration page recommends CLI 8.4.0 or above.

Use the current 2026.03 matrix: a project already on 2025.2 updates top-level `hsproject.json` from `platformVersion` 2025.2 to 2026.03 and runs `hs project upload`; a project on 2023.1, 2023.2, 2025.1, or predating platform versions runs `hs project migrate` from the project working directory; an existing non-project legacy public app uses `hs app migrate` from the parent directory where the new project should be downloaded.

A legacy non-project private app cannot currently migrate to 2026.03 through this path. Stop and use the private-app planning guide rather than substituting a public-app command. Also treat the older public-migration page as feature/limitation evidence, not the authority for the latest target version, because that live page still contains 2025.2 wording while the latest-platform page defines the 2026.03 routes.

Inspect the repository root for `hsproject.json`, then record `platformVersion`. Also find the app configuration files, including `app-hsmeta.json` where relevant, and list any serverless functions, app cards, OAuth settings, webhooks, scopes, and Marketplace listing dependencies.

For an existing public app, check active installs and test-install implications before migration. For a project app, understand whether the work is a platform-version update or a broader feature migration. For a private app, capture backend and token implications because the public-app migration decision tree does not automatically apply.

Write down the command as a path to verify, not a command to run immediately. The final pre-run step should be opening the relevant official HubSpot docs and confirming they still match the local source archive.

For `hs app migrate`, expect prompts to select the app, confirm compatible components, provide a project name and local path, and set required UIDs. The documented successful operation creates the HubSpot project, converts supported features to source files, builds and deploys Build #1, downloads the new local project, and, when an existing project is migrated, moves the prior `src` files into `archive` before populating the new `src`.

Before making follow-up changes, confirm the new project exists locally and in HubSpot, preserve UID values, record Build #1, open Builds & Deploys, and test existing authentication, installs, and supported features. HubSpot documents Build #1 as the baseline that can be redeployed to revert later project changes; that is a recovery point for later builds, not permission to skip pre-migration backups or feature testing.

If serverless functions used `environment` entries in legacy `serverless.json`, the current 2026.03 guide says those variables are not migrated automatically; recreate them as secrets with the documented `hs secret add` flow before testing functions. If the app has v1/v3 timeline events, move occurrence requests to v4 within seven days because the older endpoints then return 401. Do not schedule migration until that backend cutover has an owner and test window.

Wrong turn 1: using `hs project create` for an existing app modernization project. That command belongs to new Projects-based app creation, while migration paths require a separate review.

Wrong turn 2: treating every older project app as a non-project legacy public app. If `hsproject.json` exists, inspect platform-version guidance before selecting a migration path.

Wrong turn 3: promising automatic private app migration. Private app cases have documented limitations and may need manual planning or a net-new app approach depending on features.