> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tolmo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Using Named Profiles to Manage Multiple Tolmo Orgs

> Named profiles let you store separate Tolmo credentials for different organizations or environments and switch between them without re-authenticating.

Named profiles let you maintain separate login sessions for different Tolmo organizations or API environments (such as production and staging) without logging out and back in. Each profile stores its own credentials and API URL, so you can switch context with a single flag rather than re-authenticating. Profiles are stored locally in `~/.tolmo/`.

## Create a profile

Pass `--profile` and `--api-url` to `tolmo auth login` to create a named profile. The command opens the same browser-based OAuth flow as a standard login, but saves the resulting credentials under the profile name you choose.

```bash theme={null}
tolmo auth login --profile staging --api-url https://api.staging.example.com
```

Run this once for each organization or environment you want to access. You can create as many profiles as you need.

## Use a profile

Pass `--profile <name>` to any Tolmo command to run it using that profile's credentials and API URL.

```bash theme={null}
tolmo --profile staging sql "SELECT 1"
```

The `--profile` flag is a [global flag](/configuration/global-flags) accepted by every command. It overrides the active profile for that single invocation without changing your stored configuration.

## Default profile

When you run a command without `--profile`, Tolmo uses the profile named `default`. This is the profile created by a plain `tolmo auth login` with no `--profile` flag.

You can change the default for your current shell session by setting the `TOLMO_PROFILE` environment variable:

```bash theme={null}
export TOLMO_PROFILE=staging
tolmo sql "SELECT 1"   # uses staging profile
```

Any command in that shell session will now use the `staging` profile unless you explicitly pass `--profile` to override it.

## Check active profile

`tolmo auth status` shows which profile is currently active along with the associated organization slug and API URL. Use this to confirm you are operating against the correct environment before running destructive commands.

```bash theme={null}
tolmo auth status
```

The output includes the current profile name, organization slug, and the API URL the profile points to.

## Logout from a profile

Pass `--profile` to `tolmo auth logout` to remove credentials for a specific profile. Without `--profile`, the command logs out the `default` profile.

```bash theme={null}
tolmo auth logout --profile staging
```

This removes the stored credentials for the `staging` profile from `~/.tolmo/`. The profile entry itself is discarded; you will need to run `tolmo auth login --profile staging` again if you want to restore it.

## When to use profiles

<CardGroup cols={2}>
  <Card title="Multiple orgs" icon="building">
    Create a separate profile for each Tolmo organization your account belongs to. Switch between them with `--profile` instead of logging out and back in.
  </Card>

  <Card title="Staging vs production" icon="flask">
    Point profiles at different API environments for testing. Use `--api-url` at login time to aim a profile at a staging or preview endpoint while keeping your `default` profile on production.
  </Card>
</CardGroup>