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

# capsule auth

> Authenticate the Capsule agent with your license key, and optionally restore your encryption key on a new server.

## Usage

```bash theme={null}
# Normal setup (first time on a server)
capsule auth

# Disaster recovery (replacing a lost server)
capsule auth --restore
```

## When to run this

| Situation                                                   | Command                  |
| ----------------------------------------------------------- | ------------------------ |
| First time setting up Capsule on a server                   | `capsule auth`           |
| Your license key changed and you need to update it          | `capsule auth`           |
| Setting up a replacement server after the original was lost | `capsule auth --restore` |

You only need to run `capsule auth` once per server during normal use. Do not skip it — without a license key, the agent cannot connect to the dashboard, upload backups, or receive restore commands.

## What it does

* Prompts for your license key (starts with `cpsl_live_`)
* Saves it to `~/.config/capsule/capsule.yaml`
* Links this server to your Capsule account

When `--restore` is used, it also prompts for your saved encryption key and loads it into the OS keyring — making your existing encrypted backups accessible on the new server.

## Where to find your license key

Your license key is on the [Setup page](https://trycapsule.xyz/dashboard/setup) in your dashboard.

<Warning>
  Keep your license key secret. Anyone with access to it can link a server to your account.
</Warning>

## Flags

| Flag        | Description                                                                                                                                                                 |
| ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--restore` | After authenticating, prompt for a saved encryption key and load it into the keyring. Use this when setting up a replacement server so existing backups remain decryptable. |

## Disaster recovery — restoring on a new server

Use this when your original server is gone and you need to access your existing encrypted backups from a fresh install.

**Prerequisite:** You must have already saved your encryption key from the old server using [`capsule key show`](/cli/key). If you haven't done that yet and the old server is still accessible, do it now before continuing.

Once you have your saved key, run on the new server:

```bash theme={null}
capsule auth --restore
```

You'll be prompted for two things in sequence:

```
Enter your Capsule license key: cpsl_live_...
License key saved and verified.
Enter your saved encryption key (input hidden):
Encryption key restored. Your existing backups are now accessible.
```

Paste your 64-character hex key at the second prompt (input is hidden). After this completes, restores will work normally — Capsule will decrypt backups using the imported key.

<Warning>
  Importing the wrong key will appear to succeed but will cause decryption failures at restore time. Verify you're pasting the exact key from your old server before pressing Enter.
</Warning>

## Notes

* You only need to run `capsule auth` once per server
* Re-running it re-saves your license key to the config file but does not affect your encryption key — pass `--restore` if you also need to import a replacement encryption key
* `capsule auth` is exempt from the license key check — you can always run it on a fresh install with no prior config

## See also

* [`capsule key show`](/cli/key) — display and save your encryption key **before** you need to restore it