# Authentication

Authenticate with your sitemd account to unlock [activated builds](/docs/build-modes#activated) and [deployment](/docs/deploy). One login covers all projects on your machine.

> This page covers **CLI authentication** for production builds and deployment. To add user login and gated pages to your site, see [User Auth & Gating](/docs/user-auth).

## Log in

The default login opens your browser:

```
sitemd auth login
```

```
  Opening browser to log in...
  Your code: ABCD-1234

✓ Logged in as you@example.com
```

Your browser opens the sitemd.cc login page. After you sign in and approve the CLI access code, the terminal picks up the session automatically.

## Log in without a browser

If you're on a headless server or prefer typing credentials directly:

```
sitemd auth login --no-browser
```

```
Email: you@example.com
Password: ********
✓ Logged in
```

You can also pass credentials as flags for scripting:

```
sitemd auth login --email you@example.com --password yourpassword
```

## Check your status

See who you're logged in as and your license usage:

```
sitemd auth status
```

```
Logged in as you@example.com
Email verified: yes

Licenses: 1
Site slots: 3/5 used
```

## Log out

```
sitemd auth logout
```

This removes the saved token from `~/.sitemd/auth.json`.

## API keys for CI

For CI pipelines and automated deploys, generate a long-lived API key:

```
sitemd auth api-key GitHub Actions
```

```
✓ API key created: GitHub Actions

  sk_a1b2c3d4e5f6...

Save this key — it won't be shown again.
```

Set it as an environment variable in your CI:

```bash
export SITEMD_TOKEN=sk_a1b2c3d4e5f6...
sitemd deploy
```

The `SITEMD_TOKEN` environment variable takes precedence over saved credentials, so it works without running `sitemd auth login` first.

AI agents can also create API keys via the `sitemd_auth_api_key` MCP tool — see [MCP Server](/docs/mcp-server#sitemd_auth_api_key) for details.

## Auth commands

| Command | What it does |
|---|---|
| `sitemd auth login` | Log in via browser (default) |
| `sitemd auth login --no-browser` | Log in with email/password prompt |
| `sitemd auth logout` | Clear saved credentials |
| `sitemd auth status` | Show current user and license summary |
| `sitemd auth api-key <name>` | Generate an API key for CI |

## How it works

Your auth token is stored at `~/.sitemd/auth.json` — a single global file, not per-project. This means one login covers every sitemd site on your machine.

The precedence order is:

1. `SITEMD_TOKEN` environment variable (highest priority)
2. `~/.sitemd/auth.json` saved token
3. Prompt to log in (if neither exists)

## Related

- [User Auth & Gating](/docs/user-auth) — add login, signup, and gated pages to your site (different from CLI auth)
- [CLI Config](/docs/cli-config) — `sitemd config` for managing deploy credentials, email keys, and analytics IDs
- [Email Templates](/docs/email) — auth flows typically send verification and password reset emails
- [Deploy](/docs/deploy) — deployment workflow that uses your auth token