> ## Documentation Index
> Fetch the complete documentation index at: https://pulse-41cf5b0d.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Authenticate the pulse CLI Using a PulseGuard API Key

> Log in to the pulse CLI with your PulseGuard API key. Credentials are stored in the OS-native config directory and verified on login.

Every `pulse` command that communicates with PulseGuard requires an API key. Authentication is a one-time setup step: you log in once, and the CLI stores your credentials securely on your machine for all future commands. Your key is never transmitted to any third party — it is only ever sent to PulseGuard's API.

## Get an API key

<Steps>
  <Step title="Open the dashboard">
    Go to [pulseguard.io/dashboard](https://pulseguard.io/dashboard) and sign in to your account.
  </Step>

  <Step title="Navigate to API Keys">
    Click **Settings** in the sidebar, then select the **API Keys** tab.
  </Step>

  <Step title="Create a new key">
    Click **New Key**, give it a descriptive name (for example, `local-dev` or `ci-pipeline`), and copy the generated key. API keys are prefixed with `pg_` and are shown only once.
  </Step>
</Steps>

<Warning>
  Store your API key somewhere safe immediately after creation. PulseGuard does not show the full key again after you navigate away from the creation dialog.
</Warning>

## Log in

Pass your API key to `pulse auth login` using the `--key` flag:

```bash theme={null}
pulse auth login --key pg_your_api_key_here
```

The CLI verifies the key against PulseGuard's API before saving it. On success you'll see:

```
✔ Authenticated successfully!
  Found 3 monitors
```

If the key is invalid or the network is unreachable, the CLI exits with an error and does not persist any credentials.

## Check your authentication status

At any time, confirm which credentials the CLI is currently using:

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

```
✔ Logged in
  Key prefix : pg_live_abc123…
  Base URL   : https://pulseguard.io
```

If you are not logged in, the output guides you to the login command:

```
Not logged in. Run: pulse auth login --key <API_KEY>
```

## Log out

To remove your stored credentials from the machine:

```bash theme={null}
pulse auth logout
```

```
✔ Logged out. Credentials cleared.
```

This is useful when rotating keys or working on a shared machine.

## Where credentials are stored

The CLI uses [`conf`](https://github.com/sindresorhus/conf), which persists settings in the OS-native user config directory:

| OS      | Location                                |
| ------- | --------------------------------------- |
| macOS   | `~/Library/Preferences/pulseguard-cli/` |
| Linux   | `~/.config/pulseguard-cli/`             |
| Windows | `%APPDATA%\pulseguard-cli\`             |

Your API key is stored in that directory and is only readable by your OS user account. It is never sent anywhere except to PulseGuard's API endpoint.

## Connect to a self-hosted instance

If you run a self-hosted PulseGuard deployment, pass your instance's URL with the `--url` flag at login time:

```bash theme={null}
pulse auth login --key pg_your_api_key_here --url https://your-pulseguard.example.com
```

The CLI saves the custom base URL alongside the API key and uses it for every subsequent request. You can verify the active base URL with `pulse auth status`.