Upgrade Putnami

You want to keep Putnami up to date — the CLI, extensions, and framework dependencies in your projects.

One command

putnami upgrade

This upgrades everything from the stable channel in sequence:

CLI — downloads the latest release binary and refreshes shell completions for your current shell
Extensions — resolves latest compatible versions of @putnami/typescript, @putnami/go, @putnami/python, etc.
Templates — updates workspace templates
Framework dependencies — pins @putnami/* packages (TypeScript), go.putnami.dev/* modules (Go), and Python framework packages to the selected release set
Workspace installers — materializes lockfiles and workspace state (bun install, go work sync, uv lock, etc.)

Use --dry-run first when you want to inspect the resolved release before any file is changed:

putnami upgrade --channel canary --dry-run

The output shows what changed at each step:

  Putnami upgrade plan
  Selector: stable (channel)

  CLI
  Already up to date (1.2.0)

  Extensions
  ↑ @putnami/typescript: 1.2.0 → 1.3.0
  ✓ @putnami/go@2.1.0 (up to date)

  Templates
  ✓ typescript-web@1.0.0 (up to date)

  Dependencies
  Pinned go.work replace go.putnami.dev/app => go.putnami.dev/app v1.2.0
  Pinned @putnami/application: 1.1.0 -> 1.2.0

Select a release set

You normally select a release channel rather than typing a commit-derived version:

putnami upgrade                    # stable channel
putnami upgrade --channel stable   # same as the default
putnami upgrade --channel canary   # latest canary
putnami upgrade --branch feature-x # latest build published for a branch tag
putnami upgrade --version 1.2.3    # exact version for CI or rollback

stable maps to the registry's latest tag. --putnami-version is still accepted as a legacy alias for --version. Branch selectors consume tags created by putnami publish --also-branch-tag; branch names are normalized the same way during publish and upgrade, so feature/foo resolves through the feature-foo tag.

For Go workspaces, the selected release is written to root go.work as replace directives:

replace (
    go.putnami.dev/app => go.putnami.dev/app v1.2.0
    go.putnami.dev/http => go.putnami.dev/http v1.2.0
)

For TypeScript workspaces, the framework version lives in the Bun catalog — the single source of truth. Packages reference @putnami/* with the catalog: protocol, and putnami upgrade --deps pins the selected release in the catalog:

{
  "workspaces": ["packages/*"],
  "catalog": {
    "@putnami/application": "1.2.0",
    "@putnami/web": "1.2.0"
  }
}

// packages/web/package.json — consumers reference the catalog
{
  "dependencies": {
    "@putnami/application": "catalog:",
    "@putnami/web": "catalog:"
  }
}

The catalog is updated in place:

Non-Putnami catalog entries (react, react-dom, @types/react, …) are preserved.
No duplicate root dependencies or overrides are introduced — the catalog is the only version policy. Any leftover @putnami/* entries in root dependencies/overrides are removed.
A package referenced with catalog: but missing from the catalog is added automatically, so bun install always resolves.

Bun also accepts the catalog nested under workspaces.catalog; the upgrade updates whichever placement your workspace uses. A workspace that predates catalog support (no catalog declared) falls back to exact-pinned root dependencies and overrides.

Local workspace packages are left alone. For example, a Putnami framework checkout that has @putnami/web or go.putnami.dev/http locally will keep using the local package instead of replacing it with a registry version.

If the workspace enables the @putnami/cloud extension, the dependency phase also manages the npm @putnami/cloud runtime package and pins it to the selected release. This keeps cloud runtime sources current even when no project has added the package yet.

Upgrade specific layers

Use flags to upgrade only what you need:

putnami upgrade --cli          # Only the CLI binary
putnami upgrade --extensions   # Only extensions and templates
putnami upgrade --deps         # Only framework dependencies

Upgrade the global CLI

Inside a workspace, putnami upgrade updates the CLI version pinned for that workspace (.putnami/bin/). To update the global install in ~/.putnami/bin/ — the one the install script created — pass --global:

putnami upgrade --global                   # global CLI + the regular workspace upgrade
putnami upgrade --global --cli             # global CLI only
putnami upgrade --global --channel canary  # same, from the latest canary

--global retargets the CLI phase at the global install and replaces re-running the install script. Inside a workspace, the remaining phases — extensions, templates, and dependencies — still run, exactly like a plain putnami upgrade. Outside a workspace it upgrades the CLI binary and shell completions only (no workspace required). The release selectors (--channel, --branch, --version) work the same as for a workspace upgrade. You only need install.sh for the first install on a machine.

After upgrading

Verify everything still works:

putnami lint,test,build --impacted

If the upgrade included breaking changes, the build or test output will surface what needs updating. Use --output=jsonl for structured diagnostics if you need to pinpoint exact failures.

If you use zsh and completions still look stale after a CLI upgrade, clear zsh's completion cache and restart the shell:

rm -f ~/.zcompdump*
exec zsh

Low-level commands

The putnami upgrade command orchestrates these individual commands, which you can also run directly:

What	Command
CLI binary	`putnami upgrade --cli` (or `--global` for the global install)
Extensions	`putnami extensions update`
Templates	`putnami templates update`
Dependencies	Handled by extension `deps-upgrade` jobs

To switch the active CLI to an exact release, pass --version:

putnami upgrade --cli --version 1.2.3      # workspace pin
putnami upgrade --global --version 1.2.3   # global install

You now have a fully updated Putnami workspace — CLI, extensions, and project dependencies.