name

fireflies-transcript-search

description

Search Fireflies.ai meeting transcripts by keyword and download the full matching transcripts as Markdown. Use when the user wants to find, look up, pull, or read meeting notes or call transcripts from Fireflies by topic, phrase, speaker, or keyword (e.g. "find the meeting where we discussed pricing", "pull my Fireflies calls that mention renewal risk", "search my meeting transcripts for the roadmap").

Fireflies Transcript Search

Drives the main.py CLI in this repo to search Fireflies.ai transcripts and download matching meetings as Markdown. Everything runs through python main.py from the repo root — Python 3.11+, stdlib only, no install step or dependencies needed.

1. Preflight

The CLI reads the API key only from the FIREFLIES_API_KEY environment variable (get_api_key(), main.py:870). If it is unset the command exits with Error: Set FIREFLIES_API_KEY before running this script (exit code 1).
Do not ask for or hardcode the key. If it's missing, tell the user to run export FIREFLIES_API_KEY="…" (key from Fireflies → Integrations → Fireflies API) and stop. Never print or log the key.
Run all commands from the repo root (/home/user/fireflies-transcript-search or wherever the repo is checked out).

2. Pick the mode by intent

User wants…	Command	How you consume it
A quick preview of which meetings match (no download)	`python main.py --dry-run <keywords>`	Read the printed list from stdout
Structured results to reason over (IDs, titles, URLs, durations, matched keywords)	`python main.py search --output-file matches.json <keywords>`	`Read` the JSON file
The full transcript text	`python main.py <keywords>` (search + download)	`Read` the Markdown files it writes
To download from a prior `search` without re-querying	`python main.py download --input-file matches.json`	`Read` the Markdown files

Guidance:

Prefer --dry-run or search --output-file first to see what matches before downloading potentially many transcripts. Only do the full python main.py <keywords> (or download) once you know the matches are the right ones.
Downloaded files land under downloads/YYYY/MM/DD/<title>--<transcript_id>.md (by transcript date; downloads/unknown-date/ if undated). Existing files are skipped unless you pass --overwrite.
Requests are throttled to ~1/sec, so large searches take a while — that's expected.

3. Key flags

--scope {sentences|title|all} — where to match. Default sentences (spoken content). Use title to match only meeting titles, all for the widest net.
--limit-per-keyword N — cap results per keyword. 0 (default) = no local cap (paginates until the API returns a partial page).
--keywords-file <path> — one keyword/phrase per line (# comments allowed) instead of positional keywords.
--output-dir <dir> — where Markdown is written (default downloads).
--overwrite — re-download and replace existing files.
-v / -vv — progress / detailed diagnostics on stderr.

Matching notes:

Multiple keywords = any-keyword (OR) matching. A transcript matching several keywords is downloaded once, listing all matched keywords.
Quote phrases so the shell passes them as one argument, e.g. python main.py "renewal risk".

4. Consuming output

Each transcript line is formatted [start_time-end_time] Speaker: text.
The search JSON contains metadata + merged transcript IDs, titles, URLs, durations, and matched keywords — ideal for filtering before downloading.
After reading, summarize the relevant findings for the user (which meetings, the key passages). Don't dump entire transcripts into the reply.

5. Exit codes & failures

0 success · 1 API error / one-or-more download failures · 2 bad input · 130 interrupted.
A single failed transcript download is reported but doesn't abort the rest.

For the exhaustive flag reference and examples, see README.md in the repo root.

Fireflies Transcript Search

1. Preflight

The CLI reads the API key only from the FIREFLIES_API_KEY environment variable (get_api_key(), main.py:870). If it is unset the command exits with Error: Set FIREFLIES_API_KEY before running this script (exit code 1).

Do not ask for or hardcode the key. If it's missing, tell the user to run export FIREFLIES_API_KEY="…" (key from Fireflies → Integrations → Fireflies API) and stop. Never print or log the key.

Run all commands from the repo root (/home/user/fireflies-transcript-search or wherever the repo is checked out).

2. Pick the mode by intent

User wants…

Command

How you consume it

A quick preview of which meetings match (no download)

python main.py --dry-run <keywords>

Read the printed list from stdout

Structured results to reason over (IDs, titles, URLs, durations, matched keywords)

python main.py search --output-file matches.json <keywords>

Read the JSON file

The full transcript text

python main.py <keywords> (search + download)

Read the Markdown files it writes

To download from a prior search without re-querying

python main.py download --input-file matches.json

Read the Markdown files

Guidance:

Prefer --dry-run or search --output-file first to see what matches before downloading potentially many transcripts. Only do the full python main.py <keywords> (or download) once you know the matches are the right ones.

Downloaded files land under downloads/YYYY/MM/DD/<title>--<transcript_id>.md (by transcript date; downloads/unknown-date/ if undated). Existing files are skipped unless you pass --overwrite.

Requests are throttled to ~1/sec, so large searches take a while — that's expected.

3. Key flags

--scope {sentences|title|all} — where to match. Default sentences (spoken content). Use title to match only meeting titles, all for the widest net.

--limit-per-keyword N — cap results per keyword. 0 (default) = no local cap (paginates until the API returns a partial page).

--keywords-file <path> — one keyword/phrase per line (# comments allowed) instead of positional keywords.

--output-dir <dir> — where Markdown is written (default downloads).

--overwrite — re-download and replace existing files.

-v / -vv — progress / detailed diagnostics on stderr.

Matching notes:

Multiple keywords = any-keyword (OR) matching. A transcript matching several keywords is downloaded once, listing all matched keywords.

Quote phrases so the shell passes them as one argument, e.g. python main.py "renewal risk".

4. Consuming output

Each transcript line is formatted [start_time-end_time] Speaker: text.

The search JSON contains metadata + merged transcript IDs, titles, URLs, durations, and matched keywords — ideal for filtering before downloading.

After reading, summarize the relevant findings for the user (which meetings, the key passages). Don't dump entire transcripts into the reply.

5. Exit codes & failures

0 success · 1 API error / one-or-more download failures · 2 bad input · 130 interrupted.

A single failed transcript download is reported but doesn't abort the rest.

For the exhaustive flag reference and examples, see README.md in the repo root.