# Select a workspace

> Choose the workspace for one CLI command, a shell session, or a project

> Nevia is in beta and open to selected teams. Public launch in Dec 2026. The CLI installs with `curl -fsSL https://get.nevia.cloud | sh`, and the MCP server is at https://api.nevia.cloud/mcp. A person signs in once in the browser.
> Setup, sign-in and requesting access: [SKILL.md](https://nevia.cloud/SKILL.md). When Nevia fits and when it doesn't: [why.md](https://nevia.cloud/why.md).

> For the complete documentation index, see [llms.txt](https://nevia.cloud/llms.txt). This page's HTML version: https://nevia.cloud/docs/workspaces/select

Set the workspace that CLI commands use, per command, per shell, per project, or as
your default. You need the [CLI installed and signed in](https://nevia.cloud/docs/get-started/quickstart.md)
and access to a workspace. No workspace yet? [Create one](https://nevia.cloud/docs/workspaces/manage.md).

## Find the ID

```bash
nevia whoami
```

Copy the full ID of the workspace and use it in place of
`01d4cnjjq40hnnh0nwmkg35nv2h` below. With one workspace, such as the `default`
one from your first sign-in, commands use it without a selection.

## Save a default

```bash
nevia workspace use 01d4cnjjq40hnnh0nwmkg35nv2h
nevia workspace current
```

`use` writes the default to your user `config.toml`. `current` shows the effective
workspace and its source. To confirm API access to it, run `nevia workspace get`.

## Override one command

```bash
nevia workspace get --workspace 01d4cnjjq40hnnh0nwmkg35nv2h
```

## Select for a shell

```bash
export NEVIA_WORKSPACE=01d4cnjjq40hnnh0nwmkg35nv2h
nevia workspace current
```

Clear it with `unset NEVIA_WORKSPACE`.

## Select for a project

```bash
nevia workspace use 01d4cnjjq40hnnh0nwmkg35nv2h --local
nevia workspace current
```

`--local` writes `.nevia.toml` in the current directory. Commands in that directory
and its subdirectories use the workspace.

## Precedence

1. `--workspace` on the command.
2. `NEVIA_WORKSPACE`.
3. The nearest `.nevia.toml`.
4. The default in your user `config.toml`.

A positional workspace argument, such as `nevia workspace get 01d4cnjjq40hnnh0nwmkg35nv2h`,
beats all four.

Clear the default with `nevia workspace use --unset`. Clear the project selection
with `nevia workspace use --local --unset`. The file stays in place.

With several workspaces and no selection, commands fail with `no workspace selected`
and list them.

## When the selected workspace is removed

`nevia workspace rm` clears your saved default if it names the removed workspace.
It leaves `.nevia.toml` and `NEVIA_WORKSPACE` alone and reports when either one
names the removed workspace. If someone removes the workspace elsewhere, such as in
the console, commands fail with exit code 3 and name the source of the selection.
The CLI does not switch to another workspace on its own.

Command options are in [`nevia workspace use`](https://nevia.cloud/docs/reference/cli/workspace/use.md).
Next, [create a database](https://nevia.cloud/docs/databases/create.md) in your selected workspace.