# ECHO — API key setup (Windows & macOS)

The ECHO plugin authenticates to the vault with a bearer token. `echo.py` resolves it in
this order — **first hit wins**:

1. **`ECHO_KEY` environment variable** ← recommended for workstations
2. **`~/.echo-memory/credentials`** file (one `key=…` line, `chmod 600`)
3. a deprecated baked-in fallback (prints a warning on every call until you do #1 or #2)

You only need **one** of these. Pick the env var (below) or the credentials file
(`python3 echo.py write-key <token>`, cross-platform, no shell config needed).

> Replace `<YOUR_ECHO_API_KEY>` everywhere below with your actual token. **Never** paste
> the token into a vault note, a committed file, or a screen-share.

---

## Option A — credentials file (simplest, cross-platform)

```bash
# from the plugin's scripts dir; works identically on Windows/macOS/Linux
python3 "<plugin>/skills/echo-memory/scripts/echo.py" write-key <YOUR_ECHO_API_KEY>
```

Writes `~/.echo-memory/credentials` (mode 600 on Unix). Nothing else to configure.
To rotate later, run it again with the new token.

---

## Option B — environment variable

### Windows

**PowerShell — persistent (recommended).** Sets it for your user account; open a **new**
terminal afterward (the current session won't see it):

```powershell
[Environment]::SetEnvironmentVariable("ECHO_KEY", "<YOUR_ECHO_API_KEY>", "User")
```

**Command Prompt — persistent** (alternative; note `setx` truncates values over 1024 chars,
so the 64-char ECHO key is fine):

```cmd
setx ECHO_KEY "<YOUR_ECHO_API_KEY>"
```

**Current session only** (not persistent):

```powershell
$env:ECHO_KEY = "<YOUR_ECHO_API_KEY>"     # PowerShell
```
```cmd
set ECHO_KEY=<YOUR_ECHO_API_KEY>           REM Command Prompt
```

**GUI alternative:** Start → "Edit the system environment variables" → *Environment
Variables…* → under *User variables* click *New…* → Name `ECHO_KEY`, Value the token.

**Verify** (in a NEW terminal):
```powershell
echo $env:ECHO_KEY        # PowerShell
```
```cmd
echo %ECHO_KEY%           :: Command Prompt
```

### macOS

Modern macOS uses **zsh**. Add the export to your shell profile, then reload it:

```zsh
echo 'export ECHO_KEY="<YOUR_ECHO_API_KEY>"' >> ~/.zshrc
source ~/.zshrc
```

If you use **bash** instead:
```bash
echo 'export ECHO_KEY="<YOUR_ECHO_API_KEY>"' >> ~/.bash_profile
source ~/.bash_profile
```

**For GUI apps** (a desktop app that doesn't read your shell profile) you can also set it
for the login session:
```bash
launchctl setenv ECHO_KEY "<YOUR_ECHO_API_KEY>"
```
(Not persistent across reboot on its own; the shell-profile export above covers terminal
sessions, which is what the plugin uses.)

**Verify** (in a NEW terminal):
```bash
echo "$ECHO_KEY"
```

---

## Confirm it works

```bash
python3 "<plugin>/skills/echo-memory/scripts/echo.py" doctor
```

`doctor` reports the Python version, vault reachability, auth, bootstrap/schema, and the
**API key source** — it should say `ECHO_KEY env` or `credentials file`, not the deprecated
baked-in fallback.

---

## Security notes

- The token is a vault credential — treat it like a password. Don't commit it, don't store
  it in a vault note, rotate it if it leaks.
- `ECHO_KEY` (or `ECHO_BASE`) set in the environment **always overrides** the credentials
  file and the baked-in default, so it's safe for CI / one-off overrides:
  `ECHO_KEY=… python3 echo.py …`.
- Once you've set the key via Option A or B on every machine/agent that runs the plugin
  (terminal, CoWork, any scheduled run), the deprecated baked-in fallback can be removed
  from `scripts/echo.py` (`DEFAULT_KEY`) so no token lives in the source tree at all.