qodev-apollo-cli 0.1.0__tar.gz → 1.0.0__tar.gz

qodev_apollo_cli-1.0.0/CHANGELOG.md

@@ -0,0 +1,63 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [1.0.0] - 2026-07-01
+
+### Added
+
+- **notes**: `--opportunity-ids` on `create` and `--opportunity-id` filter on `search`. The underlying `qodev-apollo-api` client already supported opportunity attachment; only the CLI surface was missing. Enables attaching notes directly to deals/opportunities so they appear in the deal view (previously notes could only be attached to accounts/contacts, which don't surface on the opportunity UI).
+
+### Changed
+
+- **BREAKING — `contacts find-by-linkedin` is now `contacts upsert-by-linkedin`** with honest get-or-create semantics. It returns the full contact plus a `created` flag (not a bare `contact_id`), a missing contact is a normal result rather than an exit-1 `not_found` error, and `--name` is required to create. Before creating it name-searches to avoid duplicating a contact stored under a different URL. Read-only lookups now use `contacts search --linkedin-url`.
+- **internal**: Extracted the inline comma-splitting logic (used in `contacts update --label-ids`, `people search --titles/--locations`, `tasks create --contact-ids`, and `notes create --contact-ids/--account-ids/--opportunity-ids`) into a shared `apollo_cli.util.parse_comma_list` helper. Behavior is now consistent across every comma-list flag.
+
+### Removed
+
+- **BREAKING — `contacts find-by-linkedin`** (and its `--create` flag). The read path is `contacts search --linkedin-url`; the write path is `contacts upsert-by-linkedin`.
+
+### Fixed
+
+- **comma-list flags — forgiving on typos, loud on garbage.** All comma-separated CLI arguments now drop embedded empty segments, whitespace-only tokens, and leading/trailing commas — so `--contact-ids "a,,b"` sends `["a", "b"]` instead of `["a", "", "b"]` (which Apollo rejects with a 400). Empty (`""`) or whitespace-only input maps to "flag not provided", but input like `",,,"` — where the user typed *something* that collapses to nothing — now surfaces as a validation error (exit code 83, `"validation"`) via the CLI's central error handler, instead of a raw Python traceback or a silent flag-omit. Affects every command that takes a comma-list flag.
+- **notes docs**: `README.md` and `skills/SKILL.md` referenced a non-existent `--note` flag on `notes create`; the actual flag has always been `--content`. Also surfaced the already-implemented `--account-id`/`--account-ids` flags in both docs (previously only `--contact-id`/`--contact-ids` were documented). AI agents following `SKILL.md` would have hit `--note` errors.
+- **`contacts search --linkedin-url` now matches reliably.** Apollo stores and exact-matches LinkedIn URLs as `http://www.linkedin.com/in/<slug>` (http, `www`, no trailing slash, lowercase); the filter was passed through verbatim, so a normal `https://.../in/slug/` URL silently returned zero results. Inputs are now canonicalized to Apollo's stored form before searching (new `apollo_cli.linkedin` module).
+
+## [0.1.0] - 2026-02-26
+
+### Added
+
+- Initial CLI implementation with cyclopts framework
+- Dual output mode: Markdown (default, agent/human-friendly) and JSON (`--json`)
+- Global options: `--json`, `--api-key`, `--limit`, `--page`
+- **contacts**: search, get, create, update, find-by-linkedin, stages
+- **accounts**: search, get
+- **deals**: search, get
+- **pipelines**: list, get, stages
+- **stages**: list (all stages across pipelines)
+- **enrich**: org (free), person (1 credit)
+- **people**: search (global database)
+- **notes**: search, create
+- **tasks**: search, create, complete
+- **calls**: search, list (per contact)
+- **emails**: search
+- **news**: list (per account)
+- **jobs**: list (per account)
+- **usage**: API usage stats and rate limits
+- **install**: Install AI agent skill files with `--skills` flag
+- Centralized error handling with semantic exit codes (80-83)
+- Rich markdown rendering for terminal output with `help_format="rich"`
+- Pagination support with page/limit controls
+- Comprehensive README.md with command reference and usage examples
+- MIT License
+- Full PyPI metadata in pyproject.toml
+- CI/CD workflows (lint, typecheck, test, publish)
+- Complete test suite with pytest and pytest-asyncio
+- AI agent skill files (SKILL.md + workflow references)
+- Dynamic help epilogue with all commands
+- Dev dependencies (ruff, mypy, pytest)
+- Tool configurations (ruff, mypy, pytest)
+</content>
+</invoke>

{qodev_apollo_cli-0.1.0 → qodev_apollo_cli-1.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: qodev-apollo-cli
-Version: 0.1.0
+Version: 1.0.0
 Summary: Agent-friendly CLI for the Apollo API
 Project-URL: Homepage, https://github.com/qodevai/apollo-cli
 Project-URL: Repository, https://github.com/qodevai/apollo-cli
@@ -92,7 +92,7 @@ $ qodev-apollo-cli usage
 | | `get` | Get contact details by ID |
 | | `create` | Create a new contact (`--first-name`, `--last-name`, `--email`, etc.) |
 | | `update` | Update contact (`--title`, `--label-ids`) |
-| | `find-by-linkedin` | Find contact by LinkedIn URL (`--create`, `--stage-id`) |
+| | `upsert-by-linkedin` | Get or create a contact by LinkedIn URL (`--name`, `--title`, `--stage-id`) |
 | | `stages` | List all contact stages |
 | **accounts** | `search` | Search companies/accounts (`--query`, `--domain`) |
 | | `get` | Get account details by ID |
@@ -106,8 +106,8 @@ $ qodev-apollo-cli usage
 | **enrich** | `org` | Enrich organization by domain (FREE - no credits) |
 | | `person` | Enrich person by email (1 credit per lookup) |
 | **people** | `search` | Search people database (`--person-titles`, `--q-organization-domains`) |
-| **notes** | `search` | Search notes (`--contact-id`) |
-| | `create` | Create a note (`--contact-ids`, `--note`) |
+| **notes** | `search` | Search notes (`--contact-id`, `--account-id`, `--opportunity-id`) |
+| | `create` | Create a note (`--contact-ids`, `--account-ids`, `--opportunity-ids`, `--content`) |
 | **tasks** | `search` | Search tasks (`--type`, `--status`) |
 | | `create` | Create a task (`--contact-ids`, `--note`, `--due-at`) |
 | **calls** | `search` | Search call activities |
@@ -198,15 +198,15 @@ qodev-apollo-cli deals search --stage-id <stage-id>
 ### LinkedIn integration
 
 ```bash
-# Find contact by LinkedIn URL
-qodev-apollo-cli contacts find-by-linkedin "https://linkedin.com/in/janesmith"
+# Read-only lookup by LinkedIn URL (returns 0..n contacts, never writes)
+qodev-apollo-cli contacts search --linkedin-url "https://linkedin.com/in/janesmith"
 
-# Auto-create if not found
-qodev-apollo-cli contacts find-by-linkedin "https://linkedin.com/in/janesmith" --create
+# Get or create a contact by LinkedIn URL (upsert); --name is required to create
+qodev-apollo-cli contacts upsert-by-linkedin "https://linkedin.com/in/janesmith" --name "Jane Smith"
 
-# Assign to stage on creation
-qodev-apollo-cli contacts find-by-linkedin "https://linkedin.com/in/janesmith" \
-  --create --stage-id <stage-id>
+# Set title / stage when creating
+qodev-apollo-cli contacts upsert-by-linkedin "https://linkedin.com/in/janesmith" \
+  --name "Jane Smith" --title "VP Engineering" --stage-id <stage-id>
 ```
 
 ### Company enrichment (FREE)

{qodev_apollo_cli-0.1.0 → qodev_apollo_cli-1.0.0}/README.md

@@ -61,7 +61,7 @@ $ qodev-apollo-cli usage
 | | `get` | Get contact details by ID |
 | | `create` | Create a new contact (`--first-name`, `--last-name`, `--email`, etc.) |
 | | `update` | Update contact (`--title`, `--label-ids`) |
-| | `find-by-linkedin` | Find contact by LinkedIn URL (`--create`, `--stage-id`) |
+| | `upsert-by-linkedin` | Get or create a contact by LinkedIn URL (`--name`, `--title`, `--stage-id`) |
 | | `stages` | List all contact stages |
 | **accounts** | `search` | Search companies/accounts (`--query`, `--domain`) |
 | | `get` | Get account details by ID |
@@ -75,8 +75,8 @@ $ qodev-apollo-cli usage
 | **enrich** | `org` | Enrich organization by domain (FREE - no credits) |
 | | `person` | Enrich person by email (1 credit per lookup) |
 | **people** | `search` | Search people database (`--person-titles`, `--q-organization-domains`) |
-| **notes** | `search` | Search notes (`--contact-id`) |
-| | `create` | Create a note (`--contact-ids`, `--note`) |
+| **notes** | `search` | Search notes (`--contact-id`, `--account-id`, `--opportunity-id`) |
+| | `create` | Create a note (`--contact-ids`, `--account-ids`, `--opportunity-ids`, `--content`) |
 | **tasks** | `search` | Search tasks (`--type`, `--status`) |
 | | `create` | Create a task (`--contact-ids`, `--note`, `--due-at`) |
 | **calls** | `search` | Search call activities |
@@ -167,15 +167,15 @@ qodev-apollo-cli deals search --stage-id <stage-id>
 ### LinkedIn integration
 
 ```bash
-# Find contact by LinkedIn URL
-qodev-apollo-cli contacts find-by-linkedin "https://linkedin.com/in/janesmith"
+# Read-only lookup by LinkedIn URL (returns 0..n contacts, never writes)
+qodev-apollo-cli contacts search --linkedin-url "https://linkedin.com/in/janesmith"
 
-# Auto-create if not found
-qodev-apollo-cli contacts find-by-linkedin "https://linkedin.com/in/janesmith" --create
+# Get or create a contact by LinkedIn URL (upsert); --name is required to create
+qodev-apollo-cli contacts upsert-by-linkedin "https://linkedin.com/in/janesmith" --name "Jane Smith"
 
-# Assign to stage on creation
-qodev-apollo-cli contacts find-by-linkedin "https://linkedin.com/in/janesmith" \
-  --create --stage-id <stage-id>
+# Set title / stage when creating
+qodev-apollo-cli contacts upsert-by-linkedin "https://linkedin.com/in/janesmith" \
+  --name "Jane Smith" --title "VP Engineering" --stage-id <stage-id>
 ```
 
 ### Company enrichment (FREE)

{qodev_apollo_cli-0.1.0 → qodev_apollo_cli-1.0.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "qodev-apollo-cli"
-version = "0.1.0"
+version = "1.0.0"
 description = "Agent-friendly CLI for the Apollo API"
 readme = "README.md"
 requires-python = ">=3.11"

{qodev_apollo_cli-0.1.0 → qodev_apollo_cli-1.0.0}/src/apollo_cli/app.py

@@ -102,6 +102,8 @@ def launcher(
         _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 ValueError as exc:
+        _handle_error(str(exc), code="validation", exit_code=EXIT_VALIDATION)
     except SystemExit:
         raise
     except KeyboardInterrupt:

{qodev_apollo_cli-0.1.0 → qodev_apollo_cli-1.0.0}/src/apollo_cli/commands/contacts.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from typing import Annotated
+from typing import Annotated, Any
 
 from cyclopts import App, Parameter
 
@@ -12,7 +12,9 @@ from apollo_cli.formatters.contacts import (
     format_contact_list,
     format_stages_list,
 )
-from apollo_cli.output import output, output_list
+from apollo_cli.linkedin import apollo_canonical_linkedin_url
+from apollo_cli.output import error, output, output_list
+from apollo_cli.util import parse_comma_list
 
 contacts_app = App(name="contacts", help="Manage contacts.")
 
@@ -31,7 +33,9 @@ async def search(
     if stage_id:
         filters["contact_stage_ids"] = [stage_id]
     if linkedin_url:
-        filters["linkedin_url"] = linkedin_url
+        # Apollo exact-matches its stored http://www.linkedin.com/in/<slug> form, so
+        # canonicalize or the filter silently returns nothing.
+        filters["linkedin_url"] = apollo_canonical_linkedin_url(linkedin_url)
 
     async with ctx.client() as client:
         result = await client.search_contacts(page=ctx.page, limit=ctx.limit, **filters)
@@ -97,7 +101,7 @@ async def update(
     if title:
         fields["title"] = title
     if label_ids:
-        fields["label_ids"] = [lid.strip() for lid in label_ids.split(",")]
+        fields["label_ids"] = parse_comma_list(label_ids)
 
     async with ctx.client() as client:
         result = await client.update_contact(id, **fields)
@@ -105,29 +109,74 @@ async def update(
     output(result, ctx=ctx, format_fn=format_contact_detail)
 
 
-@contacts_app.command(name="find-by-linkedin")
-async def find_by_linkedin(
+def _format_upsert_result(data: dict[str, Any]) -> str:
+    status = "Created new contact" if data["created"] else "Found existing contact"
+    return f"**{status}**\n\n{format_contact_detail(data['contact'])}"
+
+
+@contacts_app.command(name="upsert-by-linkedin")
+async def upsert_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,
+    name: Annotated[
+        str | None,
+        Parameter(name="--name", help="Full name 'First Last' — required to create the contact if it doesn't exist"),
+    ] = None,
+    title: Annotated[str | None, Parameter(name="--title", help="Job title (used only when creating)")] = None,
+    company: Annotated[str | None, Parameter(name="--company", help="Company name (used only when creating)")] = None,
+    stage_id: Annotated[str | None, Parameter(name="--stage-id", help="Stage ID (used only when creating)")] = 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
+    """Get or create a contact by LinkedIn URL (upsert).
 
-        error("Contact not found.", ctx=ctx, code="not_found", exit_code=1)
+    Resolves the URL to an existing contact and returns it, or — if none exists —
+    creates one (requires ``--name``) and returns it. The result carries a ``created``
+    flag. For a read-only lookup that never writes, use ``contacts search --linkedin-url``.
+    """
+    canonical = apollo_canonical_linkedin_url(url)
+    async with ctx.client() as client:
+        # 1. Exact-match lookup on Apollo's canonical URL.
+        result = await client.search_contacts(linkedin_url=canonical, limit=1)
+        existing = result.items[0] if result.items else None
+
+        # 2. Name fallback — catch a contact stored under a drifted/numeric URL so we
+        #    don't create a duplicate; accept only an exact canonical-URL identity match.
+        #    First match wins: upsert just needs to know one exists (unlike the old client,
+        #    we intentionally don't treat >1 match as ambiguous).
+        if existing is None and name:
+            by_name = await client.search_contacts(q_keywords=name, limit=10)
+            existing = next(
+                (
+                    c
+                    for c in by_name.items
+                    if c.linkedin_url and apollo_canonical_linkedin_url(c.linkedin_url) == canonical
+                ),
+                None,
+            )
+
+        if existing is not None:
+            output({"created": False, "contact": existing}, ctx=ctx, format_fn=_format_upsert_result)
+            return
+
+        # 3. Create — Apollo needs both a first and a last name.
+        first, _, last = name.strip().partition(" ") if name else ("", "", "")
+        if not (first and last):
+            error(
+                'No contact for that LinkedIn URL. Pass --name "First Last" to create one.',
+                ctx=ctx,
+                code="name_required",
+                exit_code=2,
+            )
+            return
+        fields: dict = {"linkedin_url": canonical}
+        if title:
+            fields["title"] = title
+        if company:
+            fields["company_name"] = company
+        if stage_id:
+            fields["contact_stage_id"] = stage_id
+        created = await client.create_contact(first, last, **fields)
+
+    output({"created": True, "contact": created}, ctx=ctx, format_fn=_format_upsert_result)
 
 
 @contacts_app.command

{qodev_apollo_cli-0.1.0 → qodev_apollo_cli-1.0.0}/src/apollo_cli/commands/notes.py

@@ -9,6 +9,7 @@ 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, output_list
+from apollo_cli.util import parse_comma_list
 
 notes_app = App(name="notes", help="Notes management.")
 
@@ -17,6 +18,7 @@ NOTE_LIST_COLUMNS = [
     ("Content", "content"),
     ("Contact ID", "contact_id"),
     ("Account ID", "account_id"),
+    ("Opportunity ID", "opportunity_id"),
     ("Created", "created_at"),
 ]
 
@@ -26,13 +28,18 @@ async def search(
     *,
     contact_id: Annotated[str | None, Parameter(name="--contact-id", help="Filter by contact ID")] = None,
     account_id: Annotated[str | None, Parameter(name="--account-id", help="Filter by account ID")] = None,
+    opportunity_id: Annotated[
+        str | None, Parameter(name="--opportunity-id", help="Filter by opportunity/deal ID")
+    ] = None,
 ) -> None:
-    """Search notes by contact or account."""
+    """Search notes by contact, account, or opportunity."""
     filters: dict = {}
     if contact_id:
         filters["contact_ids"] = [contact_id]
     if account_id:
         filters["account_ids"] = [account_id]
+    if opportunity_id:
+        filters["opportunity_ids"] = [opportunity_id]
 
     async with ctx.client() as client:
         result = await client.search_notes(page=ctx.page, limit=ctx.limit, **filters)
@@ -54,13 +61,18 @@ async def create(
     content: Annotated[str, Parameter(name="--content", help="Note content")],
     contact_ids: Annotated[str | None, Parameter(name="--contact-ids", help="Comma-separated contact IDs")] = None,
     account_ids: Annotated[str | None, Parameter(name="--account-ids", help="Comma-separated account IDs")] = None,
+    opportunity_ids: Annotated[
+        str | None, Parameter(name="--opportunity-ids", help="Comma-separated opportunity/deal IDs")
+    ] = None,
 ) -> None:
     """Create a new note."""
     kwargs: dict = {}
     if contact_ids:
-        kwargs["contact_ids"] = [cid.strip() for cid in contact_ids.split(",")]
+        kwargs["contact_ids"] = parse_comma_list(contact_ids)
     if account_ids:
-        kwargs["account_ids"] = [aid.strip() for aid in account_ids.split(",")]
+        kwargs["account_ids"] = parse_comma_list(account_ids)
+    if opportunity_ids:
+        kwargs["opportunity_ids"] = parse_comma_list(opportunity_ids)
 
     async with ctx.client() as client:
         result = await client.create_note(content, **kwargs)

{qodev_apollo_cli-0.1.0 → qodev_apollo_cli-1.0.0}/src/apollo_cli/commands/people.py

@@ -8,6 +8,7 @@ from cyclopts import App, Parameter
 
 from apollo_cli.context import ctx
 from apollo_cli.output import output
+from apollo_cli.util import parse_comma_list
 
 people_app = App(name="people", help="People database search.")
 
@@ -24,9 +25,9 @@ async def search(
     if keywords:
         filters["q_keywords"] = keywords
     if titles:
-        filters["person_titles"] = [t.strip() for t in titles.split(",")]
+        filters["person_titles"] = parse_comma_list(titles)
     if locations:
-        filters["person_locations"] = [loc.strip() for loc in locations.split(",")]
+        filters["person_locations"] = parse_comma_list(locations)
 
     async with ctx.client() as client:
         result = await client.search_people(**filters)

{qodev_apollo_cli-0.1.0 → qodev_apollo_cli-1.0.0}/src/apollo_cli/commands/tasks.py

@@ -9,6 +9,7 @@ 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, output_list
+from apollo_cli.util import parse_comma_list
 
 tasks_app = App(name="tasks", help="Task management.")
 
@@ -58,7 +59,7 @@ async def create(
     priority: Annotated[str, Parameter(name="--priority", help="Priority (high, medium, low)")] = "medium",
 ) -> None:
     """Create a new task."""
-    ids = [cid.strip() for cid in contact_ids.split(",")]
+    ids = parse_comma_list(contact_ids)
 
     async with ctx.client() as client:
         result = await client.create_task(contact_ids=ids, note=note, type=type, priority=priority)

qodev_apollo_cli-1.0.0/src/apollo_cli/linkedin.py

@@ -0,0 +1,34 @@
+"""LinkedIn URL canonicalization for Apollo lookups.
+
+Apollo stores and *exact-matches* LinkedIn profile URLs in the canonical form
+``http://www.linkedin.com/in/<slug>`` — http scheme, ``www`` host, no trailing slash,
+lowercased slug (Apollo lowercases the whole URL on its side). Apollo's ``linkedin_url``
+search filter is a literal string match, so any other shape a user pastes (``https://``,
+missing ``www``, a trailing slash, a mixed-case slug or ``%HEX``, tracking query params)
+silently returns zero results. Canonicalizing
+before searching is what makes ``contacts search --linkedin-url`` and ``upsert-by-linkedin``
+match reliably.
+"""
+
+from __future__ import annotations
+
+import re
+
+# Modern LinkedIn profile URLs are /in/<slug>. Legacy /pub/ URLs carry a multi-segment
+# id we must not truncate, so we leave anything that isn't /in/ untouched.
+_PROFILE_RE = re.compile(r"linkedin\.com/in/([^/?#]+)", re.IGNORECASE)
+
+
+def apollo_canonical_linkedin_url(url: str) -> str:
+    """Return *url* in the exact form Apollo stores and matches on.
+
+    Returns *url* unchanged if it is not a recognizable ``/in/`` LinkedIn profile URL,
+    so passing a company page, a legacy ``/pub/`` URL, or an empty string is a no-op.
+    """
+    if not url:
+        return url
+    match = _PROFILE_RE.search(url.strip())
+    if not match:
+        return url
+    slug = match.group(1).rstrip("/").lower()
+    return f"http://www.linkedin.com/in/{slug}"

{qodev_apollo_cli-0.1.0 → qodev_apollo_cli-1.0.0}/src/apollo_cli/skills/SKILL.md

@@ -33,7 +33,7 @@ Get your API key from [Apollo.io Settings → API](https://app.apollo.io/#/setti
 | `contacts get ID` | Get contact details |
 | `contacts create --first-name F --last-name L [--email E] [--title T] [--company C] [--linkedin-url URL]` | Create contact |
 | `contacts update ID [--title T] [--label-ids IDS]` | Update contact |
-| `contacts find-by-linkedin URL [--create] [--name N] [--stage-id ID]` | Find contact by LinkedIn URL |
+| `contacts upsert-by-linkedin URL [--name N] [--title T] [--stage-id ID]` | Get or create a contact by LinkedIn URL |
 | `contacts stages` | List all contact stages |
 
 ### accounts
@@ -82,8 +82,8 @@ Get your API key from [Apollo.io Settings → API](https://app.apollo.io/#/setti
 
 | Command | Description |
 |---------|-------------|
-| `notes search [--contact-id ID]` | Search notes |
-| `notes create --contact-ids IDS --note TEXT` | Create a note |
+| `notes search [--contact-id ID] [--account-id ID] [--opportunity-id ID]` | Search notes |
+| `notes create --content TEXT [--contact-ids IDS] [--account-ids IDS] [--opportunity-ids IDS]` | Create a note (attach to any combination of contacts/accounts/opportunities) |
 
 ### tasks
 
@@ -182,15 +182,15 @@ qodev-apollo-cli deals search --stage-id <stage-id>
 ### LinkedIn integration
 
 ```bash
-# Find contact by LinkedIn URL
-qodev-apollo-cli contacts find-by-linkedin "https://linkedin.com/in/janesmith"
+# Read-only lookup by LinkedIn URL (returns 0..n contacts, never writes)
+qodev-apollo-cli contacts search --linkedin-url "https://linkedin.com/in/janesmith"
 
-# Auto-create if not found
-qodev-apollo-cli contacts find-by-linkedin "https://linkedin.com/in/janesmith" --create
+# Get or create a contact by LinkedIn URL (upsert); --name is required to create
+qodev-apollo-cli contacts upsert-by-linkedin "https://linkedin.com/in/janesmith" --name "Jane Smith"
 
-# Assign to stage on creation
-qodev-apollo-cli contacts find-by-linkedin "https://linkedin.com/in/janesmith" \
-  --create --stage-id <stage-id>
+# Set title / stage when creating
+qodev-apollo-cli contacts upsert-by-linkedin "https://linkedin.com/in/janesmith" \
+  --name "Jane Smith" --title "VP Engineering" --stage-id <stage-id>
 ```
 
 ## References

{qodev_apollo_cli-0.1.0 → qodev_apollo_cli-1.0.0}/src/apollo_cli/skills/references/contact-workflows.md

@@ -20,22 +20,25 @@ qodev-apollo-cli contacts search --query "engineer" --page 2 --limit 50
 
 ## LinkedIn Integration
 
-Find or create contacts from LinkedIn profiles:
+Two commands cover LinkedIn URLs — a read-only lookup and an upsert:
 
 ```bash
-# Find existing contact by LinkedIn URL
-qodev-apollo-cli contacts find-by-linkedin "https://linkedin.com/in/janesmith"
+# Read-only lookup — returns 0..n matching contacts, never writes
+qodev-apollo-cli contacts search --linkedin-url "https://linkedin.com/in/janesmith"
 
-# Auto-create if not found
-qodev-apollo-cli contacts find-by-linkedin "https://linkedin.com/in/janesmith" --create
+# Upsert — resolve to an existing contact, or create one (--name required to create).
+# The result carries a "created" flag.
+qodev-apollo-cli contacts upsert-by-linkedin "https://linkedin.com/in/janesmith" --name "Jane Smith"
 
-# Specify name for fallback search
-qodev-apollo-cli contacts find-by-linkedin "https://linkedin.com/in/janesmith" --name "Jane Smith"
-
-# Assign to stage on creation
-qodev-apollo-cli contacts find-by-linkedin "https://linkedin.com/in/janesmith" --create --stage-id <stage-id>
+# Set title / company / stage when creating
+qodev-apollo-cli contacts upsert-by-linkedin "https://linkedin.com/in/janesmith" \
+  --name "Jane Smith" --title "VP Engineering" --stage-id <stage-id>
 ```
 
+URLs are canonicalized to Apollo's exact-match form automatically, so any common shape
+(`https://`, trailing slash, `www`/no-`www`) resolves the same contact. Before creating,
+the upsert also name-searches to avoid duplicating a contact stored under a different URL.
+
 ## Contact Creation
 
 Create new contacts manually:

qodev_apollo_cli-1.0.0/src/apollo_cli/util.py

@@ -0,0 +1,22 @@
+"""Shared utility helpers for CLI commands."""
+
+from __future__ import annotations
+
+
+def parse_comma_list(raw: str) -> list[str]:
+    """Parse a comma-separated CLI argument into a list of stripped, non-empty tokens.
+
+    - `"a,b,c"` → `["a", "b", "c"]`
+    - `"a, ,b"`, `"a,,b"`, `",a,b,"` → `["a", "b"]` (drops empty/whitespace-only tokens,
+      forgiving of typos)
+    - `""` or `"   "` → `[]` (no meaningful input, treat as "flag not provided")
+    - `",,,"` → raises `ValueError` (user typed *something* but it collapsed to
+      nothing — that's broken input, not "empty", so fail loud rather than silently
+      omit the flag)
+
+    Not a real CSV parser — no quoting or escaping, just comma-split-and-strip.
+    """
+    tokens = [t.strip() for t in raw.split(",") if t.strip()]
+    if not tokens and raw.strip():
+        raise ValueError(f"expected comma-separated values, got only separators: {raw!r}")
+    return tokens