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

# Tolmo CLI Authentication: Login, Profiles, and CI/CD

> Log in to Tolmo with browser-based OAuth, use named profiles for multiple orgs, or configure environment variables for CI/CD pipelines and automation.

Tolmo authenticates you through a browser-based OAuth flow against the Tolmo backend. Once you log in, your credentials are stored in `~/.tolmo/` as a named profile and reused automatically for subsequent commands. For CI/CD pipelines and automated scripts, you can skip the interactive flow entirely and authenticate using environment variables instead.

## Interactive login

<Steps>
  <Step title="Log in">
    Run the login command to open a browser window and complete the OAuth flow:

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

    Tolmo opens your default browser and waits for you to authenticate. After you approve access, the CLI stores your credentials in `~/.tolmo/` under the `default` profile.
  </Step>

  <Step title="Confirm your session">
    Verify that authentication succeeded and check which organization is active:

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

    The output shows your active profile, the API URL, and the organization slug.
  </Step>

  <Step title="Log out when done">
    To revoke the stored session and remove local credentials:

    ```bash theme={null}
    tolmo auth logout
    ```
  </Step>
</Steps>

## Named profiles

Named profiles let you maintain separate authenticated sessions for different organizations or environments — for example, a production org and a staging environment — without overwriting your default credentials.

Log in to a non-default profile by passing `--profile` and, optionally, `--api-url` to target a different backend:

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

Once a profile is saved, pass `--profile` to any command to use it:

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

To make a non-default profile the active one for your entire shell session, set the `TOLMO_PROFILE` environment variable:

```bash theme={null}
export TOLMO_PROFILE=staging
```

Any subsequent command in that shell will use the `staging` profile without requiring the `--profile` flag.

## Override organization

If you are logged in but need to run a single command against a different organization within the same profile, use the `--org` flag:

```bash theme={null}
tolmo --org other-org sql "SELECT 1"
```

This override applies only to that command and does not change your stored profile.

## CI/CD & automation

<Note>
  Do not use `tolmo auth login` in CI/CD pipelines. The interactive OAuth flow requires a browser and cannot complete in a non-interactive environment. Use environment variables instead.
</Note>

Set the following environment variables to authenticate without a stored profile:

| Variable          | Description                                                           |
| ----------------- | --------------------------------------------------------------------- |
| `TOLMO_API_URL`   | Backend API base URL. Defaults to the production endpoint when unset. |
| `TOLMO_API_TOKEN` | API token. When set, Tolmo skips profile lookup entirely.             |
| `TOLMO_ORG_SLUG`  | Organization slug. Required whenever `TOLMO_API_TOKEN` is set.        |

Export these variables in your CI environment or pipeline configuration:

```bash theme={null}
export TOLMO_API_URL="https://api.tolmo.com"
export TOLMO_API_TOKEN="your-api-token-here"
export TOLMO_ORG_SLUG="your-org-slug"
```

With these set, any `tolmo` command authenticates using the token and targets the specified organization, with no profile file required.

<Tip>
  Store `TOLMO_API_TOKEN` as a secret in your CI platform (for example, a GitHub Actions secret or a Vault-injected variable) rather than hard-coding it in pipeline configuration files.
</Tip>

## Stored credentials

Tolmo stores your profiles locally in `~/.tolmo/`. Each profile contains the API URL and the authentication token for a specific organization and environment. No credentials are stored in your shell history or configuration files — only in `~/.tolmo/`.

To inspect the currently active profile and confirm which organization you are working in:

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

The output includes the profile name, the API endpoint, and the active organization slug. Use this command any time you are unsure which context a command will run in.