The Helix CLI (@trayai/helix-cli) is the command-line interface for Helix: it scaffolds projects, runs them locally, connects authentications, and deploys to Tray’s cloud. The binary is helix. It also runs an MCP server, which is how Claude drives the same commands while you build.
Install
The CLI needs Node.js 24.18.0 or later. Check with node --version and upgrade first if you’re below that (for example, nvm install 24).
npm install -g @trayai/helix-cliPrefer pnpm? pnpm add -g @trayai/helix-cli. To run without installing: npx @trayai/helix-cli <command>.
Verify with helix --version and which helix. These pages document v1.0.0 and later.
To move to a newer release later, see Update the CLI and SDK.
Ask the CLI
helix --help lists the commands your installed version has, and helix <command> --help lists that command’s flags. This output is authoritative and version-specific. Where these pages and --help disagree, trust --help: it ships with the binary you’re running.
Commands
Session, workspace, and project
Full details: Project & auth session.
| Command | What it does |
|---|---|
helix login | Sign in to Helix through your browser |
helix logout | Sign out and end the session |
helix whoami | Show who you’re signed in as |
helix init [project-name] | Scaffold a new project, optionally with a React app |
helix workspace select [name] | Choose the Tray workspace interactively |
helix workspace set <id> | Set the workspace by ID |
helix project set <id> | Point the project at a provisioned project ID |
helix region set <region> | Choose the Helix region the CLI talks to |
Local development
Full details: Local development.
| Command | What it does |
|---|---|
helix dev | Run the project locally on port 3000 with hot reload |
Authentications
Full details: Authentications.
| Command | What it does |
|---|---|
helix auth connect [service] | Find and connect a service interactively |
helix auth add <alias> <uuid> | Map an alias to an existing authentication |
helix auth list | List the aliases configured for this project |
Deploy
Full details: Build & deploy.
| Command | What it does |
|---|---|
helix deploy | Deploy the project and print its live URL; --wait blocks until the rollout finishes |
helix deployment get <deploymentId> | Show a deployment’s status, warnings, and build errors |
helix deployment wait <deploymentId> | Wait for a deployment to finish; exit 1 with the build errors if it fails |
helix ci init | Generate the CI pipeline (GitHub Actions) that deploys the project |
Logs
Full details: Logs.
| Command | What it does |
|---|---|
helix logs | List recent executions of the deployed project, newest first; --search, --errors, --since, and --until narrow the list |
helix logs get <executionId> | Show one execution in full: the request, every operation it ran, its ctx.log lines, and any error |
Agents
Full details: Agent commands.
| Command | What it does |
|---|---|
helix agent list | List the agents the local dev server loaded |
helix agent chat <name> | Talk to an agent from the terminal, approvals included |
Agent tooling
| Command | What it does |
|---|---|
helix mcp | Start the CLI’s MCP server on stdio |
helix mcp serves the tools Claude uses to build a Helix project. It speaks the stdio transport, and Claude starts it from the project’s MCP configuration, so you rarely run it by hand. See Building with Claude Code.
Regions and configuration
Project settings live in helix.config.ts at the project root: name, projectId, workspaceId, and your authentication aliases. Your Tray session lives separately in ~/.tray.config, written by helix login.
Helix runs as four regional deployments, us1 (the default), eu1, ap1, and ap2, each with its own dashboard and API backend. Your workspace lives in one of them. Set the Helix region with helix region set <region>, which persists. For a single command, helix login, helix logout, and helix whoami each accept an optional --region <region> flag. Run helix region set --help to see which region names your CLI version accepts. See regions for the matching dashboard URL.
Every command that reads or writes project config (dev, deploy, the deployment and logs commands, the auth commands, project set, region set, the workspace commands, and mcp) accepts --config <path> to run against a config file other than ./helix.config.ts, for example helix deploy --config helix.production.config.ts. The HELIX_CONFIG environment variable has the same effect; the flag wins when both are set. Keeping one config file per deploy target is how multiple development/production targets work in Helix; see the configuration model.