Project and auth session commands

These commands manage your Tray session and the project it belongs to: log in and out, scaffold a project, choose a workspace, and set the project ID and region the CLI works against. Run them from the project root, since most of them read and write helix.config.ts.

The commands that write config (workspace select, workspace set, project set, and region set) also accept --config <path> (v0.98.0 and later) to write into a config file other than ./helix.config.ts, for projects that keep one config file per deploy target.

helix login

Authenticates the CLI with Helix. Run it in a plain terminal, outside any AI agent session. It opens your browser, where you sign in as you normally would, including SSO if your organization uses it.

You need a browser on the same machine as your terminal, and the CLI waits up to five minutes for you to finish. Your session is saved to ~/.tray.config, created so that only your user account can read it.

Flag	What it does
`--method <oauth\|chrome>`	Login method. `oauth` (default) opens your browser. `chrome` reads a token from your signed-in Chrome, or lets you paste one; on macOS it prompts for Keychain access.
`--region <region>`	Log in to this Helix region instead of the default (`us1`)

How long a session lasts

Sessions last seven days, counted from when you signed in, not from when you last used the CLI. Using the CLI does not extend them.

Headless use with TRAY_CLI_TOKEN

Where there’s no browser and no saved session, such as a CI runner, set the TRAY_CLI_TOKEN environment variable to a Tray API user token (v1.3.0 and later). Every helix command then uses it instead of ~/.tray.config; nothing is written to disk, and the token is never refreshed. helix whoami confirms which user it belongs to, and reports a rejected token as TRAY_CLI_TOKEN was rejected rather than as an expired login. See Deploy from CI for creating the token.

helix logout

helix logout

Signs you out and clears your saved session from ~/.tray.config.

Flag	What it does
`--region <region>`	Log out of this Helix region instead of the default (`us1`)

helix whoami

helix whoami

Shows who you’re logged in as. Use it to check whether your session is still valid before you deploy. When it has expired, helix whoami prints this instead:

Your saved Tray login is no longer valid. Run helix login.

Flag	What it does
`--region <region>`	Check the session for this region instead of the default (`us1`)

helix init

helix init [project-name]

Scaffolds a new Helix project in a project-name/ folder. Pass . as the name to scaffold into the current directory instead. The scaffold includes helix.config.ts, a functions/ directory with sample functions, and the MCP configuration Claude Code needs to discover the project.

Flag	What it does
`--with-app`	Also scaffold a Vite and React app under `app/`
`--project-id <id>`	Write this project ID into the config instead of leaving it unset
`--workspace-id <id>`	Write this workspace ID into the config instead of prompting
`--force`	Scaffold even when the target directory already has files in it

helix init my-app --with-app --workspace-id f8e7d6c5-4b3a-2190-8765-abcdef012345
cd my-app
npm install

Nothing is provisioned on the platform at this point. Your project gets its ID on the first helix deploy, or from --project-id if you already have one.

helix workspace select

helix workspace select [name]

Chooses the Tray workspace for this project, interactively. Pass a name to skip the picker. Helix apps live inside a workspace, so select one before you use authentications or deploy. Your Tray contact tells you which workspace you’re provisioned in.

helix workspace set

helix workspace set <id>

Sets the workspace by ID, writing workspaceId into helix.config.ts. Use this when you already know the ID, in scripts, or in CI where the interactive picker can’t run.

helix project set

helix project set <id>

Sets projectId in helix.config.ts, pointing your local project at an existing provisioned project.

You need this to resolve resources that were provisioned for the project rather than created locally. Persistent key-value storage is the main one: without a project ID, helix dev has no provisioned project to read from and falls back to in-memory storage.

helix project set 7c1e4a90-5b2d-4f83-9c6a-1d0e8b7f2a34

helix region set

helix region set <region>

Sets the Helix region the CLI talks to, and persists it for later commands. Helix runs as four regional deployments: us1 (the default), eu1, ap1, and ap2. Your workspace lives in one of them; your Tray contact tells you which. Run helix region set --help to see which region names your CLI version accepts. See regions for how this affects the dashboard URL too.