forked from jason/echo
jason
120 lines
3.6 KiB
Markdown
120 lines
3.6 KiB
Markdown
# 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.
|