dromad 0.1.0__py3-none-any.whl

dromad/__init__.py

@@ -0,0 +1,14 @@
+"""Dromad: GEO research tools for coding agents.
+
+This distribution is the client half of Dromad: the ``dromad`` command, the
+HTTP client under it, and the pydantic schemas in :mod:`dromad.schemas` that
+are the contract with the hosted service. The service imports those schemas;
+nothing here imports the service.
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("dromad")
+except PackageNotFoundError:  # a source tree on sys.path without an install
+    __version__ = "0.0.0+unknown"

dromad/cli/analyses.py

@@ -0,0 +1,62 @@
+"""``dromad analyses list`` and ``dromad analyses show``."""
+
+import typer
+
+from dromad import config
+from dromad.cli.citations import render_citations
+from dromad.cli.fanout import render_fanout
+from dromad.cli.output import emit_json, errors_reported, table
+from dromad.client import Client
+from dromad.schemas.analyses import CitationAnalysis
+from dromad.schemas.ids import IdKind, is_id
+
+app = typer.Typer(help="Inspect analyses: results derived from runs.", no_args_is_help=True)
+
+JSON_OPTION = typer.Option(False, "--json", help="Print one JSON document to stdout.")
+API_URL_OPTION = typer.Option(None, "--api-url", help="Dromad server.")
+
+
+@app.command("list")
+def list_analyses(
+    kind: str | None = typer.Option(None, "--kind", help="Only one kind: fanout or citations."),
+    limit: int = typer.Option(20, "--limit", min=1, max=200),
+    api_url: str | None = API_URL_OPTION,
+    as_json: bool = JSON_OPTION,
+) -> None:
+    """Your analyses, newest first."""
+    with errors_reported(as_json=as_json), Client.from_settings(config.resolve(api_url)) as client:
+        listing = client.list_analyses(kind=kind, limit=limit)
+    if as_json:
+        emit_json(listing)
+        return
+    if not listing.items:
+        typer.echo(
+            'No analyses yet. Generate your first questions:\n\n  dromad fanout "AI search API"'
+        )
+        return
+    rows = [
+        [a.id, a.kind, a.status, a.run_count, a.created_at.strftime("%Y-%m-%d %H:%M"), a.subject]
+        for a in listing.items
+    ]
+    typer.echo(table(rows, ["ID", "KIND", "STATUS", "RUNS", "CREATED", "SUBJECT"]))
+
+
+@app.command("show")
+def show(
+    analysis_id: str = typer.Argument(..., help="An analysis ID (fa_… or ca_…)."),
+    api_url: str | None = API_URL_OPTION,
+    as_json: bool = JSON_OPTION,
+) -> None:
+    """One analysis, in full."""
+    if not is_id(analysis_id, IdKind.FANOUT_ANALYSIS, IdKind.CITATION_ANALYSIS):
+        raise typer.BadParameter(
+            f"{analysis_id!r} is not an analysis ID (fa_… or ca_…)", param_hint="ANALYSIS_ID"
+        )
+    with errors_reported(as_json=as_json), Client.from_settings(config.resolve(api_url)) as client:
+        analysis = client.get_analysis(analysis_id)
+    if as_json:
+        emit_json(analysis)
+    elif isinstance(analysis, CitationAnalysis):
+        typer.echo(render_citations(analysis))
+    else:
+        typer.echo(render_fanout(analysis))

dromad/cli/audit.py

@@ -0,0 +1,167 @@
+"""``dromad audit`` — what one page looks like to a crawler, and what follows."""
+
+import time
+
+import typer
+
+from dromad import config
+from dromad.cli.exit_codes import ExitCode
+from dromad.cli.output import emit_json, errors_reported, info
+from dromad.client import Client
+from dromad.client.errors import DromadError
+from dromad.schemas.audit import AuditReport, AuditResult
+from dromad.schemas.runs import TERMINAL_RUN_STATUSES, Run
+
+STATUS_MARK = {"fail": "✗", "error": "!", "pass": "✓", "not_applicable": "–"}
+
+
+def _line(label: str, value) -> str:
+    return f"{label:<12} {value}"
+
+
+def render_audit(result: AuditResult, run_id: str) -> str:
+    fetch, content, meta, structure = (
+        result.fetch,
+        result.content,
+        result.metadata,
+        result.structure,
+    )
+    lines = [result.page.url]
+    if result.page.final_url != result.page.url:
+        lines.append(f"  → {result.page.final_url}")
+    hops = len(fetch.redirect_chain)
+    parts = [f"{fetch.status} {fetch.http_status or ''}".strip(), fetch.content_type or "–"]
+    parts.append(f"{fetch.elapsed_ms} ms")
+    if hops:
+        parts.append(f"{hops} redirect{'s' if hops > 1 else ''}")
+    if fetch.robots_txt and fetch.robots_txt.allows_page is False:
+        parts.append("robots.txt disallows")
+    lines += ["", _line("Fetched", " · ".join(parts))]
+    if fetch.error:
+        lines.append(_line("", fetch.error))
+    if meta.title is not None or content.extraction_method:
+        lines += [
+            _line("Title", meta.title or "—"),
+            _line("Description", meta.description or "—"),
+            _line("Canonical", meta.canonical or "—"),
+            _line("Language", meta.lang or "—"),
+        ]
+        links = content.links
+        lines.append(
+            _line(
+                "Content",
+                f"{content.word_count:,} words · {content.code_blocks} code blocks · "
+                f"{content.tables} tables · {links.total} links ({links.internal} internal) · "
+                f"via {content.extraction_method}",
+            )
+        )
+        if content.likely_js_dependent:
+            lines.append(
+                _line("", "looks like a JavaScript shell (Dromad does not run JavaScript)")
+            )
+        skips = len(structure.level_skips)
+        lines.append(
+            _line(
+                "Outline",
+                # The outline is the main content's; whether the page has an h1
+                # at all is the missing_h1 finding, which looks at the whole page.
+                f"{len(structure.headings)} headings in the main content · "
+                f"{skips} level skip{'s' if skips != 1 else ''}",
+            )
+        )
+        if meta.structured_data_types or meta.structured_data_errors:
+            types = ", ".join(meta.structured_data_types) or "—"
+            errors = (
+                f" · {meta.structured_data_errors} unparseable"
+                if meta.structured_data_errors
+                else ""
+            )
+            lines.append(_line("Structured", types + errors))
+        if meta.dates.published or meta.dates.modified:
+            lines.append(
+                _line(
+                    "Dates",
+                    f"published {meta.dates.published or '—'} · modified {meta.dates.modified or '—'}",
+                )
+            )
+    if meta.llms_txt:
+        probes = " · ".join(
+            f"{p.url.split('://', 1)[-1]} "
+            + (f"found ({p.links} links)" if p.found else str(p.http_status or "no response"))
+            for p in meta.llms_txt
+        )
+        lines.append(_line("llms.txt", probes))
+
+    lines += ["", "FINDINGS"]
+    width = max(len(f.key) for f in result.findings) if result.findings else 0
+    for finding in result.findings:
+        mark = STATUS_MARK.get(finding.status, "?")
+        head = f"  {mark} {finding.key:<{width}}  {finding.status:<14} {finding.severity:<6} {finding.evidence_level}"
+        lines.append(head.rstrip())
+        for item in finding.items:
+            lines.append(f"      {item.summary}")
+        if finding.status in ("not_applicable", "error") and finding.reason:
+            lines.append(f"      {finding.reason}")
+    lines += ["", f"Run {run_id}"]
+    return "\n".join(lines)
+
+
+def render_audit_run(run: Run) -> str:
+    if isinstance(run.result, AuditResult):
+        return render_audit(run.result, run.id)
+    if run.error:
+        return "\n".join(
+            [
+                f"{run.input.get('url', '')}",
+                f"✗  {run.error.code}",
+                run.error.message,
+                f"Retryable: {'yes' if run.error.retryable else 'no'}",
+                f"Run {run.id}",
+            ]
+        )
+    return f"{run.input.get('url', '')}\n…  {run.status}\nRun {run.id}"
+
+
+def wait_for_run(client: Client, run_id: str, *, timeout: float) -> Run:
+    deadline = time.monotonic() + timeout
+    while True:
+        remaining = deadline - time.monotonic()
+        run = client.get_run(run_id, wait=max(0, min(30, int(remaining))))
+        if run.status in TERMINAL_RUN_STATUSES:
+            return run
+        if time.monotonic() >= deadline:
+            raise DromadError(
+                "timeout",
+                f"Run {run_id} is still running after {timeout:g}s. It continues; "
+                f"check it with `dromad runs show {run_id}`.",
+                retryable=True,
+            )
+
+
+def audit(
+    url: str = typer.Argument(..., help="The page to audit."),
+    wait: bool = typer.Option(True, "--wait/--no-wait", help="Wait for the result (default)."),
+    timeout: int = typer.Option(180, "--timeout", help="Seconds to wait."),
+    api_url: str | None = typer.Option(None, "--api-url", help="Dromad server."),
+    as_json: bool = typer.Option(False, "--json", help="Print one JSON document to stdout."),
+) -> None:
+    """Fetch one page as a crawler would and report its facts and findings.
+
+    Every finding says how strongly it is backed (evidence_level): an observed
+    fact, an established consequence, a suggestive signal, or an experimental
+    hypothesis. The result is a run (dr_…) that keeps the full captured page.
+    """
+    with errors_reported(as_json=as_json), Client.from_settings(config.resolve(api_url)) as client:
+        run = client.create_audit(url)
+        if wait:
+            info(f"Auditing {url} · run {run.id}")
+            run = wait_for_run(client, run.id, timeout=timeout)
+    if as_json:
+        if isinstance(run.result, AuditResult):
+            emit_json(AuditReport(run_id=run.id, **run.result.model_dump()))
+        else:
+            emit_json(run)
+    else:
+        typer.echo(render_audit_run(run))
+    if run.status == "failed":
+        raise typer.Exit(int(ExitCode.FAILURE))

dromad/cli/auth.py

@@ -0,0 +1,136 @@
+"""``dromad login``, ``dromad logout``, ``dromad whoami``."""
+
+import os
+import socket
+import time
+import webbrowser
+from datetime import UTC, datetime
+
+import typer
+
+from dromad import config
+from dromad.cli.output import emit_json, errors_reported, info
+from dromad.client import Client
+from dromad.client.errors import ApiError, ConnectionFailed, DromadError
+from dromad.schemas.auth import CLIAuthStatus
+
+# Indirection so tests can run the polling loop without waiting.
+_sleep = time.sleep
+_monotonic = time.monotonic
+
+JSON_OPTION = typer.Option(False, "--json", help="Print one JSON document to stdout.")
+
+
+def _default_client_name() -> str:
+    return f"dromad CLI on {socket.gethostname()}"
+
+
+def login(
+    api_url: str | None = typer.Option(
+        None, "--api-url", help="Dromad server (default: DROMAD_API_URL, else dromad.dev)."
+    ),
+    name: str | None = typer.Option(
+        None, "--name", help="How this device appears under your account's sessions."
+    ),
+    no_browser: bool = typer.Option(
+        False, "--no-browser", help="Print the sign-in URL instead of opening it."
+    ),
+    as_json: bool = JSON_OPTION,
+) -> None:
+    """Sign in through the browser and store a CLI token for this device."""
+    with errors_reported(as_json=as_json):
+        settings = config.resolve(api_url)
+        with Client(settings.api_url, token=None) as client:
+            start = client.cli_auth_start(name or _default_client_name())
+            info("To sign in, open this URL in a browser:")
+            info(f"\n  {start.verification_uri_complete}\n")
+            info(f"and check that it shows the code  {start.user_code}\n")
+            if not no_browser:
+                try:
+                    webbrowser.open(start.verification_uri_complete)
+                except webbrowser.Error:
+                    pass
+            info("Waiting for approval…")
+
+            deadline = _monotonic() + start.expires_in
+            while True:
+                _sleep(start.interval)
+                poll = client.cli_auth_poll(start.device_code)
+                if poll.status == CLIAuthStatus.APPROVED and poll.token and poll.token_id:
+                    break
+                if poll.status == CLIAuthStatus.DENIED:
+                    raise DromadError("access_denied", "Sign-in was denied in the browser.")
+                if poll.status != CLIAuthStatus.PENDING or _monotonic() > deadline:
+                    raise DromadError(
+                        "expired_token",
+                        "The sign-in request expired before it was approved. "
+                        "Run `dromad login` again.",
+                    )
+
+        path = config.save_credentials(
+            config.StoredCredentials(
+                api_url=settings.api_url,
+                token=poll.token,
+                token_id=poll.token_id,
+                email=poll.email or "",
+                created_at=datetime.now(UTC),
+            )
+        )
+    if as_json:
+        emit_json({"email": poll.email, "token_id": poll.token_id, "api_url": settings.api_url})
+    else:
+        info(f"Logged in as {poll.email}.")
+        info(f"Credentials saved to {path}")
+
+
+def logout(as_json: bool = JSON_OPTION) -> None:
+    """Revoke this device's CLI token and delete the local credentials."""
+    with errors_reported(as_json=as_json):
+        stored = config.load_credentials()
+        revoked = False
+        if stored is not None:
+            try:
+                with Client(stored.api_url, stored.token) as client:
+                    client.revoke_cli_token()
+                revoked = True
+            except ApiError as exc:
+                # Already revoked or expired server-side: nothing left to undo.
+                if exc.status != 401:
+                    raise
+            except ConnectionFailed:
+                info(
+                    f"Could not reach {stored.api_url} to revoke the token; "
+                    "removing the local credentials anyway. Revoke it from "
+                    "your account's sessions page."
+                )
+            config.delete_credentials()
+    env_key_set = bool(os.environ.get(config.ENV_API_KEY))
+    if as_json:
+        emit_json(
+            {
+                "logged_out": stored is not None,
+                "token_revoked": revoked,
+                "api_key_env_set": env_key_set,
+            }
+        )
+        return
+    info("Logged out." if stored is not None else "Not logged in.")
+    if env_key_set:
+        info(f"{config.ENV_API_KEY} is still set; unset it to stop using that key.")
+
+
+def whoami(
+    api_url: str | None = typer.Option(None, "--api-url", help="Dromad server."),
+    as_json: bool = JSON_OPTION,
+) -> None:
+    """Show which account and credential the CLI is using."""
+    with errors_reported(as_json=as_json):
+        settings = config.resolve(api_url)
+        with Client.from_settings(settings) as client:
+            me = client.me()
+    if as_json:
+        emit_json(me)
+        return
+    typer.echo(me.email)
+    typer.echo(f"{me.credential.kind} {me.credential.id} ({me.credential.name})")
+    typer.echo(f"source {settings.source} · {settings.api_url}")

dromad/cli/citations.py

@@ -0,0 +1,133 @@
+"""``dromad citations`` — what a set of prompt runs cited, counted."""
+
+import typer
+
+from dromad import config
+from dromad.cli.output import emit_json, errors_reported, table
+from dromad.cli.render import short_url
+from dromad.client import Client
+from dromad.schemas.analyses import CitationAnalysis
+from dromad.schemas.ids import IdKind, is_id
+
+
+def _pct(numerator: int, denominator: int) -> str:
+    return f"{round(100 * numerator / denominator)}%" if denominator else "–"
+
+
+def _n(count: int, noun: str) -> str:
+    return f"{count} {noun}{'' if count == 1 else 's'}"
+
+
+def render_citations(analysis: CitationAnalysis, *, top: int = 10) -> str:
+    t = analysis.totals
+    lines = [
+        f"{t.runs} prompt runs · {t.prompts} prompts · {t.engines} engines",
+        f"{t.citations} citations · {t.unique_cited_urls} unique URLs · "
+        f"{t.unique_cited_domains} unique domains",
+    ]
+    unknowns = []
+    if t.retrieved_not_cited:
+        unknowns.append(f"{t.retrieved_not_cited} sources seen but not cited")
+    if t.citation_status_unknown:
+        unknowns.append(f"{t.citation_status_unknown} with citation status unknown")
+    if t.unresolved_sources:
+        unknowns.append(f"{t.unresolved_sources} unresolved redirects")
+    if unknowns:
+        lines.append(" · ".join(unknowns))
+
+    if analysis.domains:
+        rows = [
+            [d.domain, d.citations, d.pages, d.runs, d.prompts, ", ".join(d.engines)]
+            for d in analysis.domains[:top]
+        ]
+        lines += ["", table(rows, ["DOMAIN", "CITATIONS", "PAGES", "RUNS", "PROMPTS", "ENGINES"])]
+
+    if len(analysis.engines) > 1:
+        rows = [
+            [e.engine, e.runs, e.runs_with_citations, e.citations, e.unique_cited_domains]
+            for e in analysis.engines
+        ]
+        lines += ["", table(rows, ["ENGINE", "RUNS", "WITH CITATIONS", "CITATIONS", "DOMAINS"])]
+
+    if analysis.pages:
+        lines += ["", "TOP PAGES"]
+        for n, page in enumerate(analysis.pages[:top], 1):
+            lines.append(
+                f"  {n:>2}  {short_url(page.url, 70)}  · {_n(page.citations, 'citation')} · "
+                f"{_n(page.runs, 'run')} · {', '.join(page.engines)}"
+            )
+
+    overlap = analysis.overlap
+    if overlap.engines > 1:
+        by = overlap.domains_by_engine_count
+        parts = [f"by {n}: {by[str(n)]}" for n in range(overlap.engines, 0, -1)]
+        lines += ["", "CROSS-ENGINE OVERLAP", "  cited domains " + " · ".join(parts)]
+        if overlap.domains_cited_by_every_engine:
+            lines.append(
+                "  cited by every engine: " + ", ".join(overlap.domains_cited_by_every_engine)
+            )
+
+    if analysis.textual_mentions:
+        lines += ["", "TEXTUAL MENTIONS  (naive whole-word match in answer text)"]
+        for m in analysis.textual_mentions:
+            lines.append(
+                f"  {m.term}  {m.runs_mentioning} of {m.runs} runs · "
+                f"{m.prompts_mentioning} of {m.prompts} prompts · {m.occurrences} occurrences"
+            )
+
+    for c in analysis.domain_coverage:
+        engines = " · ".join(f"{e.engine} {e.cited_runs}/{e.runs}" for e in c.by_engine)
+        lines += [
+            "",
+            f"DOMAIN COVERAGE  {c.domain}",
+            f"  cited in {c.cited_runs} of {c.runs} runs ({_pct(c.cited_runs, c.runs)}) · "
+            f"{c.cited_prompts} of {c.prompts} prompts · {c.citations} citations",
+            f"  by engine: {engines}",
+        ]
+        if c.unknown_runs:
+            lines.append(
+                f"  {_n(c.unknown_runs, 'run')} did not expose citations; the rate is a floor"
+            )
+        if c.pages:
+            lines.append(f"  pages cited: {', '.join(short_url(p, 60) for p in c.pages[:top])}")
+        if c.prompts_seen_not_cited:
+            lines.append(f"  seen but not cited on {_n(len(c.prompts_seen_not_cited), 'prompt')}")
+        if c.prompts_absent:
+            lines.append(
+                f"  absent from {_n(len(c.prompts_absent), 'prompt')}, e.g. “{c.prompts_absent[0]}”"
+            )
+
+    if analysis.excluded_runs:
+        lines += ["", f"Excluded {len(analysis.excluded_runs)} runs:"]
+        lines += [f"  {e.run_id}  {e.reason}" for e in analysis.excluded_runs]
+    lines += ["", f"Analysis {analysis.id} · {analysis.method}"]
+    return "\n".join(lines)
+
+
+def citations(
+    ids: list[str] = typer.Argument(..., help="Run IDs (dr_…) and/or batch IDs (rq_…)."),
+    brand: list[str] = typer.Option(
+        [], "--brand", "-b", help="A term to count in answers (repeatable). Naive word match."
+    ),
+    domain: list[str] = typer.Option(
+        [], "--domain", "-d", help="A domain to report coverage for (repeatable)."
+    ),
+    top: int = typer.Option(10, "--top", min=1, help="Rows per table."),
+    api_url: str | None = typer.Option(None, "--api-url", help="Dromad server."),
+    as_json: bool = typer.Option(False, "--json", help="Print one JSON document to stdout."),
+) -> None:
+    """Count what a set of prompt runs cited: domains, pages, engines, overlap.
+
+    Only citations an engine showed are counted; sources whose citation
+    status was not exposed are reported as unknown. The result is a durable
+    analysis (ca_…).
+    """
+    bad = [i for i in ids if not is_id(i, IdKind.RUN, IdKind.REQUEST_BATCH)]
+    if bad:
+        raise typer.BadParameter(f"not a run or batch ID: {', '.join(bad)}", param_hint="IDS")
+    with errors_reported(as_json=as_json), Client.from_settings(config.resolve(api_url)) as client:
+        analysis = client.create_citation_analysis(ids, brands=brand, domains=domain)
+    if as_json:
+        emit_json(analysis)
+    else:
+        typer.echo(render_citations(analysis, top=top))

dromad/cli/exit_codes.py

@@ -0,0 +1,14 @@
+"""Process exit codes. Stable: scripts and agents branch on them.
+
+0  the command did what it was asked
+1  the operation failed (the server refused it, an engine failed, no connection)
+2  the command could not be attempted (bad arguments, not logged in, bad config)
+"""
+
+from enum import IntEnum
+
+
+class ExitCode(IntEnum):
+    OK = 0
+    FAILURE = 1
+    USAGE = 2

dromad/cli/fanout.py

@@ -0,0 +1,89 @@
+"""``dromad fanout`` — turn a topic into the questions people ask about it."""
+
+import time
+
+import typer
+
+from dromad import config
+from dromad.cli.exit_codes import ExitCode
+from dromad.cli.output import emit_json, errors_reported, info
+from dromad.client import Client
+from dromad.client.errors import DromadError
+from dromad.schemas.analyses import TERMINAL_ANALYSIS_STATUSES, FanoutAnalysis
+
+
+def render_fanout(analysis: FanoutAnalysis) -> str:
+    lines = [analysis.topic, ""]
+    if analysis.status == "failed" and analysis.error:
+        lines += [f"✗  {analysis.error.code}", analysis.error.message, ""]
+    elif analysis.status != "completed":
+        lines += [f"…  {analysis.status}", ""]
+    else:
+        lines += [
+            f"Generated {len(analysis.questions)} questions across "
+            f"{len(analysis.clusters)} clusters.",
+            "",
+        ]
+        by_id = {q.id: q for q in analysis.questions}
+        width = len(str(len(analysis.questions)))
+        for cluster in analysis.clusters:
+            lines.append(f"{cluster.name.upper()}  ({cluster.intent.replace('_', ' ')})")
+            lines.append("")
+            for question_id in cluster.question_ids:
+                question = by_id[question_id]
+                n = int(question_id.lstrip("q"))
+                tag = f"  [{question.specificity}]" if question.specificity else ""
+                lines.append(f"  {n:>{width}}. {question.text}{tag}")
+            lines.append("")
+    footer = [f"Analysis {analysis.id}"]
+    if analysis.provenance:
+        provenance = analysis.provenance
+        if provenance.model:
+            footer.append(provenance.model)
+        footer.append(
+            f"{provenance.strategy}/v{provenance.prompt_version} (prompt {provenance.prompt_sha[:10]})"
+        )
+    lines.append(" · ".join(footer))
+    return "\n".join(lines)
+
+
+def wait_for_analysis(client: Client, analysis_id: str, *, timeout: float) -> FanoutAnalysis:
+    deadline = time.monotonic() + timeout
+    while True:
+        remaining = deadline - time.monotonic()
+        analysis = client.get_analysis(analysis_id, wait=max(0, min(30, int(remaining))))
+        if analysis.status in TERMINAL_ANALYSIS_STATUSES:
+            return analysis
+        if time.monotonic() >= deadline:
+            raise DromadError(
+                "timeout",
+                f"Analysis {analysis_id} is still running after {timeout:g}s. It continues; "
+                f"check it with `dromad analyses show {analysis_id}`.",
+                retryable=True,
+            )
+
+
+def fanout(
+    topic: str = typer.Argument(..., help='The topic, e.g. "AI search API".'),
+    count: int = typer.Option(30, "--count", min=5, max=100, help="How many questions."),
+    wait: bool = typer.Option(True, "--wait/--no-wait", help="Wait for the questions (default)."),
+    timeout: int = typer.Option(300, "--timeout", help="Seconds to wait."),
+    api_url: str | None = typer.Option(None, "--api-url", help="Dromad server."),
+    as_json: bool = typer.Option(False, "--json", help="Print one JSON document to stdout."),
+) -> None:
+    """Generate the questions people ask AI assistants about a topic, clustered by intent.
+
+    The result is a durable analysis (fa_…) whose questions keep stable IDs
+    (q01…), with the full generation prompt recorded as provenance.
+    """
+    with errors_reported(as_json=as_json), Client.from_settings(config.resolve(api_url)) as client:
+        analysis = client.create_fanout(topic, count)
+        if wait:
+            info(f"Generating {count} questions · analysis {analysis.id}")
+            analysis = wait_for_analysis(client, analysis.id, timeout=timeout)
+    if as_json:
+        emit_json(analysis)
+    else:
+        typer.echo(render_fanout(analysis))
+    if analysis.status == "failed":
+        raise typer.Exit(int(ExitCode.FAILURE))

dromad/cli/main.py

@@ -0,0 +1,49 @@
+"""The ``dromad`` command."""
+
+import typer
+
+from dromad import __version__
+from dromad.cli import analyses, audit, auth, citations, fanout, prompt, runs, share
+from dromad.cli import open as open_command
+from dromad.config import DEFAULT_API_URL
+
+app = typer.Typer(
+    name="dromad",
+    help="GEO research tools for coding agents.",
+    epilog=f"Docs: {DEFAULT_API_URL}/docs/cli · for agents: {DEFAULT_API_URL}/docs/agents.md",
+    no_args_is_help=True,
+    add_completion=False,
+)
+
+
+def _print_version(value: bool) -> None:
+    if value:
+        typer.echo(f"dromad {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    version: bool = typer.Option(
+        False,
+        "--version",
+        callback=_print_version,
+        is_eager=True,
+        help="Print the version and exit.",
+    ),
+) -> None:
+    """GEO research tools for coding agents."""
+
+
+app.command()(auth.login)
+app.command()(auth.logout)
+app.command()(auth.whoami)
+app.command()(fanout.fanout)
+app.command()(prompt.prompt)
+app.command()(citations.citations)
+app.command()(audit.audit)
+app.command(name="open")(open_command.open_page)
+app.command()(share.share)
+app.command()(share.unshare)
+app.add_typer(runs.app, name="runs")
+app.add_typer(analyses.app, name="analyses")