Upgrade
upgrade is the verb that moves a project to the latest toolchain.
bunx @defold-typescript/cli@latest upgradeTip
update is a synonym — both spellings run the same verb, so you never have to
remember which one this CLI chose.
What it does
upgrade always resolves the latest published @defold-typescript/cli from the
npm registry first, then branches on how it compares to the CLI that is running:
- The running CLI is behind — it hands off to the newer one, which re-scaffolds the project in place. An older binary must never re-scaffold from its own templates: it would exit successfully while moving the project backwards.
- The running CLI is already the latest — it re-scaffolds in place directly, with no hand-off.
Either entry point therefore lands on the same place — the latest templates and
the latest pins — whether you invoke @latest from outside the project or the
copy already installed in it. The re-scaffold is init --force, and the verb
finishes by running your package manager's install so the refreshed pins are
actually on disk.
The summary line reads <from> -> <to>, where <from> is the
@defold-typescript/cli version the project had before the run and <to> is the
resolved latest. It adds (already latest; re-scaffolded managed files) only when
the project was already on <to>, and reads none -> <to> when no earlier version
is found.
What it refreshes, and what it never touches
The re-scaffold refreshes the managed files: it re-pins the managed
@defold-typescript/types and @defold-typescript/cli devDependencies to the new
CLI's version, refreshes the managed mise.toml task block and the managed
AGENTS.md block, and reconciles tsconfig.json, adding noEmit: true when the
project sets none. Configs are edited in place, so comments, layout and keys such
as extends, references and files survive, and a setting inherited through
extends counts as set. A project with no src/test/tsconfig.json gets the
Bun test config init writes; an existing one that extends
the root gains each missing setting and has its include and exclude brought
in step with the root's, and src/test joins the root exclude when no entry
names it. Each of those edits, an installed Bun that is older than the CLI's
bun-types pin or differs from the project's exact pin, and a test/ or tests/
folder holding Bun tests is reported in warnings; see
Test with Bun. If .vscode/defold-debug.ts
already exists and its normalized checksum matches a generated launcher — including
an unmodified legacy launcher whose line endings became CRLF — it is refreshed too.
An absent launcher stays absent.
It never clobbers files you authored. An entry script you have written —
src/main.ts — is left exactly as it is; the scaffold reports it as skipped
rather than overwriting it. Notes you keep outside the AGENTS.md markers, your
own [tools] and [tasks.*] entries in mise.toml, and your other
tsconfig.json settings all survive the upgrade untouched. Inside a managed
mise.toml task the refresh rewrites only the two keys the scaffold authors —
description and run — so a key you added there, such as an alias or a
depends, survives too. The upgrade never touches defold-typescript.lock either;
only resolve writes it.
What it does to your defold-target pin
The upgrade repairs the defold-typescript namespace in package.json rather
than resetting it:
- A valid
defold-targetpin is left untouched — it round-trips byte for byte, so upgrading the toolchain never silently moves your Defold API surface. - A legacy
defold-versionorchannelkey is migrated todefold-target, keeping its value, and you get a warning naming the key that moved. - If both a legacy key and a valid
defold-targetare present, the legacy key is dropped and thedefold-targetpin wins. - A project with no pin at all has
defold-targetseeded with the current stable version.
Upgrading the toolchain and moving the Defold API surface are separate decisions. See Pinning the Defold target for the pin's own lifecycle — how to choose a version or a release channel, and how the surface is materialized.
Flags
--json— emit the upgrade result as a single JSON object for agents and scripts. See Agent runbooks.
Pass --json when a script or an agent runs the upgrade:
bunx @defold-typescript/cli@latest upgrade --json{
"command": "upgrade",
"ok": true,
"written": ["package.json", "tsconfig.json", "..."],
"from": "0.4.1",
"to": "0.5.0",
"handedOff": true
}from is the @defold-typescript/cli version the project had before the
upgrade — the installed copy in node_modules, else the version in its
package.json pin — and is absent when neither exists. to is the resolved
latest, and handedOff says whether a newer CLI did the re-scaffold.
written lists the managed files the re-scaffold touched. When handedOff is
true it is the list the newer CLI reports for the re-scaffold it performed,
read back from the delegated run; when handedOff is false it is the running
CLI's own list. If a launcher checksum is unknown, the upgrade still succeeds:
warnings names .vscode/defold-debug.ts and says it was preserved, and that path
is absent from written. Delete the file and run defold-typescript setup-debug
to replace a customized launcher explicitly.
Upgrading is the one command that needs the network. If the registry is
unreachable, the run fails — ok is false with a non-zero exit — rather than
quietly re-scaffolding against the version you already have. See the
upgrade runbook for the agent-facing
procedure.
As a mise task
The scaffold writes this verb as a mise task, so once your project's mise.toml
is on disk the same upgrade is reachable as:
mise run # and pick defold-typescript:upgrade
# or
mise run defold-typescript:upgradeThe task carries no version tag, so mise runs the @defold-typescript/cli that
init pinned as a devDependency — the same version bunx would
resolve with @latest.