# Log in to the HTTP backend

## Goal

Authenticate against a PlayMolecule HTTP backend so app calls submit jobs through the backend instead of running locally.

## Minimal example

```bash
playmolecule login --email you@example.com
```

You'll be prompted for a password (or read it from `PM_PASSWORD` / `PLAYMOLECULE_PASSWORD`). On success, a cookie is written to `~/.cache/playmolecule/cookies/` and reused by every subsequent call.

## From Python

```python
from playmolecule import login, logout

login("you@example.com", "•••••••")
# ... use playmolecule normally ...
logout()
```

`login()` raises if `PM_EXECUTOR` (or `PM_REGISTRIES` for an `http://` registry) doesn't point at a valid HTTP URL.

## Configure where to log in

The HTTP URL comes from your environment:

```bash
export PM_REGISTRIES=http://playmolecule.example.com
export PM_EXECUTOR=http://playmolecule.example.com    # often the same URL
```

`PM_REGISTRIES` tells PlayMolecule where to fetch manifests; `PM_EXECUTOR` tells it where to submit jobs. They're independent — you can browse an HTTP registry but execute locally, or vice versa.

## Non-interactive login (CI)

```bash
export PLAYMOLECULE_EMAIL=ci@example.com
export PLAYMOLECULE_PASSWORD='••••••••••'
playmolecule login
```

Or the `PM_*` aliases:

```bash
export PM_EMAIL=ci@example.com
export PM_PASSWORD='••••••••••'
playmolecule login
```

## Log out

```bash
playmolecule logout
```

Clears the session cookie locally. Equivalent in Python:

```python
from playmolecule import logout
logout()
```

## Custom cookie cache location

By default cookies sit under `~/.cache/playmolecule/cookies/`. Move them by setting:

```bash
export PM_COOKIE_CACHE_DIR=/secure/path/playmolecule-cookies
```

Useful in containerised CI runners where `$HOME` is ephemeral.

## Gotchas

- The backend issues a CSRF token before accepting credentials; if the first request fails with an HTTP error, the URL is almost certainly wrong or the backend isn't reachable.
- A logged-in session is persisted per host. Different machines need their own `login`.
- `login` doesn't validate the credentials beyond what the server reports — if you mistyped the password you'll see the failure surface as an HTTP 401 from the next API call, not the login itself.

## See also

- {py:func}`~playmolecule.login`
- {py:func}`~playmolecule.logout`
- [Environment variables](../reference/environment-variables.md)
- [CLI](../reference/cli.md)