Skip to content

fix: deals --query searches deal name; document filter formats in skill #14

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jschfflr merged 1 commit into from
Jul 10, 2026
Merged

fix: deals --query searches deal name; document filter formats in skill #14

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 5 additions & 3 deletions src/apollo_cli/commands/deals.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@
@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,
Expand All @@ -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

@peqy peqy Bot Jul 10, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

q_opportunity_name support appears to depend on apollo-api#21 (deal allowlist). To avoid this silently regressing for users who install an older qodev-apollo-api (e.g. 0.4.0), it may be worth bumping the minimum required version (and updating uv.lock) once the apollo-api release containing #21 is cut.

stage_ids: list[str] = []
if stage_id:
stage_ids.append(stage_id)
Expand Down
39 changes: 30 additions & 9 deletions src/apollo_cli/skills/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 |

Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -122,24 +123,44 @@ 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

| Command | Description |
|---------|-------------|
| `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 |
Expand Down
2 changes: 1 addition & 1 deletion src/apollo_cli/skills/references/deal-workflows.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Loading