Update the Helix CLI and SDK

Helix ships as two packages: the @trayai/helix-cli command-line tool, installed globally, and the @trayai/helix-sdk library, installed inside each project. The recommended way to update is to ask your coding agent to do it. That way both packages move forward together, and anything the new version changes gets fixed in the same pass. You can also run the steps by hand. Helix moves quickly before 1.0, so an out-of-date CLI or SDK is worth ruling out first when something that used to work stops.

Ask your coding agent to update (recommended)

Updating is a mechanical task a coding agent handles well, and it’s the safest path because the agent updates both packages together and repairs anything the new version breaks. Open your coding agent inside the project and ask it to:

• update the global CLI to the latest version,
• bump the project’s @trayai/helix-sdk to match,
• run npm install,
• confirm helix --version, and
• fix anything the newer version changed.

For example: “Update the Helix CLI to the latest version, bring @trayai/helix-sdk in this project up to match, reinstall, and fix any breakage.”

The agent runs the same commands documented below, so you stay in control and can review each change.

Update manually

Prefer to run it yourself? Update the CLI, then the SDK, then check Node.

Update the CLI

The CLI is a global npm package. Install the latest version over whatever you have:

npm install -g @trayai/helix-cli@latest
helix --version

Prefer install ...@latest over npm update, which does not always move to the newest version. With pnpm, use pnpm add -g @trayai/helix-cli@latest.

If helix --version still prints the old version afterwards, the cause is almost always an old Node or an nvm version that isn’t active. See update didn’t take.

Update the SDK in your project

The SDK is a project dependency, not a command, so update it from inside the project:

cd your-helix-project
npm install @trayai/helix-sdk@latest

Do this whenever you update the CLI, so your project’s SDK matches the tool you’re building with. If your project pins the SDK to *, a plain npm install already pulls the current version.

Keep Node current

Both the CLI and the SDK need Node.js 24.18.0 or later. An old Node is the most common reason an update appears not to work.

node --version     # 24.18.0 or higher

If you’re below that, upgrade Node and reinstall the CLI under the new version:

nvm install 24
npm install -g @trayai/helix-cli@latest

Reinstall the project’s dependencies too, so the SDK is rebuilt against the new Node: run npm install inside the project.

Re-authenticate after updating

If a command fails to authenticate after an update, your session may simply have expired rather than the update having broken anything. Sessions last seven days from sign-in. Confirm and refresh:

helix whoami       # confirm the session is still valid
helix login        # sign in again if it isn't

See project and auth session commands for the full login flow.

Migrate off the retired scope

If your machine or a project still references the old @trayio scope (spelled with io), move to @trayai (spelled with ai). The old scope no longer receives updates and cannot deploy. Uninstall it and install the current package:

# CLI, global
npm uninstall -g @trayio/helix-cli
npm install -g @trayai/helix-cli@latest

# SDK, inside each project
npm uninstall @trayio/helix-sdk
npm install @trayai/helix-sdk@latest

Update any remaining @trayio references in package.json and your imports to @trayai, then run npm install. This is a one-time cleanup, not part of a normal update.

After an update

Run the project locally to confirm the new versions work before you deploy:

helix dev

Pre-1.0 releases can carry breaking changes, so upgrade the CLI and SDK together and deliberately, not while preparing to ship. Already-deployed apps keep running while you’re behind; being out of date affects your next deploy, not the app that’s already live.

When an update misbehaves

The update didn’t take

helix --version still shows the old version after installing @latest. This is almost always an old Node or nvm setup. Restart your terminal, reinstall with npm install -g @trayai/helix-cli@latest (not npm update), upgrade Node to 24.18.0 or later, and if you use nvm make sure the new Node is the active and default version. Then re-check.

helix: command not found

The global install isn’t on your PATH, or didn’t finish. Reinstall, then check where it landed: see helix: command not found.

A deploy fails after updating

Pull the full record for the deployment, which carries its status, warnings, and build errors:

helix deployment get <deploymentId>

The troubleshooting page collects the other common deploy and version failures and their fixes.