1Password integration (API keys & tokens)

Use 1Password as the single source of truth for Broccolini Bot secrets. Your .env file then holds only Secret References (op://...), so you never store plaintext tokens on disk.

Setup checklist (extension + CLI)

Step	What to do
1. Extension	In Cursor: Extensions (Ctrl+Shift+X) → search 1Password → Install. (On WSL/Linux the extension may refuse to install; use the CLI path below instead.)
2. Choose account	After installing: Command Palette (Ctrl+Shift+P) → 1Password: Choose account → sign in and pick a vault.
3. CLI	Install 1Password CLI: `sudo apt install op` (WSL/Linux) or install from 1Password. Then run `eval $(op signin)` once per terminal (or add to your shell profile).
4. Store secrets	In 1Password: create an item (e.g. Broccolini Bot) and add custom fields for each secret (e.g. `DISCORD_TOKEN`, `MONGODB_URI`, `REFRESH_TOKEN`). Use Copy reference on each field.
5. .env with refs	In `broccolini-bot/.env`: put `KEY=op://Vault/ItemName/FIELD` for each secret (no plaintext). Use 1Password: Get from 1Password in the editor to insert refs, or paste from step 4.
6. Run bot	From `broccolini-bot/`: `npm run start:1p` (or `op run --env-file=.env -- npm run start`).

If the extension is not available on your OS, use steps 3–6 only (CLI + Secret References in .env + op run).

Extensions and Cursor integration

What	Where	Purpose
1Password for VS Code	VS Code Marketplace	Works in Cursor. Save/retrieve secrets, Secret References, detect secrets, preview `op://` refs. Docs.
1Password Cursor Hooks	1Password Marketplace	Validates that 1Password Environments–mounted `.env` files are present and valid before Cursor Agent runs shell commands. Cursor Hooks docs, validate hook guide.

VS Code extension: Install in Cursor via Extensions (search “1Password”). Use 1Password: Get from 1Password / Save in 1Password and Secret References in .env and code.
Cursor Hooks: Uses 1Password Environments with locally mounted .env files (Mac/Linux; requires 1Password app + sqlite3). Clone 1Password/cursor-hooks, add the hook to .cursor/hooks, and optionally .1password/environments.toml to declare which .env paths to validate. Then Cursor Agent only runs commands when those env files are mounted.

1. Install

1Password for VS Code / Cursor
Install the 1Password extension in Cursor. You can then use Secret References in files and autofill from your vault.
1Password CLI (op)
Required for running the bot with secrets from 1Password. Full install and sign-in: Get started with 1Password CLI.
- Install: Linux (WSL): sudo apt install op; Mac: Homebrew or manual; Windows: winget or manual.
- Desktop app: In 1Password app → Settings → Developer → turn on Integrate with 1Password CLI (Mac: optional Touch ID; Windows: turn on Windows Hello first; Linux: Settings → Security → Unlock using system authentication, then Developer → Integrate).
- Sign in: Run eval $(op signin) (or any op command); you’ll be prompted to authenticate.

2. Store secrets in 1Password

Create an item that will hold Broccolini Bot env vars, e.g. “Broccolini Bot” or “Broccolini Bot Production”.

Type: API Credential or Secure Note.
Fields: Add one custom field per secret. Field names must match the env var names (e.g. DISCORD_TOKEN, MONGODB_URI, REFRESH_TOKEN, GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, etc.).
Use the same names as in .env.example for the sensitive values.

You can use a second item (e.g. “Broccolini Bot Test”) with test-only values and point .env.test at it (see below).

3. Use Secret References in `.env`

In .env (and optionally .env.test), do not put real tokens. Use 1Password Secret References instead:

# Example: vault "Personal", item "Broccolini Bot", field "password" or custom field name
DISCORD_TOKEN=op://Personal/Broccolini Bot/DISCORD_TOKEN
MONGODB_URI=op://Personal/Broccolini Bot/MONGODB_URI
REFRESH_TOKEN=op://Personal/Broccolini Bot/REFRESH_TOKEN
GOOGLE_CLIENT_ID=op://Personal/Broccolini Bot/GOOGLE_CLIENT_ID
GOOGLE_CLIENT_SECRET=op://Personal/Broccolini Bot/GOOGLE_CLIENT_SECRET
# ... same for other secrets

Replace Personal with your vault name.
Replace Broccolini Bot with your item title (spaces are fine).
The last part is the field name inside that item (e.g. DISCORD_TOKEN).

Non-secret values (IDs, ports, feature flags) can stay as plain text in .env if you prefer.

To get a reference from the 1Password app: open the item → click a field → “Copy reference”.

4. Run the bot with 1Password

From the broccolini-bot directory:

op run --env-file=.env -- npm run start

For the test env:

op run --env-file=.env.test -- npm run start:test

op run reads .env (or .env.test), resolves every op://... value with 1Password, and runs the command with the resolved environment. The bot’s config.js still reads from process.env as usual; no code changes are required.

5. npm scripts (already in package.json)

In broccolini-bot/:

npm run start:1p — production env from 1Password (resolves op:// from .env)
npm run start:test:1p — test env from 1Password (resolves op:// from .env.test)

6. Security notes

Do not commit .env or .env.test. They are gitignored. Even with Secret References, keep them out of the repo.
Rotate secrets in 1Password when needed; no need to edit local files if you only use references.
The 1Password Cursor extension can fill Secret References in the editor; the CLI is what actually resolves them when you run the bot.

Quick reference

Task	Command / step
CLI get started	Get started with 1Password CLI (install, desktop integration, sign in)
Sign in to CLI	`eval $(op signin)` — required so the session is loaded into your shell; plain `op signin` only prints the commands.
Run bot (production)	`op run --env-file=.env -- npm run start`
Run bot (test)	`op run --env-file=.env.test -- npm run start:test`
Copy a secret reference	1Password app → item → field → “Copy reference”

7.1 KiB Raw Blame History Unescape Escape