setup

1p-flawless Setup

Sets up a complete 1Password-backed env var workflow for the current project.

After setup:

• npm run env:inject → generates .env.local from 1P via op inject
• npm run dev:auth → starts dev server with secrets in-memory via op run (OAuth use case)

Prerequisites: op CLI installed and authenticated (op vault list must succeed).

---

Readiness Check

which op || echo "NOT INSTALLED"
op vault list 2>&1 | head -3

If op not installed: tell user to install from https://1password.com/downloads/mac/ then run op signin. If vault list fails: tell user to run op signin first. Stop.

---

Phase 1: Discovery (Autonomous)

Launch the secrets-scanner agent. Do not proceed until the report is returned.

---

Phase 2: Confirmation Gates

Gate 1: Vault + Item Name

Present the scanner's vault recommendation and proposed item name. Ask:

"Use vault [recommended] and item name [slug]? Or pick a different vault / create a new one."

If user wants a new vault:

op vault create "<name>"

Store confirmed vault name and item slug — used in all op:// references.

Gate 2: Secret List Review

Show the proposed fields (secrets only — skip PUBLIC vars). Ask:

"Any fields to remove, add, or change before I create the 1P item?"

Wait for confirmation or edits. Apply any changes to the list.

Gate 3: Template Type

Ask which injection pattern(s) to wire up:

1. op inject → writes .env.local to disk (env:inject npm script)
2. op run → in-memory at dev server start (dev:auth npm script, OAuth use case)
3. Both (recommended)

---

Phase 3: Execute

After all three gates confirmed, execute in order:

3a: Create/Update 1P Item

Check if item already exists:

op item get "<slug>" --vault "<vault>" 2>/dev/null && echo "EXISTS" || echo "NEW"

If new — create item with all confirmed secret fields. See references/vault-ops.md for exact op item create syntax.

If exists — add any missing fields via op item edit. See references/vault-ops.md for field edit syntax.

3b: Write Template File(s)

If op inject selected — create .env.local.tpl:

# Generated by 1p-flawless — edit op:// references if field names change
FIELD_NAME={{ op://VaultName/slug/FIELD_NAME }}

Use {{ }} syntax. See references/naming.md for the critical syntax distinction.

If op run selected — create .env.local.dev.tpl:

FIELD_NAME=op://VaultName/slug/FIELD_NAME

Bare op:// — NO braces. See references/naming.md.

3c: Patch .gitignore

Check for !.env*.tpl. If missing, add it. Ensure .env.local remains ignored (not negated).

!.env*.tpl

3d: Add npm scripts to package.json

If op inject selected — add:

"env:inject": "op inject -i .env.local.tpl -o .env.local"

If op run selected — read existing dev script and mirror it:

"dev:auth": "op run --env-file=.env.local.dev.tpl -- <existing dev command>"

Use Edit tool on package.json — do not overwrite the entire file.

3e: Conflict Check

grep -oE '^[A-Z_]+' .env.local.tpl 2>/dev/null | while read var; do
  grep -q "^$var=" .env.local 2>/dev/null && echo "CONFLICT: $var also in .env.local"
done

Warn user if any conflicts found — values in .env.local take precedence.

---

Phase 4: Verify

# Test op inject resolves
op inject -i .env.local.tpl -o /tmp/1p-flawless-test.env 2>&1 && echo "INJECT OK" || echo "INJECT FAILED"
rm -f /tmp/1p-flawless-test.env

If INJECT FAILED, show the error and help the user fix the op:// references.

---

Additional Resources

Reference Files

• references/vault-ops.md — Exact op CLI syntax: vault create/list, item create/edit/get, common errors
• references/naming.md — Slug rules, field naming, {{ }} vs bare op:// syntax distinction, comment caveat
• references/providers.md — OAuth provider env var names per framework (Better Auth, NextAuth v5)

---

Completion Summary

1p-flawless setup complete

Item:     <slug> in <vault> (<N> fields)
Created:  .env.local.tpl  (<N> refs)  [if op inject]
Created:  .env.local.dev.tpl  (<N> refs)  [if op run]
Updated:  package.json — env:inject / dev:auth
Updated:  .gitignore — !.env*.tpl

Run:
  npm run env:inject    → generate .env.local
  npm run dev:auth      → dev server with OAuth secrets

Check status:  /1p-status
Rotate a key:  /1p-rotate