qodev-apollo-cli 0.1.0__py3-none-any.whl

apollo_cli/__init__.py

@@ -0,0 +1,3 @@
+"""Apollo CLI — Agent-friendly command line interface for the Apollo API."""
+
+__version__ = "0.1.0"

apollo_cli/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running as `python -m apollo_cli`."""
+
+from apollo_cli.app import main
+
+main()

apollo_cli/app.py

@@ -0,0 +1,120 @@
+"""Root App definition, global options, and error handling."""
+
+from __future__ import annotations
+
+import sys
+from typing import Annotated
+
+from cyclopts import App, Group, Parameter
+from qodev_apollo_api import APIError, AuthenticationError, RateLimitError
+
+import apollo_cli.context as _ctx
+
+app = App(
+    name="apollo",
+    help="Agent-friendly CLI for the Apollo API.",
+    help_format="rich",
+    version_flags=[],
+)
+
+app.meta.group_parameters = Group("Global Options", sort_key=0)
+
+
+# ---------------------------------------------------------------------------
+# Import and register command groups
+# ---------------------------------------------------------------------------
+from apollo_cli.commands.accounts import accounts_app  # noqa: E402
+from apollo_cli.commands.calls import calls_app  # noqa: E402
+from apollo_cli.commands.contacts import contacts_app  # noqa: E402
+from apollo_cli.commands.deals import deals_app  # noqa: E402
+from apollo_cli.commands.emails import emails_app  # noqa: E402
+from apollo_cli.commands.enrich import enrich_app  # noqa: E402
+from apollo_cli.commands.install import install_app  # noqa: E402
+from apollo_cli.commands.jobs import jobs_app  # noqa: E402
+from apollo_cli.commands.news import news_app  # noqa: E402
+from apollo_cli.commands.notes import notes_app  # noqa: E402
+from apollo_cli.commands.people import people_app  # noqa: E402
+from apollo_cli.commands.pipelines import pipelines_app, stages_app  # noqa: E402
+from apollo_cli.commands.tasks import tasks_app  # noqa: E402
+from apollo_cli.commands.usage import usage_app  # noqa: E402
+
+# Register all sub-apps
+_sub_apps = [
+    contacts_app,
+    accounts_app,
+    deals_app,
+    pipelines_app,
+    stages_app,
+    enrich_app,
+    people_app,
+    notes_app,
+    tasks_app,
+    calls_app,
+    emails_app,
+    news_app,
+    jobs_app,
+    usage_app,
+    install_app,
+]
+
+for sub in _sub_apps:
+    app.command(sub)
+    sub.help_epilogue = ""  # Prevent epilogue propagation
+
+# Build dynamic help epilogue
+from apollo_cli.help_reference import build_command_reference  # noqa: E402
+
+app.help_epilogue = build_command_reference(_sub_apps)
+
+
+# ---------------------------------------------------------------------------
+# Meta launcher — global options & error handling
+# ---------------------------------------------------------------------------
+
+EXIT_AUTH = 80
+EXIT_RATE_LIMIT = 81
+EXIT_API = 82
+EXIT_VALIDATION = 83
+
+
+@app.meta.default
+def launcher(
+    *tokens: Annotated[str, Parameter(show=False, allow_leading_hyphen=True)],
+    json: Annotated[bool, Parameter(name="--json", help="Output as JSON", negative="")] = False,
+    api_key: Annotated[
+        str | None, Parameter(name="--api-key", help="Apollo API key (overrides APOLLO_API_KEY)", show=False)
+    ] = None,
+    limit: Annotated[int, Parameter(name="--limit", help="Results per page")] = 25,
+    page: Annotated[int, Parameter(name="--page", help="Page number")] = 1,
+) -> None:
+    """Apollo CLI — search contacts, accounts, deals, and more."""
+    # Configure the global context singleton before dispatching to subcommands.
+    _ctx.ctx.configure(json_mode=json, api_key=api_key, limit=limit, page=page)
+
+    try:
+        app(tokens)
+    except AuthenticationError as exc:
+        _handle_error(str(exc), code="authentication", exit_code=EXIT_AUTH)
+    except RateLimitError as exc:
+        msg = str(exc)
+        if exc.retry_after:
+            msg += f" (retry after {exc.retry_after}s)"
+        _handle_error(msg, code="rate_limit", exit_code=EXIT_RATE_LIMIT)
+    except APIError as exc:
+        _handle_error(str(exc), code="api_error", exit_code=EXIT_API)
+    except SystemExit:
+        raise
+    except KeyboardInterrupt:
+        sys.exit(130)
+    except Exception as exc:
+        _handle_error(f"Unexpected error: {exc}", code="unknown", exit_code=1)
+
+
+def _handle_error(message: str, *, code: str, exit_code: int) -> None:
+    from apollo_cli.output import error
+
+    error(message, ctx=_ctx.ctx, code=code, exit_code=exit_code)
+
+
+def main() -> None:
+    app.meta()

apollo_cli/commands/accounts.py

@@ -0,0 +1,51 @@
+"""Accounts command group."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from cyclopts import App, Parameter
+
+from apollo_cli.context import ctx
+from apollo_cli.formatters.accounts import format_account_detail, format_account_list
+from apollo_cli.output import output, output_list
+
+accounts_app = App(name="accounts", help="Manage accounts/companies.")
+
+
+@accounts_app.command
+async def search(
+    *,
+    query: Annotated[str, Parameter(name=["--query", "-q"], help="Search by organization name")] = "",
+    stage_id: Annotated[str | None, Parameter(name="--stage-id", help="Filter by account stage ID")] = None,
+) -> None:
+    """Search accounts by keyword or filter."""
+    filters: dict = {}
+    if query:
+        filters["q_organization_name"] = query
+    if stage_id:
+        filters["account_stage_ids"] = [stage_id]
+
+    async with ctx.client() as client:
+        result = await client.search_accounts(page=ctx.page, limit=ctx.limit, **filters)
+
+    output_list(
+        items=result.items,
+        total=result.total,
+        page=result.page,
+        limit=ctx.limit,
+        ctx=ctx,
+        format_fn=format_account_list,
+        resource_name="Accounts",
+    )
+
+
+@accounts_app.command
+async def get(
+    id: Annotated[str, Parameter(help="Account ID")],
+) -> None:
+    """Get account details by ID."""
+    async with ctx.client() as client:
+        account = await client.get_account(id)
+
+    output(account, ctx=ctx, format_fn=format_account_detail)

apollo_cli/commands/calls.py

@@ -0,0 +1,54 @@
+"""Calls command group."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from cyclopts import App, Parameter
+
+from apollo_cli.context import ctx
+from apollo_cli.formatters.generic import list_table
+from apollo_cli.output import output_json, output_list, output_markdown
+
+calls_app = App(name="calls", help="Call activity.")
+
+CALL_LIST_COLUMNS = [
+    ("ID", "id"),
+    ("Contact ID", "contact_id"),
+    ("Status", "status"),
+    ("Duration", "duration"),
+    ("Start", "start_time"),
+    ("Note", "note"),
+]
+
+
+@calls_app.command
+async def search() -> None:
+    """Search call activities."""
+    async with ctx.client() as client:
+        result = await client.search_calls(page=ctx.page, limit=ctx.limit)
+
+    output_list(
+        items=result.items,
+        total=result.total,
+        page=result.page,
+        limit=ctx.limit,
+        ctx=ctx,
+        format_fn=lambda items, **kw: list_table(items, CALL_LIST_COLUMNS, title="Calls", **kw),
+        resource_name="Calls",
+    )
+
+
+@calls_app.command(name="list")
+async def list_contact_calls(
+    contact_id: Annotated[str, Parameter(help="Contact ID")],
+) -> None:
+    """List calls for a specific contact."""
+    async with ctx.client() as client:
+        result = await client.list_contact_calls(contact_id)
+
+    if ctx.json_mode:
+        output_json(result)
+    else:
+        md = list_table(result, CALL_LIST_COLUMNS, title="Contact Calls", total=len(result), page=1)
+        output_markdown(md)

apollo_cli/commands/contacts.py

@@ -0,0 +1,147 @@
+"""Contacts command group."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from cyclopts import App, Parameter
+
+from apollo_cli.context import ctx
+from apollo_cli.formatters.contacts import (
+    format_contact_detail,
+    format_contact_list,
+    format_stages_list,
+)
+from apollo_cli.output import output, output_list
+
+contacts_app = App(name="contacts", help="Manage contacts.")
+
+
+@contacts_app.command
+async def search(
+    *,
+    query: Annotated[str, Parameter(name=["--query", "-q"], help="Search keyword")] = "",
+    stage_id: Annotated[str | None, Parameter(name="--stage-id", help="Filter by stage ID")] = None,
+    linkedin_url: Annotated[str | None, Parameter(name="--linkedin-url", help="Filter by LinkedIn URL")] = None,
+) -> None:
+    """Search contacts by keyword or filter."""
+    filters: dict = {}
+    if query:
+        filters["q_keywords"] = query
+    if stage_id:
+        filters["contact_stage_ids"] = [stage_id]
+    if linkedin_url:
+        filters["linkedin_url"] = linkedin_url
+
+    async with ctx.client() as client:
+        result = await client.search_contacts(page=ctx.page, limit=ctx.limit, **filters)
+
+    output_list(
+        items=result.items,
+        total=result.total,
+        page=result.page,
+        limit=ctx.limit,
+        ctx=ctx,
+        format_fn=format_contact_list,
+        resource_name="Contacts",
+    )
+
+
+@contacts_app.command
+async def get(
+    id: Annotated[str, Parameter(help="Contact ID")],
+) -> None:
+    """Get contact details by ID."""
+    async with ctx.client() as client:
+        contact = await client.get_contact(id)
+
+    output(contact, ctx=ctx, format_fn=format_contact_detail)
+
+
+@contacts_app.command
+async def create(
+    *,
+    first_name: Annotated[str, Parameter(name="--first-name", help="First name")],
+    last_name: Annotated[str, Parameter(name="--last-name", help="Last name")],
+    email: Annotated[str | None, Parameter(name="--email", help="Email address")] = None,
+    title: Annotated[str | None, Parameter(name="--title", help="Job title")] = None,
+    company: Annotated[str | None, Parameter(name="--company", help="Company name")] = None,
+    linkedin_url: Annotated[str | None, Parameter(name="--linkedin-url", help="LinkedIn URL")] = None,
+) -> None:
+    """Create a new contact."""
+    fields: dict = {}
+    if email:
+        fields["email"] = email
+    if title:
+        fields["title"] = title
+    if company:
+        fields["company_name"] = company
+    if linkedin_url:
+        fields["linkedin_url"] = linkedin_url
+
+    async with ctx.client() as client:
+        result = await client.create_contact(first_name, last_name, **fields)
+
+    output(result, ctx=ctx)
+
+
+@contacts_app.command
+async def update(
+    id: Annotated[str, Parameter(help="Contact ID")],
+    *,
+    title: Annotated[str | None, Parameter(name="--title", help="New job title")] = None,
+    label_ids: Annotated[str | None, Parameter(name="--label-ids", help="Comma-separated label IDs")] = None,
+) -> None:
+    """Update a contact's fields."""
+    fields: dict = {}
+    if title:
+        fields["title"] = title
+    if label_ids:
+        fields["label_ids"] = [lid.strip() for lid in label_ids.split(",")]
+
+    async with ctx.client() as client:
+        result = await client.update_contact(id, **fields)
+
+    output(result, ctx=ctx, format_fn=format_contact_detail)
+
+
+@contacts_app.command(name="find-by-linkedin")
+async def find_by_linkedin(
+    url: Annotated[str, Parameter(help="LinkedIn profile URL")],
+    *,
+    name: Annotated[str | None, Parameter(name="--name", help="Person's full name (for fallback search)")] = None,
+    create_flag: Annotated[bool, Parameter(name="--create", help="Auto-create if not found", negative="")] = False,
+    stage_id: Annotated[str | None, Parameter(name="--stage-id", help="Stage ID for auto-created contact")] = None,
+) -> None:
+    """Find a contact by LinkedIn URL with fallback strategies."""
+    async with ctx.client() as client:
+        contact_id = await client.find_contact_by_linkedin_url(
+            linkedin_url=url,
+            person_name=name,
+            create_if_missing=create_flag,
+            contact_stage_id=stage_id,
+        )
+
+    if contact_id:
+        output({"contact_id": contact_id}, ctx=ctx)
+    else:
+        from apollo_cli.output import error
+
+        error("Contact not found.", ctx=ctx, code="not_found", exit_code=1)
+
+
+@contacts_app.command
+async def stages() -> None:
+    """List contact pipeline stages."""
+    async with ctx.client() as client:
+        result = await client.get_contact_stages()
+
+    if ctx.json_mode:
+        from apollo_cli.output import output_json
+
+        output_json(result)
+    else:
+        from apollo_cli.output import output_markdown
+
+        md = format_stages_list(result, total=len(result), page=1)
+        output_markdown(md)

apollo_cli/commands/deals.py

@@ -0,0 +1,51 @@
+"""Deals command group."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from cyclopts import App, Parameter
+
+from apollo_cli.context import ctx
+from apollo_cli.formatters.deals import format_deal_detail, format_deal_list
+from apollo_cli.output import output, output_list
+
+deals_app = App(name="deals", help="Manage deals/opportunities.")
+
+
+@deals_app.command
+async def search(
+    *,
+    query: Annotated[str, Parameter(name=["--query", "-q"], help="Search keyword")] = "",
+    stage_id: Annotated[str | None, Parameter(name="--stage-id", help="Filter by deal stage ID")] = None,
+) -> None:
+    """Search deals by keyword or filter."""
+    filters: dict = {}
+    if query:
+        filters["q_keywords"] = query
+    if stage_id:
+        filters["opportunity_stage_ids"] = [stage_id]
+
+    async with ctx.client() as client:
+        result = await client.search_deals(page=ctx.page, limit=ctx.limit, **filters)
+
+    output_list(
+        items=result.items,
+        total=result.total,
+        page=result.page,
+        limit=ctx.limit,
+        ctx=ctx,
+        format_fn=format_deal_list,
+        resource_name="Deals",
+    )
+
+
+@deals_app.command
+async def get(
+    id: Annotated[str, Parameter(help="Deal ID")],
+) -> None:
+    """Get deal details by ID."""
+    async with ctx.client() as client:
+        deal = await client.get_deal(id)
+
+    output(deal, ctx=ctx, format_fn=format_deal_detail)

apollo_cli/commands/emails.py

@@ -0,0 +1,37 @@
+"""Emails command group."""
+
+from __future__ import annotations
+
+from cyclopts import App
+
+from apollo_cli.context import ctx
+from apollo_cli.formatters.generic import list_table
+from apollo_cli.output import output_list
+
+emails_app = App(name="emails", help="Email activity.")
+
+EMAIL_LIST_COLUMNS = [
+    ("ID", "id"),
+    ("Subject", "subject"),
+    ("From", "from_email"),
+    ("To", "to_email"),
+    ("Status", "status"),
+    ("Created", "created_at"),
+]
+
+
+@emails_app.command
+async def search() -> None:
+    """Search email activities."""
+    async with ctx.client() as client:
+        result = await client.search_emails(page=ctx.page, limit=ctx.limit)
+
+    output_list(
+        items=result.items,
+        total=result.total,
+        page=result.page,
+        limit=ctx.limit,
+        ctx=ctx,
+        format_fn=lambda items, **kw: list_table(items, EMAIL_LIST_COLUMNS, title="Emails", **kw),
+        resource_name="Emails",
+    )

apollo_cli/commands/enrich.py

@@ -0,0 +1,34 @@
+"""Enrichment command group."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from cyclopts import App, Parameter
+
+from apollo_cli.context import ctx
+from apollo_cli.output import output
+
+enrich_app = App(name="enrich", help="Enrichment operations.")
+
+
+@enrich_app.command
+async def org(
+    domain: Annotated[str, Parameter(help="Company domain (e.g. apollo.io)")],
+) -> None:
+    """Enrich organization data by domain (FREE)."""
+    async with ctx.client() as client:
+        result = await client.enrich_organization(domain)
+
+    output(result, ctx=ctx)
+
+
+@enrich_app.command
+async def person(
+    email: Annotated[str, Parameter(help="Person's email address")],
+) -> None:
+    """Enrich person data by email (costs 1 credit)."""
+    async with ctx.client() as client:
+        result = await client.enrich_person(email)
+
+    output(result, ctx=ctx)

apollo_cli/commands/install.py

@@ -0,0 +1,59 @@
+"""Install CLI resources (skills for AI agents)."""
+
+from __future__ import annotations
+
+import shutil
+from importlib.abc import Traversable
+from importlib.resources import files
+from pathlib import Path
+from typing import Annotated
+
+from cyclopts import App, Parameter
+
+from apollo_cli.output import console
+
+install_app = App(name="install", help="Install CLI resources.")
+
+
+def _install_skills(target_root: Path | None = None) -> Path:
+    """Copy bundled skill files to .claude/skills/apollo/."""
+    root = target_root or Path.cwd()
+    dest = root / ".claude" / "skills" / "apollo"
+
+    source = files("apollo_cli") / "skills"
+
+    if dest.exists():
+        console.print(f"Replacing existing skills at {dest}")
+        shutil.rmtree(dest)
+    dest.mkdir(parents=True)
+
+    _copy_traversable(source, dest)
+    return dest
+
+
+def _copy_traversable(source: Traversable, dest: Path) -> None:
+    """Recursively copy from a Traversable (importlib.resources) to a Path."""
+    for item in source.iterdir():
+        if item.name.startswith("__"):
+            continue
+        target = dest / item.name
+        if item.is_file():
+            target.write_bytes(item.read_bytes())
+        elif item.is_dir():
+            target.mkdir(exist_ok=True)
+            _copy_traversable(item, target)
+
+
+@install_app.default
+def install(
+    *,
+    skills: Annotated[bool, Parameter(name="--skills", help="Install AI agent skill files", negative="")] = False,
+) -> None:
+    """Install CLI resources into the current workspace."""
+    if not skills:
+        from apollo_cli.output import error
+
+        error("No install target specified. Use: qodev-apollo-cli install --skills", code="validation", exit_code=83)
+
+    dest = _install_skills()
+    console.print(f"[green]Installed skills to {dest}[/green]")

apollo_cli/commands/jobs.py

@@ -0,0 +1,36 @@
+"""Jobs command group."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from cyclopts import App, Parameter
+
+from apollo_cli.context import ctx
+from apollo_cli.formatters.generic import list_table
+from apollo_cli.output import output_json, output_markdown
+
+jobs_app = App(name="jobs", help="Job postings.")
+
+JOBS_LIST_COLUMNS = [
+    ("Title", "title"),
+    ("Location", "location"),
+    ("Department", "department"),
+    ("URL", "url"),
+    ("Posted", "posted_at"),
+]
+
+
+@jobs_app.command(name="list")
+async def list_jobs(
+    account_id: Annotated[str, Parameter(help="Account ID")],
+) -> None:
+    """List job postings for an account."""
+    async with ctx.client() as client:
+        result = await client.list_account_jobs(account_id)
+
+    if ctx.json_mode:
+        output_json(result)
+    else:
+        md = list_table(result, JOBS_LIST_COLUMNS, title="Job Postings", total=len(result), page=1)
+        output_markdown(md)

apollo_cli/commands/news.py

@@ -0,0 +1,35 @@
+"""News command group."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from cyclopts import App, Parameter
+
+from apollo_cli.context import ctx
+from apollo_cli.formatters.generic import list_table
+from apollo_cli.output import output_json, output_markdown
+
+news_app = App(name="news", help="Account news.")
+
+NEWS_LIST_COLUMNS = [
+    ("Title", "title"),
+    ("Category", "category"),
+    ("Published", "published_at"),
+    ("URL", "url"),
+]
+
+
+@news_app.command(name="list")
+async def list_news(
+    account_id: Annotated[str, Parameter(help="Account ID")],
+) -> None:
+    """List news articles for an account."""
+    async with ctx.client() as client:
+        result = await client.list_account_news(account_id)
+
+    if ctx.json_mode:
+        output_json(result)
+    else:
+        md = list_table(result, NEWS_LIST_COLUMNS, title="Account News", total=len(result), page=1)
+        output_markdown(md)