Project and auth session commands

Log in to Tray, scaffold a project with helix init, choose a workspace, and point the CLI at a project ID and environment.

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 environment the CLI works against. Run them from the project root, since most of them read and write helix.config.ts.

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.
`--env <us1\|staging>`	Log in to this Helix environment 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.

~/.tray.config is shared with connector-cli. Logging in or out with either tool changes the token both of them use.

helix logout

helix logout

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

Flag	What it does
`--env <us1\|staging>`	Log out of this Helix environment 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
`--env <us1\|staging>`	Check the session for this environment 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 env set

helix env set <environment>

Sets the Helix environment the CLI talks to, and persists it for later commands.

helix env set us1

us1 is the environment shown in the command’s help text, and --env on login, logout, and whoami accepts us1 and staging. The full set of names env set accepts isn’t confirmed. Run helix env set --help to see what your version lists.