Template Literals

This page explains how to use tagged template literals within ebcprep's configuration and scripting surface. Tagged template literals let you embed dynamic values — such as executive names, meeting dates, and document URLs — directly into configuration strings and CLI invocations, making it easier to build consistent, readable expressions when wiring up your feeder spreadsheet data or customizing output. Understanding this pattern helps you work more efficiently with ebcprep's configuration files and reduces the chance of formatting errors in notebook titles and source labels.

Before working with tagged template literals in ebcprep, make sure you have the following in place:

• Python ≥ 3.11 — required by ebcprep and its dependencies
• uv (Astral package manager) — used to install and run the project
• notebooklm-mcp-cli (nlm) ≥ 0.6.5 — the companion tool that manages your NotebookLM session
• A configured .env file — containing your service-account path, Google Sheet ID, and NotebookLM profile name
• A valid defaults.toml (optional) — if you plan to template default source titles or collaborator labels
• ebcprep installed and authenticated — run ebcprep doctor to confirm everything is connected before experimenting with template expressions

1. Install uv if you have not already:

curl -Ls https://astral.sh/uv/install.sh | sh

2. Clone the ebcprep repository and enter the project directory:

git clone <ebcprep-repo-url>
cd ebcprep-orchestrator

3. Install dependencies using uv:

uv sync

4. Install the nlm companion CLI (required for NotebookLM authentication):

uv pip install "notebooklm-mcp-cli>=0.6.5"

5. Log in to NotebookLM and save a named profile. This opens a Chrome browser window for interactive authentication:

nlm login --profile my-profile

6. Copy the example environment file and fill in your values:

cp .env.example .env

Edit .env to set your service-account JSON path, Google Sheet ID, and the profile name you chose in step 5.

7. Verify your setup with the health-check command:

ebcprep doctor

A clean output means ebcprep can reach your feeder spreadsheet and NotebookLM session. Proceed to configuration once all checks pass.

ebcprep reads configuration from two files at startup.

.env — runtime connection settings

Create this file by copying .env.example. The key fields are:

All values are strings. ebcprep validates these at startup: the service-account file must exist on disk, and the share role must be exactly editor or viewer.

defaults.toml — always-included people and documents

This file is optional. If it is absent, ebcprep treats both lists as empty. Use it to specify collaborators and documents that should appear in every executive notebook.

[[always_collaborator]]
email = "ebc-ops@example.com"
role  = "editor"

[[default_source]]
url   = "https://docs.google.com/document/d/<doc-id>/edit"
title = "Corporate Briefing Standards Guide"

• always_collaborator — each entry must include a valid email address and a role (editor or viewer). This person is invited to every notebook ebcprep creates or updates.
• default_source — each entry must include a valid https:// URL pointing to a Google Doc, Sheet, or Slide. The optional title field sets a human-readable label for the source inside NotebookLM.

ebcprep adds default sources and collaborators idempotently: if a source or collaborator is already present in a notebook, the entry is skipped on subsequent sync runs.

Once ebcprep is installed and configured, your day-to-day workflow revolves around a small set of CLI commands.

Preview what a sync would do (no changes made):

ebcprep sync --dry-run

This reads your feeder spreadsheet and prints every action ebcprep would take — creating notebooks, adding sources, sending invites — without touching NotebookLM or your state database.

Run a full sync to reconcile the sheet with NotebookLM:

ebcprep sync

ebcprep processes every row in the feeder sheet. Rows whose content hash already exists in the state database (data/ebcprep.db) are skipped automatically, so only new or changed meetings trigger API calls.

Check which executives and notebooks are tracked:

ebcprep execs

Inspect the meetings recorded for a specific executive:

ebcprep meetings "Jane Smith"

Generate mind maps for all executives whose notebooks have sources:

ebcprep mindmaps

Publish the team portal — a local HTML page listing every executive's notebook URL:

ebcprep export

This writes index.html to your working directory. Open it in a browser or share it with your EBC team.

Run the health check at any time to validate configuration and connectivity:

ebcprep doctor

Preview a sync before making changes

Always start with a dry run when you have added new rows to the feeder sheet.

ebcprep sync --dry-run

Expected output (example):

[dry-run] Would create notebook: Jane Smith — EBC 2025
[dry-run] Would add source: Acme Corp · 2025-08-14 · 09:00–10:00
[dry-run] Would invite: jane.smith@acme.com (editor)
[dry-run] Would invite: ebc-ops@example.com (editor)
No changes written.

Run a sync after confirming the dry run looks correct

ebcprep sync

Expected output (example):

Reading feeder sheet … 12 rows found, 3 complete, 9 skipped (already processed)
Created notebook: Jane Smith — EBC 2025 (id: abc123)
Added source: Acme Corp · 2025-08-14 · 09:00–10:00
Invited jane.smith@acme.com as editor
Invited ebc-ops@example.com as editor
Sync complete: 1 notebook created, 1 source added, 2 invites sent, 0 errors

Inspect a specific executive's synced meetings

ebcprep meetings "Jane Smith"

Expected output (example):

Meetings for Jane Smith:
  2025-08-14  09:00–10:00  Acme Corp        [source added]
  2025-08-21  14:00–15:30  Globex Inc       [source added]

Generate mind maps for all executives

ebcprep mindmaps

Expected output (example):

Generating mind map for Jane Smith … done (artifact: mm_xyz789)
Generating mind map for Bob Jones … done (artifact: mm_def456)
2 mind maps created.

Publish the team portal

ebcprep export

Expected output (example):

Portal written to index.html (2 executives)

Open index.html in your browser to see a page listing each executive's NotebookLM notebook URL.

NotebookLM session expired

Symptom: ebcprep sync fails with an authentication or cookie error referencing NotebookLM.

Likely cause: The NotebookLM session saved in your nlm profile has expired. Sessions typically last 2–4 weeks.

Fix: Re-run the login command with your profile name to refresh the session:

nlm login --profile my-profile

Then re-run ebcprep doctor to confirm the session is valid before syncing again.

Service-account file not found

Symptom: ebcprep doctor reports that the service-account file cannot be found.

Likely cause: The path set in GOOGLE_APPLICATION_CREDENTIALS inside your .env file does not exist or is relative to the wrong working directory.

Fix: Confirm the file path:

ls -la ./keys/my-sa.json

Update the GOOGLE_APPLICATION_CREDENTIALS value in .env to match the correct absolute or relative path, then re-run ebcprep doctor.

Feeder sheet rows are skipped unexpectedly

Symptom: New rows you added to the feeder sheet are not processed during sync.

Likely cause A: The rows are incomplete — they are missing a valid exec name, prep-doc URL, or exec email address. ebcprep only processes rows where all three are present and valid.

Fix: Check the sync output for skipped-row messages. Open the feeder sheet and confirm that columns H (exec name), I (doc URL), and L (exec email) are all filled in correctly for the affected rows.

Likely cause B: The content hash for the row already exists in the state database from a previous run, even if the row appears new to you.

Fix: Run with --dry-run to see which rows would be processed. If you need to force a row to be re-processed, you can delete data/ebcprep.db to reset all state — but note this causes ebcprep to re-create all notebooks and re-add all sources on the next sync.

defaults.toml entries are not applied

Symptom: Always-included collaborators or default sources do not appear in newly created notebooks.

Likely cause: The defaults.toml file has a syntax error or is located in the wrong directory.

Fix: Validate your TOML syntax (any online TOML linter works) and confirm the file is in the project root alongside your .env. Run ebcprep doctor — it reports configuration-loading errors including malformed defaults.toml entries.

ebcprep doctor reports a wrong share role

Symptom: Doctor output shows a validation error about the share role.

Likely cause: The SHARE_ROLE value in .env is not exactly editor or viewer (for example, Editor with a capital E, or write).

Fix: Edit .env and set SHARE_ROLE to exactly editor or viewer in lowercase.