qodev-apollo-cli 1.2.1__tar.gz → 1.4.0__tar.gz

{qodev_apollo_cli-1.2.1 → qodev_apollo_cli-1.4.0}/.gitignore

@@ -7,3 +7,8 @@ dist/
 .coverage
 .pytest_cache/
 .ruff_cache/
+.mypy_cache/
+
+# Local secrets — never commit
+.env
+.env.*

{qodev_apollo_cli-1.2.1 → qodev_apollo_cli-1.4.0}/CHANGELOG.md

@@ -6,6 +6,32 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [1.4.0] - 2026-07-10
+
+### Fixed
+
+- `deals search --query` now searches the **deal name** (`q_opportunity_name`). Apollo silently ignores `q_keywords` on `/opportunities/search`, so name search never actually filtered before.
+- `jobs list` renders the organization job-postings shape (`Title/City/State/URL/Posted`) returned by the fixed API.
+
+### Changed
+
+- Require `qodev-apollo-api>=0.5.0` (people `api_search`, deal name param, repaired `list_*` endpoints, search-filter validation).
+- **Skill** (`SKILL.md` + references): added a "Search filter formats" section (seniority enums, location formats, `"min,max"` employee ranges, dict ranges, deal name search, canonical `linkedin_url`); documented `deals create` and `people --keywords`.
+
+### Removed
+
+- **Breaking:** `news list` and `calls list` commands — the underlying Apollo routes were removed (`list_account_news` / `list_contact_calls` are gone from the API). `calls search` remains.
+
+## [1.3.0] - 2026-07-09
+
+### Added
+
+- `deals create` command — create a deal/opportunity from the CLI: `deals create --name "…" [--owner-id] [--account-id] [--amount] [--stage-id | --stage-name] [--closed-date]`. `--name` is the only required flag; `--stage-name` resolves to an ID via the stage list (same helper as `deals search`), and passing both `--stage-id` and `--stage-name` is a validation error. Requires a master Apollo API key (non-master keys get a 403).
+
+### Changed
+
+- Require `qodev-apollo-api>=0.4.0` (adds `create_deal`, and ships the fixed `update_opportunity_roles` payload so `deals set-role` now works, plus `search_accounts` filter validation).
+
 ## [1.2.1] - 2026-07-08
 
 Follow-ups from code review of the v1.2.0 changes.

{qodev_apollo_cli-1.2.1 → qodev_apollo_cli-1.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: qodev-apollo-cli
-Version: 1.2.1
+Version: 1.4.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
@@ -19,7 +19,7 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Typing :: Typed
 Requires-Python: >=3.11
 Requires-Dist: cyclopts>=3.0
-Requires-Dist: qodev-apollo-api>=0.3.1
+Requires-Dist: qodev-apollo-api>=0.5.0
 Requires-Dist: rich>=13.0
 Provides-Extra: dev
 Requires-Dist: mypy>=1.13.0; extra == 'dev'

{qodev_apollo_cli-1.2.1 → qodev_apollo_cli-1.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "qodev-apollo-cli"
-version = "1.2.1"
+version = "1.4.0"
 description = "Agent-friendly CLI for the Apollo API"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -20,7 +20,7 @@ classifiers = [
 dependencies = [
     "cyclopts>=3.0",
     "rich>=13.0",
-    "qodev-apollo-api>=0.3.1",
+    "qodev-apollo-api>=0.5.0",
 ]
 
 [project.optional-dependencies]

{qodev_apollo_cli-1.2.1 → qodev_apollo_cli-1.4.0}/src/apollo_cli/app.py

@@ -33,7 +33,6 @@ 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
@@ -55,7 +54,6 @@ _sub_apps = [
     conversations_app,
     custom_fields_app,
     emails_app,
-    news_app,
     jobs_app,
     usage_app,
     install_app,

{qodev_apollo_cli-1.2.1 → qodev_apollo_cli-1.4.0}/src/apollo_cli/commands/calls.py

@@ -2,13 +2,11 @@
 
 from __future__ import annotations
 
-from typing import Annotated
-
-from cyclopts import App, Parameter
+from cyclopts import App
 
 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
+from apollo_cli.output import output_list
 
 calls_app = App(name="calls", help="Call activity.")
 
@@ -37,18 +35,3 @@ async def search() -> None:
         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)

{qodev_apollo_cli-1.2.1 → qodev_apollo_cli-1.4.0}/src/apollo_cli/commands/deals.py

@@ -19,7 +19,7 @@ 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")] = "",
+    query: Annotated[str, Parameter(name=["--query", "-q"], help="Search by deal name")] = "",
     stage_id: Annotated[str | None, Parameter(name="--stage-id", help="Filter by deal stage ID")] = None,
     stage_name: Annotated[
         str | None,
@@ -28,10 +28,12 @@ async def search(
         ),
     ] = None,
 ) -> None:
-    """Search deals by keyword or filter."""
+    """Search deals by name or filter."""
     filters: dict = {}
     if query:
-        filters["q_keywords"] = query
+        # Deal name search is q_opportunity_name — Apollo silently ignores
+        # q_keywords on /opportunities/search (it returns every deal).
+        filters["q_opportunity_name"] = query
     stage_ids: list[str] = []
     if stage_id:
         stage_ids.append(stage_id)
@@ -66,6 +68,50 @@ async def get(
     output(deal, ctx=ctx, format_fn=format_deal_detail)
 
 
+@deals_app.command
+async def create(
+    *,
+    name: Annotated[str, Parameter(name="--name", help="Deal name (required)")],
+    owner_id: Annotated[str | None, Parameter(name="--owner-id", help="Deal owner (team member) ID")] = None,
+    account_id: Annotated[str | None, Parameter(name="--account-id", help="Target account/company ID")] = None,
+    amount: Annotated[float | None, Parameter(name="--amount", help="Deal value (no currency symbol)")] = None,
+    stage_id: Annotated[str | None, Parameter(name="--stage-id", help="Deal stage ID")] = None,
+    stage_name: Annotated[
+        str | None,
+        Parameter(name="--stage-name", help="Deal stage name (resolved to an ID; avoids a `pipelines stages` lookup)"),
+    ] = None,
+    closed_date: Annotated[str | None, Parameter(name="--closed-date", help="Expected close date (YYYY-MM-DD)")] = None,
+) -> None:
+    """Create a new deal/opportunity.
+
+    Requires a master Apollo API key (non-master keys get a 403). ``--name`` is the
+    only required field. Use ``--stage-name`` to set the stage by name instead of ID.
+    """
+    if stage_id and stage_name:
+        error("Pass either --stage-id or --stage-name, not both.", ctx=ctx, code="conflicting_args", exit_code=2)
+        return
+
+    fields: dict[str, Any] = {}
+    if owner_id:
+        fields["owner_id"] = owner_id
+    if account_id:
+        fields["account_id"] = account_id
+    if amount is not None:
+        fields["amount"] = amount
+    if closed_date:
+        fields["closed_date"] = closed_date
+
+    async with ctx.client() as client:
+        if stage_name:
+            all_stages = await client.list_all_stages()
+            stage_id = resolve_stage_id(stage_name, all_stages.items, kind="deal stage")
+        if stage_id:
+            fields["opportunity_stage_id"] = stage_id
+        deal = await client.create_deal(name, **fields)
+
+    output(deal, ctx=ctx, format_fn=format_deal_detail)
+
+
 ROLE_TYPE_COLUMNS = [("ID", "id"), ("Name", "name"), ("Display Order", "display_order")]
 
 

{qodev_apollo_cli-1.2.1 → qodev_apollo_cli-1.4.0}/src/apollo_cli/commands/jobs.py

@@ -14,8 +14,8 @@ jobs_app = App(name="jobs", help="Job postings.")
 
 JOBS_LIST_COLUMNS = [
     ("Title", "title"),
-    ("Location", "location"),
-    ("Department", "department"),
+    ("City", "city"),
+    ("State", "state"),
     ("URL", "url"),
     ("Posted", "posted_at"),
 ]

{qodev_apollo_cli-1.2.1 → qodev_apollo_cli-1.4.0}/src/apollo_cli/skills/SKILL.md

@@ -47,8 +47,9 @@ Get your API key from [Apollo.io Settings → API](https://app.apollo.io/#/setti
 
 | Command | Description |
 |---------|-------------|
-| `deals search [--query Q] [--stage-id ID] [--stage-name NAME]` | Search opportunities/deals |
+| `deals search [--query Q] [--stage-id ID] [--stage-name NAME]` | Search deals. `--query` matches the **deal name** (`q_opportunity_name`) |
 | `deals get ID` | Get deal details |
+| `deals create --name N [--owner-id ID] [--account-id ID] [--amount N] [--stage-id ID \| --stage-name NAME] [--closed-date YYYY-MM-DD]` | Create a deal (needs a master API key) |
 | `deals role-types` | List opportunity contact role types |
 | `deals set-role ID --contact-id C [--role-type NAME_OR_ID] [--primary]` | Set/update a contact's role on a deal |
 
@@ -78,7 +79,7 @@ Get your API key from [Apollo.io Settings → API](https://app.apollo.io/#/setti
 
 | Command | Description |
 |---------|-------------|
-| `people search [--titles T] [--seniorities S] [--locations L] [--organization-domains D]` | Search people database (respects `--limit`/`--page`) |
+| `people search [--keywords K] [--titles T] [--seniorities S] [--locations L] [--organization-domains D]` | Search people database (respects `--limit`/`--page`). Returns teaser data only — no email/linkedin without enrichment. See **Search filter formats** below |
 
 ### notes
 
@@ -122,17 +123,11 @@ Recorded meetings (Zoom/Teams/Meet) with transcript and AI summary — distinct
 |---------|-------------|
 | `emails search` | Search email activities |
 
-### news
-
-| Command | Description |
-|---------|-------------|
-| `news search [--categories CATS]` | Search news |
-
 ### jobs
 
 | Command | Description |
 |---------|-------------|
-| `jobs search [--job-titles TITLES] [--company-domains DOMAINS]` | Search job postings |
+| `jobs list ACCOUNT_ID` | List job postings for an account's linked organization |
 
 ### usage
 
@@ -140,6 +135,32 @@ Recorded meetings (Zoom/Teams/Meet) with transcript and AI summary — distinct
 |---------|-------------|
 | `usage` | Show API usage stats and rate limits |
 
+## Search filter formats
+
+Apollo **silently ignores** a filter whose value is in the wrong format (it returns an
+unfiltered/whole page that looks like a real match) — so getting the format right matters.
+These are empirically verified (each measurably narrows the result count):
+
+**`people search`**
+| Filter | Format | Notes |
+|--------|--------|-------|
+| `--keywords` | free text | names / titles / keywords |
+| `--titles` | comma list of titles | e.g. `--titles "CEO,VP Sales"` |
+| `--seniorities` | **lowercase enums** | `owner, founder, c_suite, partner, vp, head, director, manager, senior, entry, intern`. `"VP"` / `"vice president"` match **nothing** |
+| `--locations` | country name, **2-letter code** (`US`), or `"City, State, Country"` | `US` ≡ `United States` |
+| `--organization-domains` | comma list of domains | e.g. `acme.com,globex.com` |
+
+Raw API (via `qodev_apollo_api`) also accepts, on people search:
+`organization_num_employees_ranges` as **`"min,max"` comma** strings (`["1,10"]`, `["1000,5000"]` — a dash `"1-10"` is silently ignored); `revenue_range`/`organization_num_jobs_range` as `{"min":N,"max":N}`; `contact_email_status` as `verified|unverified|likely to engage|unavailable`; `currently_using_any_of_technology_uids` as a list of tech UIDs.
+
+**`deals search`** — `--query` searches the **deal name** (`q_opportunity_name`). *(Plain keyword search is not supported by Apollo for deals.)*
+
+**`contacts search`** — `--linkedin-url` must be a real LinkedIn profile URL; the CLI canonicalizes it to Apollo's stored form (`http://www.linkedin.com/in/<slug>`). `--query` is free-text keywords.
+
+**`accounts search`** — `--query` is a company-name keyword (`q_organization_name`).
+
+**Stage filters** (`--stage-id`/`--stage-name` on contacts/deals) take a stage the account actually has — list them with `contacts stages` / `pipelines stages`.
+
 ## Exit Codes
 
 | Code | Meaning |

{qodev_apollo_cli-1.2.1 → qodev_apollo_cli-1.4.0}/src/apollo_cli/skills/references/deal-workflows.md

@@ -36,7 +36,7 @@ qodev-apollo-cli --json pipelines stages <pipeline-id> | jq '.items[] | {name, i
 # Search all deals
 qodev-apollo-cli deals search
 
-# Search by keyword
+# Search by deal name (--query matches the deal name, not free keywords)
 qodev-apollo-cli deals search --query "enterprise"
 
 # Filter by stage

{qodev_apollo_cli-1.2.1 → qodev_apollo_cli-1.4.0}/tests/test_commands.py

@@ -502,6 +502,60 @@ class TestDealRoleCommands:
         assert all("opportunity_contact_role_type_id" not in r for r in roles)
 
 
+class TestDealCreate:
+    @pytest.mark.asyncio
+    async def test_create_passes_name_and_optional_fields(self, sample_deal: dict, capsys) -> None:
+        """deals create forwards --name plus only the optional fields that were provided."""
+        mock_client = MagicMock()
+        mock_client.create_deal = AsyncMock(return_value=sample_deal)
+
+        _ctx.ctx.configure(json_mode=True, api_key="test-key", limit=25, page=1)
+
+        with patch.object(_ctx.ctx, "client", return_value=MockAsyncContextManager(mock_client)):
+            from apollo_cli.commands.deals import create
+
+            await create(name="Big One", owner_id="o1", amount=5000, stage_id="st1")
+
+        name_arg = mock_client.create_deal.call_args.args[0]
+        fields = mock_client.create_deal.call_args.kwargs
+        assert name_arg == "Big One"
+        assert fields == {"owner_id": "o1", "amount": 5000, "opportunity_stage_id": "st1"}
+
+    @pytest.mark.asyncio
+    async def test_create_resolves_stage_name(self, sample_deal: dict, capsys) -> None:
+        """deals create --stage-name resolves to opportunity_stage_id."""
+        mock_client = MagicMock()
+        mock_client.list_all_stages = AsyncMock(
+            return_value=MockSearchResult(items=[{"id": "st-neg", "name": "Negotiation"}], total=1, page=1)
+        )
+        mock_client.create_deal = AsyncMock(return_value=sample_deal)
+
+        _ctx.ctx.configure(json_mode=True, api_key="test-key", limit=25, page=1)
+
+        with patch.object(_ctx.ctx, "client", return_value=MockAsyncContextManager(mock_client)):
+            from apollo_cli.commands.deals import create
+
+            await create(name="Deal", stage_name="negotiation")
+
+        assert mock_client.create_deal.call_args.kwargs["opportunity_stage_id"] == "st-neg"
+
+    @pytest.mark.asyncio
+    async def test_create_rejects_both_stage_id_and_name(self, capsys) -> None:
+        """Passing both --stage-id and --stage-name is a validation error; no API call is made."""
+        mock_client = MagicMock()
+        mock_client.create_deal = AsyncMock()
+
+        _ctx.ctx.configure(json_mode=True, api_key="test-key", limit=25, page=1)
+
+        with patch.object(_ctx.ctx, "client", return_value=MockAsyncContextManager(mock_client)):
+            from apollo_cli.commands.deals import create
+
+            with pytest.raises(SystemExit):
+                await create(name="Deal", stage_id="st1", stage_name="Negotiation")
+
+        mock_client.create_deal.assert_not_called()
+
+
 class TestCustomFieldsCommand:
     @pytest.mark.asyncio
     async def test_custom_fields_list_filters_by_modality(self, capsys) -> None:

{qodev_apollo_cli-1.2.1 → qodev_apollo_cli-1.4.0}/uv.lock

@@ -472,7 +472,7 @@ wheels = [
 
 [[package]]
 name = "qodev-apollo-api"
-version = "0.3.2"
+version = "0.5.0"
 source = { directory = "../apollo-api" }
 dependencies = [
     { name = "httpx" },
@@ -494,7 +494,7 @@ provides-extras = ["dev"]
 
 [[package]]
 name = "qodev-apollo-cli"
-version = "1.2.1"
+version = "1.4.0"
 source = { editable = "." }
 dependencies = [
     { name = "cyclopts" },

qodev_apollo_cli-1.2.1/src/apollo_cli/commands/news.py

@@ -1,35 +0,0 @@
-"""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)