# Update the Helix CLI and SDK

> Update the Helix CLI globally with npm, update the SDK in your project to match, keep Node current, and re-authenticate after an update.

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:

```bash
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](#the-update-didnt-take).

### Update the SDK in your project

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

```bash
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.

```bash
node --version     # 24.18.0 or higher
```

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

```bash
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:

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

See [project and auth session commands](/documentation/reference/cli/project/) 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:

```bash
# 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:

```bash
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](/documentation/troubleshooting/#helix-command-not-found).

### A deploy fails after updating

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

```bash
helix deployment get <deploymentId>
```

The [troubleshooting page](/documentation/troubleshooting/) collects the other common deploy and version failures and their fixes.

---

Canonical: https://helix.tray.ai/documentation/reference/cli/update/
Any link on this page is available as markdown by appending .md to its URL.
Full corpus: https://helix.tray.ai/documentation/llms-full.txt