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:

1. CLI — downloads the latest release binary and refreshes shell completions for your current shell
2. CLI handoff — when a new CLI was installed, continues the remaining phases under that verified binary
3. Extensions — resolves latest compatible versions of installed extensions. @putnami/python remains an explicit experimental opt-in, not a default upgrade target.
4. Templates — updates workspace templates
5. Framework dependencies — pins @putnami/* packages (TypeScript) and go.putnami.dev/* modules (Go) to the selected release set. Python has no Putnami framework package release set; an explicitly enabled Python extension upgrades that workspace's own uv-resolved dependencies.
6. 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
)

The upgrade also reconciles the framework modules present in the workspace's final Go dependency graph. That means newly introduced transitive modules get matching go.work replacements, malformed prerelease tails are normalized to the selected release, and any managed exclude of that exact release is removed before dependency resolution.

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 only. A same-version override duplicating a direct dependency is redundant npm EOVERRIDE bait, so redundant @putnami/* overrides are stripped rather than written — the direct dependency is the sole version policy, consistent with the catalog path.

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.

Enabling the @putnami/cloud extension does not, by itself, pin the npm @putnami/cloud package. The extension is resolved through the lock/artifact-store path, and its optional @putnami/cloud/runtime package is loaded lazily with graceful degradation when absent — so a hoisted root install is not needed for compile or build. @putnami/cloud is managed only when a project actually declares it as a dependency. If an app imports @putnami/cloud/runtime (for a remote config or secrets source), add @putnami/cloud to that app's own dependencies; putnami upgrade --deps then pins it to the selected release like any other referenced package.

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 active CLI in .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 — what it verifies and how it reaches your PATH is in Getting Started.

If putnami.lock.json pins a workspace CLI, that pin is not changed by upgrade: it is a committed trust decision. A full upgrade hands its remaining phases to the freshly verified binary to avoid mixing a new extension with an older engine, then warns when later commands would return to a different pin. To adopt the new CLI for ordinary workspace commands, run putnami pin <version> deliberately and add a digest from each platform your team uses.

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

Go workspace and standalone dependency metadata

For Go projects, the root go.work and go.work.sum are the workspace release lock. An upgrade changes those files without copying the same Putnami version and checksums into every workspace member's go.mod and go.sum.

Member metadata is upgraded independently when a project declares the go publish channel, because a published module must resolve without its source workspace. A non-published application or tool that intentionally builds with GOWORK=off can opt into the same behavior:

{
  "options": {
    "@putnami/go": {
      "standalone": true
    }
  }
}

Use this option only for a real standalone boundary such as a packaged CLI or an extension runtime. Ordinary Putnami build, test, lint, and serve jobs resolve through the workspace lock and do not need duplicate member pins.

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.