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

# Sign in

> Sign the MoleSignal CLI in through the browser with OAuth 2.1 or with an API token, keep several sign-ins in profiles, and check the setup behind a proxy.

The CLI signs in once and keeps the sign-in for later commands. Two ways are available:

| Way | Use it for |
| - | - |
| Browser sign-in | A person at a computer with a browser. Uses OAuth 2.1 and renews itself. |
| API token | Scripts, build machines, and computers without a browser. |

A browser sign-in reaches MoleSignal's MCP endpoint only. Reporting deployments, uploading
source maps and symbols, and sending logs call MoleSignal's API and take an API token.

## Sign in in the browser

```bash theme={null}
molesignal login --url https://molesignal.example.com
```

1. The CLI registers itself with MoleSignal and opens the MoleSignal authorization page in the
   default browser. Sign in to MoleSignal there if no session exists yet.
2. The authorization page names the client, the account, and the organization, and lists what the
   access allows. A user in several organizations picks one in **Organization**; the access is
   bound to it.
3. Click **Authorize**. The browser returns to the CLI, which reports the number of tools it can
   use.

The CLI asks for the scopes `mcp` and `offline_access`, so the sign-in renews itself until it is
revoked. The authorization page waits five minutes; after that, the command ends and the earlier
sign-in, if any, stays as it was. A refused or interrupted sign-in also leaves the earlier one in
place.

> [!NOTE]
>
> The browser returns to a listener on `http://127.0.0.1` that exists only while the command runs.
> Nothing listens on the machine after the command ends. On a remote machine reached over SSH, the
> browser cannot reach that listener: sign in there with an API token.

## Sign in with an API token

Create a token at **Identity & Access → API tokens**, then pass it on standard input:

```bash theme={null}
printf '%s' "$MOLESIGNAL_TOKEN" | molesignal login --url https://molesignal.example.com --with-token
```

The token acts with the permissions of the user or service account that owns it.

## Use a token without saving it

Set the address and the token in the environment, as on a build machine. Nothing is saved:

```bash theme={null}
MOLESIGNAL_URL=https://molesignal.example.com MOLESIGNAL_TOKEN=<token> molesignal status
```

`--url` and `--token` do the same for one command. A token saved for one address is never sent
to another.

## Keep several sign-ins

Each sign-in is kept in a profile: an address and the access to it. Several profiles keep the CLI
signed in to several MoleSignal instances, or to several organizations of one instance.
`--profile` names the profile a sign-in goes into:

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

The profile signed in last becomes the current one. Commands use the current profile;
`--profile` or `MOLESIGNAL_PROFILE` choose another for one command. A first sign-in without
`--profile` goes into the profile `default`.

| Command | Effect |
| - | - |
| `molesignal profiles` | Lists the profiles, their kind of sign-in, and their addresses. `*` marks the current one. |
| `molesignal use <profile>` | Makes a profile the current one. |
| `molesignal logout --profile <profile>` | Forgets the sign-in of a profile and keeps its address. |
| `molesignal profiles remove <profile>` | Forgets a profile. |

## Where the sign-in is kept

The profiles are saved in `~/.config/molesignal/config.json`, readable by its owner only. The
folder follows `XDG_CONFIG_HOME` when it is set, and `%APPDATA%` on Windows.
`MOLESIGNAL_CONFIG` points to another file.

## Work behind a proxy

`HTTPS_PROXY` (or `HTTP_PROXY`) sends every request of the CLI through a proxy, and `NO_PROXY`
lists the hosts reached without it:

```bash theme={null}
HTTPS_PROXY=http://proxy.example.com:3128 NO_PROXY=localhost molesignal status
```

A MoleSignal certificate issued by a private certificate authority needs that authority's
certificate in `NODE_EXTRA_CA_CERTS`.

## Check the sign-in and the setup

`molesignal status` reports the address, the profile, the server that answered, the MCP protocol
revision, the kind of sign-in, and the number of MCP tools:

```bash theme={null}
molesignal status
```

`molesignal whoami` reports the user, the organization, the role, and the permissions MoleSignal
grants:

```bash theme={null}
molesignal whoami
```

`molesignal doctor` checks each thing the CLI depends on and says what to do about a failure:
Node.js, the permissions of the configuration file, the address, the proxy, the network and TLS,
the clock, the sign-in, and the MCP endpoint. It exits with `1` when a check fails:

```bash theme={null}
molesignal doctor
```

## End a sign-in

`molesignal logout` forgets the saved sign-in of the current profile on this machine:

```bash theme={null}
molesignal logout
```

The grant itself stays in MoleSignal until it is revoked at
**Mole Agent → Settings → Inbound MCP**.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.