Getting Started

This page walks you through installing ebcprep, authenticating with Google and NotebookLM, and running your first sync against a feeder spreadsheet. By the end you will have a working setup that automatically creates per-executive NotebookLM notebooks, populates them with meeting prep documents, and shares them with the right people — all from a single CLI command.

Before you begin, make sure you have the following:

• Python ≥ 3.11 — ebcprep requires a modern Python runtime.
• uv — Astral's fast package manager, used to install and run ebcprep.
• notebooklm-mcp-cli (nlm) ≥ 0.6.5 — a companion CLI that handles the NotebookLM login session ebcprep depends on.
• Google account with NotebookLM access — you must be able to sign in to notebooklm.google.com.
• Chrome browser — required by nlm login for its interactive authentication flow.
• Google Cloud project with Sheets API enabled — ebcprep reads your feeder spreadsheet through the Sheets API.
• GCP service account JSON key with Sheets read access — a non-human Google identity that lets ebcprep read your spreadsheet without your personal credentials.
• A Google Sheet feeder spreadsheet — your single source of truth for executive meetings; see the column layout requirements in the Prepare the feeder spreadsheet guide.

The steps below take you from a clean machine to a completed first sync in the shortest possible path.

1. Install ebcprep

   Copy

   uv tool install ebcprep
   

2. Install the nlm companion CLI

   Copy

   uv tool install notebooklm-mcp-cli
   

3. Sign in to NotebookLM and save a profile

   Copy

   nlm login --profile my-profile
   

   Complete the browser prompt that opens in Chrome.

4. Create your .env configuration file in the project directory:

   Copy

   SERVICE_ACCOUNT_PATH=/path/to/your-service-account.json
   SHEET_ID=your-google-sheet-id
   NLM_PROFILE=my-profile
   

5. Verify everything is wired up correctly

   Copy

   ebcprep doctor
   

6. Preview what the first sync will do (no changes made)

   Copy

   ebcprep sync --dry-run
   

7. Run the sync

   Copy

   ebcprep sync
   

That's it. ebcprep reads your feeder sheet, creates notebooks in NotebookLM, adds prep documents as named sources, and sends invites — then records everything in data/ebcprep.db so future runs skip completed work.

Follow these steps in order. Each step includes what you are doing, the exact command, and what a successful outcome looks like.

Step 1 — Install ebcprep

Use uv to install ebcprep as a global tool so the ebcprep command is available anywhere on your machine.

uv tool install ebcprep

✅ Success: running ebcprep --help prints the command reference without errors.

Step 2 — Install the nlm companion CLI

ebcprep does not talk to NotebookLM directly with your credentials. Instead it relies on a saved session created by notebooklm-mcp-cli (the nlm command). Install it the same way:

uv tool install notebooklm-mcp-cli

✅ Success: nlm --version reports 0.6.5 or higher.

Step 3 — Sign in to NotebookLM

Run nlm login with a profile name you choose. This opens Chrome so you can complete Google's interactive auth flow. The session is saved under the profile name you supply; ebcprep will reference this name in .env.

nlm login --profile my-profile

Complete the sign-in in the browser window that opens. When Chrome closes automatically, the session is saved.

✅ Success: the terminal prints a confirmation that the profile was saved (e.g., Profile 'my-profile' saved).

Step 4 — Create a GCP service account key

ebcprep reads your feeder spreadsheet using a GCP service account — a non-human Google identity — so it never needs your personal password. In your Google Cloud project:

1. Navigate to IAM & Admin → Service Accounts and create a new service account.
2. Grant it the Viewer role on the project (or share the spreadsheet directly with the service account email).
3. Create and download a JSON key for the service account.
4. Enable the Google Sheets API in your project if you have not already.

✅ Success: you have a .json key file on disk and the Sheets API is enabled.

Step 5 — Configure the .env file

Create a file named .env in the directory from which you will run ebcprep. This file tells ebcprep where your service account key lives, which spreadsheet to read, and which NotebookLM profile to use.

SERVICE_ACCOUNT_PATH=/path/to/your-service-account.json
SHEET_ID=your-google-sheet-id
NLM_PROFILE=my-profile

Replace each value with your actual paths and IDs. The SHEET_ID is the long string in your Google Sheet's URL between /d/ and /edit.

✅ Success: the file is saved and contains all three keys.

Step 6 — Run the health check

Before syncing, use ebcprep doctor to verify that every configuration value is valid and that ebcprep can reach both your spreadsheet and your NotebookLM session. This is the fastest way to catch misconfigured paths or missing API access.

ebcprep doctor

✅ Success: all checks pass and the output shows no errors. If any check fails, see the Troubleshooting section below.

Step 7 — Preview the sync with --dry-run

Before making any changes, run a dry run to see exactly what ebcprep would create or update. No notebooks are created, no sources are added, and no invites are sent during a dry run.

ebcprep sync --dry-run

✅ Success: the output lists the executives and meetings ebcprep found, plus the actions it would take.

Step 8 — Run the sync

Once the dry-run output looks correct, run the actual sync:

ebcprep sync

ebcprep reads every row in your feeder sheet, creates a NotebookLM notebook for each executive (or locates an existing one), adds each meeting's prep document as a named source, and invites the executive plus any EA/COS addresses found in the sheet. Completed work is recorded in data/ebcprep.db.

✅ Success: the output shows each notebook and source processed, ending with a summary of rows handled and rows skipped (because they were already complete from a prior run).

Example 1 — Checking your setup before the first sync

Run the doctor command to validate all configuration and connectivity at once:

ebcprep doctor

Expected output (all checks passing):

[✓] .env loaded — SERVICE_ACCOUNT_PATH, SHEET_ID, NLM_PROFILE present
[✓] Service account key found at /path/to/your-service-account.json
[✓] Sheets API reachable — feeder spreadsheet opened successfully
[✓] NotebookLM session valid — profile 'my-profile' authenticated
All checks passed. You are ready to sync.

Example 2 — Dry run showing pending work

Before committing to a sync, preview exactly what would happen:

ebcprep sync --dry-run

Expected output:

[DRY RUN] No changes will be made.

Found 3 unprocessed meeting rows:
  • Jane Smith   — Acme Corp       2025-08-12 10:00–11:00
  • Jane Smith   — Globex Inc      2025-08-14 14:00–15:00
  • Robert Lee   — Initech LLC     2025-08-13 09:00–10:00

Planned actions:
  CREATE notebook  → "Jane Smith — EBC Prep"
  ADD source       → "Acme Corp | 2025-08-12 | 10:00–11:00"
  ADD source       → "Globex Inc | 2025-08-14 | 14:00–15:00"
  INVITE           → jane.smith@example.com (editor)
  CREATE notebook  → "Robert Lee — EBC Prep"
  ADD source       → "Initech LLC | 2025-08-13 | 09:00–10:00"
  INVITE           → robert.lee@example.com (editor)

Re-run without --dry-run to apply these changes.

Example 3 — Running a sync and reviewing results

ebcprep sync

Expected output:

Syncing feeder sheet (Sheet ID: 1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms)...

[1/3] Jane Smith — Acme Corp 2025-08-12
      ✓ Notebook created
      ✓ Source added: "Acme Corp | 2025-08-12 | 10:00–11:00"
      ✓ Invited: jane.smith@example.com

[2/3] Jane Smith — Globex Inc 2025-08-14
      ✓ Source added: "Globex Inc | 2025-08-14 | 14:00–15:00"
      (notebook already exists — skipped create)

[3/3] Robert Lee — Initech LLC 2025-08-13
      ✓ Notebook created
      ✓ Source added: "Initech LLC | 2025-08-13 | 09:00–10:00"
      ✓ Invited: robert.lee@example.com

Sync complete. 3 rows processed, 0 skipped.
State saved to data/ebcprep.db.

Example 4 — Re-running sync safely after adding a new meeting row

After adding a fourth row to your feeder sheet, re-run the same command:

ebcprep sync

Expected output (only the new row is processed):

Syncing feeder sheet...

[1/4] Jane Smith — Acme Corp 2025-08-12   ← skipped (already processed)
[2/4] Jane Smith — Globex Inc 2025-08-14  ← skipped (already processed)
[3/4] Robert Lee — Initech LLC 2025-08-13 ← skipped (already processed)
[4/4] Robert Lee — Umbrella Corp 2025-08-20
      ✓ Source added: "Umbrella Corp | 2025-08-20 | 11:00–12:00"
      (notebook already exists — skipped create)

Sync complete. 1 row processed, 3 skipped.

Use the following table to diagnose and fix the most common issues.

ebcprep doctor reports: NLM_PROFILE not found or session expired

• Cause: Either NLM_PROFILE in .env does not match the name used during nlm login, or the saved session has expired.
• Fix: Re-run nlm login --profile <name>, using exactly the same profile name set in .env. Confirm the profile name has no extra spaces or capitalisation differences.

ebcprep doctor reports: Could not open feeder spreadsheet

• Cause: The service account does not have access to the sheet, the SHEET_ID value is wrong, or the Sheets API is not enabled in your GCP project.
• Fix:
  1. Confirm SHEET_ID in .env matches the ID in the spreadsheet URL.
  2. Share the Google Sheet with the service account email address (found in your JSON key file under client_email).
  3. Verify the Sheets API is enabled at Google Cloud Console → APIs & Services → Enabled APIs.

ebcprep doctor reports: Service account key not found

• Cause: SERVICE_ACCOUNT_PATH in .env points to a file that does not exist or is mistyped.
• Fix: Double-check the path. Use an absolute path to avoid ambiguity (e.g., /home/you/keys/sa.json rather than ~/keys/sa.json).

ebcprep sync processes zero rows even though the sheet has data

• Cause: All rows were already recorded in data/ebcprep.db from a prior run, so ebcprep correctly skips them.
• Fix: If you genuinely want to re-process everything (for example, after a mistake), delete data/ebcprep.db. ebcprep will perform a full re-sync on the next run. Do this with caution — it will re-create sources and re-send invites.

nlm login opens Chrome but closes immediately without saving a profile

• Cause: Chrome may not be installed in the default location, or a corporate policy is blocking the interactive auth window.
• Fix: Ensure Chrome is installed and is your system default browser. If a corporate proxy or SSO intercepts the auth flow, complete the login on an unmanaged network or contact your IT administrator.

ebcprep command is not found after installation

• Cause: uv tool install succeeded, but the uv tools bin directory is not on your PATH.
• Fix: Add the uv tools directory to your shell profile. For most systems:
  Copy

  export PATH="$HOME/.local/bin:$PATH"
  

  Then reload your shell (source ~/.bashrc or open a new terminal) and re-run ebcprep --help.