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

:::note{title="Flags are version-specific"}
The flags below match v0.85.0. Run `helix <command> --help` to confirm what your installed version accepts.
:::

## helix login

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

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

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

```text
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

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

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

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

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

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

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

## helix env set

```bash
helix env set <environment>
```

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

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

---

Canonical: https://helix.tray.ai/documentation/reference/cli/project/
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