ffx-cli 0.1.0__tar.gz

ffx_cli-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,31 @@
+name: CI
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+    branches: ["main"]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Run tests
+        run: uv run pytest --cov=ffx --cov-report=term-missing

ffx_cli-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,44 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Run tests
+        run: uv run pytest
+
+  publish:
+    needs: test
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+
+      - name: Build
+        run: uv build
+
+      - name: Publish to PyPI
+        run: uv publish --trusted-publishing always

ffx_cli-0.1.0/.gitignore

@@ -0,0 +1,26 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
+.env
+
+# uv
+.python-version
+
+# ffx local state
+.ffx/
+
+# Planning docs (not committed)
+TODOS.md
+PLAN.md
+*.plan.md
+
+# Editor
+.DS_Store
+.vscode/
+.idea/

ffx_cli-0.1.0/CLAUDE.md

@@ -0,0 +1,136 @@
+# ffx — Fireflies CLI
+
+## Project
+
+Python CLI tool for the Fireflies.ai GraphQL API. Wraps both primitive API operations
+and higher-level workflow commands. Designed for developer scripting, shell pipelines,
+and AI agent tooling.
+
+## Dev Setup
+
+```bash
+uv sync
+uv pip install -e .
+```
+
+## Tests
+
+```bash
+uv run pytest
+uv run pytest --cov=ffx --cov-report=term-missing   # with coverage
+```
+
+Test strategy: HTTP requests mocked with `respx`. CLI commands tested with
+`typer.testing.CliRunner`. Config tests use `tmp_path` + `FFX_HOME` env override.
+
+## Build and Publish
+
+```bash
+uv build
+uv publish   # requires PYPI_API_TOKEN env var
+```
+
+CI/CD: GitHub Actions triggers on git tag push → tests → build → publish.
+
+## Locked Architecture Decisions
+
+These were decided during design review. Do not change without a documented reason.
+
+**CLI framework: Typer** (not Click)
+- Type hint-driven argument parsing
+- Auto-generates `--help` from docstrings
+- Better DX for flat command tree design
+
+**GraphQL client: gql[httpx]** via `HTTPXTransport` (not raw httpx)
+- Handles GraphQL error envelope automatically
+- Standard Python GraphQL client as of 2025
+
+**API-direct architecture** (no local SQLite cache)
+- All commands hit the Fireflies API directly
+- No sync layer, no local DB, no cache
+- Simpler, fewer failure modes, always-fresh data
+
+## Dropped from Scope
+
+- `ffx objections` — pattern-matched from summary text, unreliable. Do not add back
+  without a structured Fireflies API field or explicit --llm flag.
+- `ffx risks` — same reason as objections.
+- `ffx sync` / local SQLite — dropped after review. API-direct is simpler and sufficient.
+  Commits exist in git history if ever needed.
+- `ffx serve --webhook` — cron + `ffx` commands covers this.
+- MCP adapter — Fireflies already has one.
+- `ffx export notion` — OAuth complexity for niche use case.
+
+## Project Structure
+
+```
+ffx/
+├── __init__.py
+├── api_client.py    # Fireflies GraphQL client (gql + httpx)
+├── models.py        # Dataclasses: Transcript, ActionItem, Speaker, Topic, Summary
+├── config.py        # Config file (~/.ffx/config.yaml) read/write
+├── output.py        # Rich terminal formatting + JSON envelope
+└── commands/
+    ├── __init__.py
+    ├── auth.py          # ffx auth
+    ├── list_cmd.py      # ffx list
+    ├── get.py           # ffx get
+    ├── search.py        # ffx search
+    ├── summary.py       # ffx summary
+    ├── export.py        # ffx export
+    ├── brief.py         # ffx brief
+    ├── action_items.py  # ffx action-items
+    ├── topics.py        # ffx topics
+    ├── speaker.py       # ffx speaker
+    └── week.py          # ffx week / ffx month
+tests/
+├── conftest.py      # Shared fixtures
+├── test_api_client.py
+├── test_config.py
+└── test_commands/
+    └── test_*.py    # One test file per command
+```
+
+## Fireflies API Notes
+
+- Endpoint: `https://api.fireflies.ai/graphql`
+- Auth: `Authorization: Bearer <api_key>`
+- `participants` field is `[String!]` (emails), not objects
+- Summary fields (`action_items`, `bullet_gist`, `topics_discussed`, `outline`,
+  `shorthand_bullet`) are **strings** (newline-delimited), not lists. Only `keywords`
+  is a proper list. Use `Summary.*_list` properties to split into lists.
+- Speaker analytics path: `analytics.speakers` (not `speaker_talk_time_percentage`)
+- Speaker fields: `name`, `speaker_id`, `duration`, `duration_pct`, `word_count`,
+  `words_per_minute`, `filler_words`, `questions`, `longest_monologue`, `monologues_count`
+
+## Error Handling
+
+Standard exit codes:
+- 0: success
+- 1: user error (bad flag, missing required arg)
+- 2: API error (Fireflies unreachable, rate limit exhausted)
+- 3: not found
+
+JSON error envelope (always use in `--json` mode):
+```json
+{"error": "message", "code": "ERROR_CODE", "hint": "Run: ffx auth"}
+```
+
+On AuthError: print "API key may have expired. Run: ffx auth"
+
+## Output Conventions
+
+Standard JSON wrapper (all list-returning commands):
+```json
+{"source": "fireflies", "generated_at": "ISO_TIMESTAMP", "filters": {}, "results": []}
+```
+
+Global flags all commands support: `--json`
+List commands also support: `--days N`, `--limit N`
+
+Default `--limit` for `ffx list`: 10.
+
+## References
+
+- Fireflies API docs: https://docs.fireflies.ai
+- CEO plan: ~/.gstack/projects/fireflies-cli/ceo-plans/2026-03-27-ffx-cli.md

ffx_cli-0.1.0/PKG-INFO

@@ -0,0 +1,9 @@
+Metadata-Version: 2.4
+Name: ffx-cli
+Version: 0.1.0
+Summary: Fireflies.ai CLI
+Requires-Python: >=3.11
+Requires-Dist: gql[httpx]>=3.5
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.7
+Requires-Dist: typer>=0.12

ffx_cli-0.1.0/README.md

@@ -0,0 +1,127 @@
+# ffx — Fireflies CLI
+
+A command-line tool for the [Fireflies.ai](https://fireflies.ai) API. List meetings, read transcripts, pull action items, view speaker analytics, and export to JSON/Markdown/Obsidian/CSV.
+
+All commands output JSON by default — pipe to `jq`, feed to scripts, or use `--table` for human-readable output.
+
+## Install
+
+```bash
+pip install ffx-cli
+# or
+uv tool install ffx-cli
+```
+
+## Setup
+
+Get your API key from [Fireflies Settings](https://app.fireflies.ai/integrations/custom/fireflies) and either:
+
+```bash
+ffx auth                              # interactive prompt, stores in ~/.ffx/config.yaml
+export FIREFLIES_API_KEY=your-key     # env var, overrides config file
+```
+
+## Commands
+
+### Basics
+
+```bash
+ffx list                              # recent meetings (JSON)
+ffx list --table                      # rich formatted table
+ffx list --days 7 --limit 20          # last 7 days, up to 20
+ffx list --participant alice@co.com   # filter by attendee (repeatable)
+
+ffx get <id>                          # single meeting details
+ffx search "quarterly review"         # keyword search
+```
+
+### Summaries & briefs
+
+```bash
+ffx summary <id>                      # AI-generated summary
+ffx brief <id>                        # formatted brief: gist, key points, action items, topics
+ffx brief <id> --table                # rich formatted version
+```
+
+### Action items & topics
+
+```bash
+ffx action-items                      # action items from last 7 days
+ffx action-items --days 30 --filter alice
+ffx topics                            # topics across recent meetings
+ffx topics <id>                       # topics from one meeting
+```
+
+### Full transcript
+
+```bash
+ffx transcript <id>                   # full text with speakers + timestamps (JSON)
+ffx transcript <id> --table           # readable format with timestamps
+ffx transcript <id> --no-timestamps   # just speaker: text
+ffx transcript <id> --no-speakers     # just text
+```
+
+### Speaker analytics
+
+```bash
+ffx speaker <id>                      # talk time, word count, wpm, fillers, questions
+ffx speaker <id> --table              # visual bar chart
+```
+
+### Weekly & monthly rollups
+
+```bash
+ffx week                              # this week: meeting count, hours, action items, top topics
+ffx month                             # this month
+ffx week --table                      # rich formatted
+```
+
+### Export
+
+```bash
+ffx export <id>                       # JSON (default)
+ffx export <id> --format md           # Markdown
+ffx export <id> --format obsidian     # Markdown with YAML frontmatter
+ffx export <id> --format csv          # CSV
+```
+
+## Scripting examples
+
+```bash
+# Get all action items from last week as JSON
+ffx action-items --days 7 | jq '.results[].text'
+
+# Export all recent meetings to markdown files
+ffx list --limit 50 | jq -r '.results[].id' | while read id; do
+  ffx export "$id" --format md > "meeting-$id.md"
+done
+
+# Who talks the most in a meeting?
+ffx speaker <id> | jq '.speakers | sort_by(.duration_pct) | reverse | .[0].name'
+
+# Search and get briefs
+ffx search "product launch" | jq -r '.results[].id' | xargs -I{} ffx brief {}
+```
+
+## Auth
+
+Two methods, env var takes precedence:
+
+| Method | How |
+|--------|-----|
+| Config file | `ffx auth` stores key in `~/.ffx/config.yaml` (chmod 600) |
+| Env var | `export FIREFLIES_API_KEY=your-key` |
+
+## Development
+
+```bash
+git clone https://github.com/bobtista/fireflies-cli.git
+cd fireflies-cli
+uv sync
+uv pip install -e .
+uv run pytest
+```
+
+## License
+
+MIT

ffx_cli-0.1.0/ffx/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

ffx_cli-0.1.0/ffx/__main__.py

@@ -0,0 +1,4 @@
+from ffx.commands import app
+
+if __name__ == "__main__":
+    app()

ffx_cli-0.1.0/ffx/api_client.py

@@ -0,0 +1,261 @@
+from __future__ import annotations
+
+from gql import Client, gql
+from gql.transport.httpx import HTTPXTransport
+
+from ffx.models import (
+    ActionItem,
+    Sentence,
+    Speaker,
+    Summary,
+    Topic,
+    Transcript,
+)
+
+FIREFLIES_API_URL = "https://api.fireflies.ai/graphql"
+
+# participants is [String!] (emails), not objects
+# analytics.speakers is the correct path (not speaker_talk_time_percentage)
+LIST_TRANSCRIPTS_QUERY = gql("""
+    query Transcripts($limit: Int, $skip: Int, $keyword: String, $fromDate: DateTime, $toDate: DateTime, $participants: [String!]) {
+        transcripts(limit: $limit, skip: $skip, keyword: $keyword, fromDate: $fromDate, toDate: $toDate, participants: $participants) {
+            id
+            title
+            date
+            duration
+            organizer_email
+            participants
+            summary {
+                action_items keywords overview gist bullet_gist
+                shorthand_bullet outline short_summary short_overview
+                meeting_type topics_discussed
+            }
+            analytics {
+                speakers {
+                    speaker_id name duration duration_pct word_count
+                    words_per_minute filler_words questions
+                    longest_monologue monologues_count
+                }
+            }
+        }
+    }
+""")
+
+GET_TRANSCRIPT_QUERY = gql("""
+    query Transcript($id: String!) {
+        transcript(id: $id) {
+            id
+            title
+            date
+            duration
+            organizer_email
+            participants
+            summary {
+                action_items keywords overview gist bullet_gist
+                shorthand_bullet outline short_summary short_overview
+                meeting_type topics_discussed
+            }
+            analytics {
+                speakers {
+                    speaker_id name duration duration_pct word_count
+                    words_per_minute filler_words questions
+                    longest_monologue monologues_count
+                }
+            }
+        }
+    }
+""")
+
+
+GET_TRANSCRIPT_WITH_SENTENCES_QUERY = gql("""
+    query Transcript($id: String!) {
+        transcript(id: $id) {
+            id
+            title
+            date
+            duration
+            organizer_email
+            participants
+            summary {
+                action_items keywords overview gist bullet_gist
+                shorthand_bullet outline short_summary short_overview
+                meeting_type topics_discussed
+            }
+            analytics {
+                speakers {
+                    speaker_id name duration duration_pct word_count
+                    words_per_minute filler_words questions
+                    longest_monologue monologues_count
+                }
+            }
+            sentences {
+                index
+                speaker_name
+                speaker_id
+                text
+                raw_text
+                start_time
+                end_time
+            }
+        }
+    }
+""")
+
+
+class AuthError(Exception):
+    pass
+
+
+class ApiError(Exception):
+    pass
+
+
+def _parse_transcript(raw: dict) -> Transcript:
+    summary_raw = raw.get("summary") or {}
+    analytics_raw = raw.get("analytics") or {}
+
+    # Most summary fields come back as strings (with newlines), not lists.
+    # Only keywords is a proper list. We store raw and use .action_items_list etc.
+    summary = Summary(
+        overview=summary_raw.get("overview"),
+        short_overview=summary_raw.get("short_overview"),
+        gist=summary_raw.get("gist"),
+        short_summary=summary_raw.get("short_summary"),
+        bullet_gist=summary_raw.get("bullet_gist"),
+        shorthand_bullet=summary_raw.get("shorthand_bullet"),
+        action_items=summary_raw.get("action_items"),
+        keywords=summary_raw.get("keywords") or [],
+        topics_discussed=summary_raw.get("topics_discussed"),
+        outline=summary_raw.get("outline"),
+        meeting_type=summary_raw.get("meeting_type"),
+    )
+
+    participants = raw.get("participants") or []
+
+    speakers = [
+        Speaker(
+            name=s.get("name", ""),
+            speaker_id=s.get("speaker_id"),
+            duration=s.get("duration", 0),
+            duration_pct=s.get("duration_pct", 0.0),
+            word_count=s.get("word_count", 0),
+            words_per_minute=s.get("words_per_minute", 0.0),
+            filler_words=s.get("filler_words", 0),
+            questions=s.get("questions", 0),
+            longest_monologue=s.get("longest_monologue", 0),
+            monologues_count=s.get("monologues_count", 0),
+        )
+        for s in (analytics_raw.get("speakers") or [])
+    ]
+
+    action_items = [
+        ActionItem(text=item, transcript_id=raw.get("id"))
+        for item in summary.action_items_list
+    ]
+
+    topics = [
+        Topic(text=t, transcript_id=raw.get("id"))
+        for t in summary.topics_list
+    ]
+
+    sentences = [
+        Sentence(
+            index=s.get("index", 0),
+            speaker_name=s.get("speaker_name", ""),
+            speaker_id=s.get("speaker_id"),
+            text=s.get("text", ""),
+            raw_text=s.get("raw_text", ""),
+            start_time=s.get("start_time", 0.0),
+            end_time=s.get("end_time", 0.0),
+        )
+        for s in (raw.get("sentences") or [])
+    ]
+
+    return Transcript(
+        id=raw["id"],
+        title=raw.get("title", "Untitled"),
+        date=str(raw.get("date", "")),
+        duration=raw.get("duration", 0),
+        organizer_email=raw.get("organizer_email"),
+        participants=participants,
+        summary=summary,
+        speakers=speakers,
+        action_items=action_items,
+        topics=topics,
+        sentences=sentences,
+        raw=raw,
+    )
+
+
+class FirefliesClient:
+    def __init__(self, api_key: str) -> None:
+        transport = HTTPXTransport(
+            url=FIREFLIES_API_URL,
+            headers={"Authorization": f"Bearer {api_key}"},
+        )
+        self._client = Client(transport=transport, fetch_schema_from_transport=False)
+
+    def _execute(self, query, variables: dict | None = None) -> dict:
+        try:
+            result = self._client.execute(query, variable_values=variables or {})
+            return result
+        except Exception as e:
+            msg = str(e).lower()
+            if "429" in str(e) or "rate limit" in msg:
+                raise ApiError("rate limit exceeded — retry later") from e
+            if "unauthenticated" in msg or "unauthorized" in msg or "401" in str(e):
+                raise AuthError("API key missing or expired") from e
+            if any(code in str(e) for code in ("500", "502", "503")):
+                raise ApiError(f"Fireflies API error: {e}") from e
+            raise ApiError(str(e)) from e
+
+    def list_transcripts(
+        self,
+        limit: int = 10,
+        skip: int = 0,
+        keyword: str | None = None,
+        from_date: str | None = None,
+        to_date: str | None = None,
+        participants: list[str] | None = None,
+    ) -> list[Transcript]:
+        vars: dict = {"limit": limit, "skip": skip}
+        if keyword:
+            vars["keyword"] = keyword
+        if from_date:
+            vars["fromDate"] = from_date
+        if to_date:
+            vars["toDate"] = to_date
+        if participants:
+            vars["participants"] = participants
+        result = self._execute(LIST_TRANSCRIPTS_QUERY, vars)
+        return [_parse_transcript(t) for t in (result.get("transcripts") or [])]
+
+    def get_transcript(self, transcript_id: str) -> Transcript | None:
+        result = self._execute(GET_TRANSCRIPT_QUERY, {"id": transcript_id})
+        raw = result.get("transcript")
+        if raw is None:
+            return None
+        return _parse_transcript(raw)
+
+    def get_transcript_with_sentences(self, transcript_id: str) -> Transcript | None:
+        result = self._execute(GET_TRANSCRIPT_WITH_SENTENCES_QUERY, {"id": transcript_id})
+        raw = result.get("transcript")
+        if raw is None:
+            return None
+        return _parse_transcript(raw)
+
+    def search_transcripts(
+        self,
+        query: str,
+        limit: int = 20,
+        from_date: str | None = None,
+        to_date: str | None = None,
+        participants: list[str] | None = None,
+    ) -> list[Transcript]:
+        return self.list_transcripts(
+            limit=limit,
+            keyword=query,
+            from_date=from_date,
+            to_date=to_date,
+            participants=participants,
+        )

ffx_cli-0.1.0/ffx/commands/__init__.py

@@ -0,0 +1,29 @@
+import typer
+from ffx.commands.auth import auth
+from ffx.commands.list_cmd import list_cmd
+from ffx.commands.get import get
+from ffx.commands.search import search
+from ffx.commands.summary import summary
+from ffx.commands.brief import brief
+from ffx.commands.action_items import action_items
+from ffx.commands.export import export
+from ffx.commands.topics import topics
+from ffx.commands.speaker import speaker
+from ffx.commands.transcript import transcript
+from ffx.commands.week import week, month
+
+app = typer.Typer(name="ffx", help="Fireflies.ai CLI", no_args_is_help=True)
+
+app.command()(auth)
+app.command("list")(list_cmd)
+app.command()(get)
+app.command()(search)
+app.command()(summary)
+app.command()(brief)
+app.command("action-items")(action_items)
+app.command()(export)
+app.command()(transcript)
+app.command()(topics)
+app.command()(speaker)
+app.command()(week)
+app.command()(month)