API Reference

The ebcprep CLI is the primary interface for all sync, inspection, and publishing operations. It reads your feeder spreadsheet, reconciles its contents with NotebookLM, and tracks every operation in a local SQLite state database (data/ebcprep.db). Use these commands to create and update executive notebooks, preview changes before they happen, generate mind maps, publish the team portal, and diagnose configuration problems.

ebcprep sync

Synchronizes the feeder spreadsheet with NotebookLM. This is the main command you will run on a schedule or after every sheet update.

ebcprep doctor

Runs a pre-flight health check against all configuration and connectivity requirements. Use this before your first sync or whenever something stops working.

ebcprep status

Prints a summary of every executive tracked in the state database, including notebook URLs, source counts, and the last sync timestamp.

ebcprep export

Generates index.html — the team portal — listing every executive's NotebookLM notebook URL in one place.

ebcprep mindmap

Triggers NotebookLM to generate a mind map for one or all executive notebooks and records the artifact in the state database.

.env configuration keys

The .env file is read on every command invocation. All keys are required unless marked optional.

defaults.toml configuration keys

defaults.toml is optional. When present, it is merged into every notebook operation.

Feeder spreadsheet column layout

ebcprep reads specific columns from your feeder sheet by position. Columns A–N are recognised; additional columns to the right are ignored.

ebcprep sync

Exits 0 on success. Writes a structured run summary to stdout listing:

• Number of rows read from the feeder sheet
• Number of notebooks created or matched
• Number of sources added
• Number of invites sent
• Number of rows skipped (already processed)

With --dry-run, exits 0 and writes the same summary prefixed with [DRY RUN]; no state is written to data/ebcprep.db.

ebcprep doctor

Exits 0 if all checks pass. Exits non-zero if any check fails. Each check is printed on its own line with a ✓ (pass) or ✗ (fail) indicator and a short explanation.

ebcprep status

Exits 0 and writes a table (or JSON array when --json is specified) to stdout. Each row represents one executive and includes: executive name, notebook URL, number of sources, number of invites sent, and the ISO-8601 timestamp of the last sync that touched the notebook.

Returns an empty table (exit 0) if no executives have been synced yet.

ebcprep export

Exits 0 and writes index.html to the specified output directory (default: current working directory). Prints the resolved output path to stdout.

ebcprep mindmap

Exits 0 on success. Prints one line per notebook processed, showing the executive name and the mind map artifact identifier recorded in data/ebcprep.db.

With --dry-run, exits 0 and prints which notebooks would be processed without contacting NotebookLM.

Preview a sync without making changes

Always run with --dry-run first so you can confirm what will be created before any notebook operations happen.

ebcprep sync --dry-run

Expected output:

[DRY RUN] Reading feeder sheet: 1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms
[DRY RUN] 12 rows found
[DRY RUN] Would create notebook: Priya Patel
[DRY RUN] Would add source: Acme Corp — 2025-08-14 14:00–15:00 → Priya Patel
[DRY RUN] Would invite: priya@example.com (executive), ops-team@example.com (always_collaborator)
[DRY RUN] 3 rows already processed — would skip
[DRY RUN] 0 changes written to state database

Run a live sync

After confirming the dry run looks correct, run without the flag.

ebcprep sync

Expected output:

Reading feeder sheet: 1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms
12 rows found, 3 already processed
Created notebook: Priya Patel
Added source: Acme Corp — 2025-08-14 14:00–15:00 → Priya Patel
Invited: priya@example.com, ops-team@example.com
Sync complete. 9 rows processed, 3 skipped.

Run a health check before the first sync

ebcprep doctor

Expected output (all clear):

✓ .env loaded
✓ SERVICE_ACCOUNT_PATH resolves to /home/user/.config/ebcprep/sa-key.json
✓ Sheets API: read access confirmed on sheet 1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms
✓ NLM profile "ebc-ops" found and session is valid
✓ defaults.toml loaded (2 always_collaborators, 1 default_source)
All checks passed.

Expected output (profile missing):

✓ .env loaded
✓ SERVICE_ACCOUNT_PATH resolves to /home/user/.config/ebcprep/sa-key.json
✓ Sheets API: read access confirmed
✗ NLM profile "ebc-ops" not found — run: nlm login --profile ebc-ops
1 check failed.

Inspect a single executive's status

ebcprep status --exec "priya"

Expected output:

Executive        Notebook URL                                      Sources  Invites  Last Sync
Priya Patel      https://notebooklm.google.com/notebook/abc123    4        3        2025-08-13T09:14:02Z

Emit status as JSON for scripting

ebcprep status --json

Expected output:

[
  {
    "executive_name": "Priya Patel",
    "notebook_url": "https://notebooklm.google.com/notebook/abc123",
    "source_count": 4,
    "invite_count": 3,
    "last_sync": "2025-08-13T09:14:02Z"
  }
]

Generate mind maps for all executives

ebcprep mindmap

Expected output:

Generating mind map: Priya Patel → mindmap-abc123-20250813
Generating mind map: James Okonkwo → mindmap-def456-20250813
Mind maps generated: 2

Generate a mind map for one executive only

ebcprep mindmap --exec "priya"

Expected output:

Generating mind map: Priya Patel → mindmap-abc123-20250813
Mind maps generated: 1

Publish the team portal

ebcprep export --out ./portal

Expected output:

Portal written to: ./portal/index.html

Minimal .env file

SERVICE_ACCOUNT_PATH=/home/user/.config/ebcprep/sa-key.json
SHEET_ID=1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms
NLM_PROFILE=ebc-ops

Minimal defaults.toml file

always_collaborators = [
  "ebc-ops@example.com"
]

default_sources = [
  "https://docs.google.com/document/d/BRIEFING_STANDARDS_DOC_ID/edit"
]

Content hash and deduplication. ebcprep computes a content hash from the executive_name (column A) and prep_doc_url (column G) of each feeder row. This hash is the deduplication key stored in data/ebcprep.db. If you correct a typo in the executive name or change the prep doc URL, ebcprep treats the row as new and will add a second source. Delete the stale source in NotebookLM manually and delete the matching row from data/ebcprep.db if you need a clean re-process.

Deleting the state database. Deleting data/ebcprep.db forces a full re-sync on the next run. ebcprep will attempt to create notebooks that already exist in NotebookLM — it will match them by name rather than creating duplicates — but it will re-add all sources and re-send all invites. Only do this as a recovery step.

nlm login is a one-time prerequisite. ebcprep does not call nlm login itself. You must run nlm login --profile <name> once (it opens Chrome for interactive auth) before any sync or mindmap command. The profile name you use must match NLM_PROFILE in .env.

defaults.toml is merged, not replaced. If an executive's notebook already has some of the default_sources added (from a previous sync), ebcprep detects the content hash and skips re-adding them. always_collaborators are similarly idempotent — inviting an already-invited address is a no-op.

EA / COS columns are optional but positional. Columns M and N are only read when they contain a valid email address. Empty cells are silently ignored. Do not shift these columns — ebcprep reads by position, not by header name.

Concurrent runs are not supported. ebcprep holds a write lock on data/ebcprep.db for the duration of a sync. If you run two instances simultaneously, the second will fail with StateDBError: database locked. Use a CI job mutex or a simple lock file in your automation to prevent this.

ebcprep export does not contact NotebookLM. It reads notebook URLs from data/ebcprep.db and renders them into index.html locally. If a notebook was created in a previous session but the state database has been moved or deleted, that executive will not appear in the portal.

Mind map availability. Mind maps are generated inside NotebookLM's Studio panel. ebcprep records the artifact identifier in data/ebcprep.db but does not download the mind map content. Access the visual mind map by navigating to the executive's notebook URL and opening the Studio panel.