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

# Authentication

> Sign in to the CLI, inspect saved credentials, and work across several workspaces.

The CLI signs in through the browser. Unlike the REST API, it does not use an API key: it
creates a session tied to your user account, so every command is subject to the permissions
your role grants in that workspace.

## Sign in

```bash theme={"system"}
neetoinvoice login --subdomain acme
```

A browser window opens for you to approve the session. Omit `--subdomain` and the CLI prompts
for it.

```
Authenticated as oliver@example.com on acme.neetoinvoice.com.
```

Credentials for every signed-in subdomain are stored together in
`~/.config/neetoinvoice/auth.json`.

<Warning>
  That file holds live session tokens. Treat it like a password: keep it out of logs, bug
  reports, screen shares, and version control. Note that `logout` only removes the local
  copy, so if the file has leaked, contact
  [support@neetoinvoice.com](mailto:support@neetoinvoice.com) to have the sessions revoked.
</Warning>

## Check who you are

```bash theme={"system"}
neetoinvoice whoami
```

```
Authenticated as oliver@example.com on acme.neetoinvoice.com (default).
```

With more than one workspace signed in, `whoami` lists them all. Pass `--subdomain <name>` to
show just one.

## Working with several workspaces

How a command picks a subdomain depends on how many are signed in:

| Signed-in subdomains | Behavior                                                                                                  |
| -------------------- | --------------------------------------------------------------------------------------------------------- |
| None                 | Every command that talks to the API fails with `not logged in. Run 'neetoinvoice login' to authenticate`. |
| One                  | That one is the implicit default. `--subdomain` may be omitted.                                           |
| Two or more          | `--subdomain <name>` is **required** on every command that talks to the API, including `doctor`.          |

```bash theme={"system"}
neetoinvoice clients list --subdomain acme
```

## Sign out

```bash theme={"system"}
neetoinvoice logout --subdomain acme
```

| Command                                  | Effect                                                                         |
| ---------------------------------------- | ------------------------------------------------------------------------------ |
| `neetoinvoice logout --subdomain <name>` | Removes that one entry.                                                        |
| `neetoinvoice logout --all`              | Removes every entry.                                                           |
| `neetoinvoice logout`                    | Removes the only entry when exactly one is signed in; errors when several are. |

## Verify connectivity

```bash theme={"system"}
neetoinvoice doctor
```

```
✓ Authentication: authenticated as oliver@example.com on acme.neetoinvoice.com
✓ API connection: https://acme.neetoinvoice.com (responding in 142ms)
✓ CLI version: 1.0.7
```

Each check runs independently, so a failing one does not hide the others.

## How the CLI, the API, and MCP authenticate

| Surface                                     | Credential                             | Acts as                                 |
| ------------------------------------------- | -------------------------------------- | --------------------------------------- |
| [REST API](/getting-started/authentication) | `X-Api-Key` header                     | The workspace, unrestricted by role     |
| CLI                                         | Browser session stored on your machine | You, limited by your role's permissions |
| [MCP server](/mcp/authentication)           | `Authorization: Bearer <api-key>`      | The workspace, unrestricted by role     |

## Point the CLI at another server

Set `NEETOINVOICE_BASE_URL` to override the default `https://<subdomain>.neetoinvoice.com`:

```bash theme={"system"}
export NEETOINVOICE_BASE_URL=http://acme.lvh.me:8980
neetoinvoice login --subdomain acme
```