| 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.
