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

apollo_cli/skills/references/contact-workflows.md

@@ -0,0 +1,110 @@
+# Contact Management Workflows
+
+## Search and Filter
+
+Search contacts with various filters:
+
+```bash
+# Keyword search
+qodev-apollo-cli contacts search --query "engineer"
+
+# Filter by stage
+qodev-apollo-cli contacts search --stage-id <stage-id>
+
+# Filter by LinkedIn URL
+qodev-apollo-cli contacts search --linkedin-url "https://linkedin.com/in/..."
+
+# Pagination
+qodev-apollo-cli contacts search --query "engineer" --page 2 --limit 50
+```
+
+## LinkedIn Integration
+
+Find or create contacts from LinkedIn profiles:
+
+```bash
+# Find existing contact by LinkedIn URL
+qodev-apollo-cli contacts find-by-linkedin "https://linkedin.com/in/janesmith"
+
+# Auto-create if not found
+qodev-apollo-cli contacts find-by-linkedin "https://linkedin.com/in/janesmith" --create
+
+# 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>
+```
+
+## Contact Creation
+
+Create new contacts manually:
+
+```bash
+qodev-apollo-cli contacts create \
+  --first-name Jane \
+  --last-name Smith \
+  --email jane@example.com \
+  --title "VP Engineering" \
+  --company "Acme Corp" \
+  --linkedin-url "https://linkedin.com/in/janesmith"
+```
+
+## Update Contact Fields
+
+```bash
+# Update title
+qodev-apollo-cli contacts update <contact-id> --title "CTO"
+
+# Update labels
+qodev-apollo-cli contacts update <contact-id> --label-ids "label1,label2,label3"
+```
+
+## View Contact Stages
+
+List all available contact stages:
+
+```bash
+qodev-apollo-cli contacts stages
+```
+
+## JSON Output for Scripting
+
+Extract specific fields using jq:
+
+```bash
+# Get contact emails
+qodev-apollo-cli --json contacts search --query "engineer" | jq '.items[].email'
+
+# Count total results
+qodev-apollo-cli --json contacts search --query "engineer" | jq '.total'
+
+# Extract contact IDs
+qodev-apollo-cli --json contacts search --query "engineer" | jq '.items[].id'
+```
+
+## Bulk Operations
+
+Process multiple contacts using JSON output:
+
+```bash
+# Search and process each contact
+qodev-apollo-cli --json contacts search --query "VP" | \
+  jq -r '.items[].id' | \
+  while read id; do
+    qodev-apollo-cli contacts get "$id"
+  done
+```
+
+## Filtering by Stage
+
+```bash
+# List all stages to find IDs
+qodev-apollo-cli contacts stages
+
+# Search contacts in specific stage
+qodev-apollo-cli contacts search --stage-id <stage-id>
+
+# JSON output for stage filtering
+qodev-apollo-cli --json contacts stages | jq '.items[] | select(.name=="Qualified Lead") | .id'
+```

apollo_cli/skills/references/deal-workflows.md

@@ -0,0 +1,142 @@
+# Deal Pipeline Workflows
+
+## Understanding Pipelines
+
+Apollo.io uses pipelines to organize sales opportunities. Each pipeline has multiple stages representing the sales process.
+
+## List Pipelines
+
+```bash
+# View all pipelines
+qodev-apollo-cli pipelines list
+
+# Get details of specific pipeline
+qodev-apollo-cli pipelines get <pipeline-id>
+
+# View as JSON
+qodev-apollo-cli --json pipelines list | jq '.items[].name'
+```
+
+## Pipeline Stages
+
+```bash
+# List stages in a pipeline
+qodev-apollo-cli pipelines stages <pipeline-id>
+
+# Get stage details
+qodev-apollo-cli stages get <stage-id>
+
+# Extract stage IDs with jq
+qodev-apollo-cli --json pipelines stages <pipeline-id> | jq '.items[] | {name, id}'
+```
+
+## Searching Deals
+
+```bash
+# Search all deals
+qodev-apollo-cli deals search
+
+# Search by keyword
+qodev-apollo-cli deals search --query "enterprise"
+
+# Filter by stage
+qodev-apollo-cli deals search --stage-id <stage-id>
+
+# Pagination
+qodev-apollo-cli deals search --page 2 --limit 50
+```
+
+## Deal Details
+
+```bash
+# Get deal details
+qodev-apollo-cli deals get <deal-id>
+
+# Extract specific fields with jq
+qodev-apollo-cli --json deals get <deal-id> | jq '{name, amount, stage_name, is_won}'
+```
+
+## Pipeline Analysis
+
+Analyze deals across stages:
+
+```bash
+# Count deals per stage
+qodev-apollo-cli --json deals search --stage-id <stage-id> | jq '.total'
+
+# List all won deals
+qodev-apollo-cli --json deals search | jq '.items[] | select(.is_won==true)'
+
+# Calculate total deal value
+qodev-apollo-cli --json deals search | jq '[.items[].amount] | add'
+```
+
+## Stage Movement Tracking
+
+Track deals as they move through stages:
+
+```bash
+# Get current stage distribution
+for stage_id in $(qodev-apollo-cli --json pipelines stages <pipeline-id> | jq -r '.items[].id'); do
+  count=$(qodev-apollo-cli --json deals search --stage-id "$stage_id" | jq '.total')
+  stage_name=$(qodev-apollo-cli --json stages get "$stage_id" | jq -r '.name')
+  echo "$stage_name: $count deals"
+done
+```
+
+## JSON Output Examples
+
+### Pipeline List
+
+```json
+{
+  "items": [
+    {
+      "id": "pipeline-123",
+      "name": "Sales Pipeline",
+      "created_at": "2024-01-01T00:00:00Z"
+    }
+  ],
+  "total": 1
+}
+```
+
+### Deal Search
+
+```json
+{
+  "items": [
+    {
+      "id": "deal-789",
+      "name": "Enterprise Deal",
+      "amount": 50000,
+      "stage_name": "Negotiation",
+      "is_won": false,
+      "owner_id": "owner-123"
+    }
+  ],
+  "total": 25,
+  "page": 1,
+  "limit": 25
+}
+```
+
+## Common Scenarios
+
+### Find deals in final stage
+
+```bash
+# Get final stage ID
+final_stage=$(qodev-apollo-cli --json pipelines stages <pipeline-id> | \
+  jq -r '.items[-1].id')
+
+# Search deals in final stage
+qodev-apollo-cli deals search --stage-id "$final_stage"
+```
+
+### Track deal progression
+
+```bash
+# Monitor specific deal
+watch -n 60 'qodev-apollo-cli deals get <deal-id> | grep -E "(stage_name|is_won)"'
+```

qodev_apollo_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,224 @@
+Metadata-Version: 2.4
+Name: qodev-apollo-cli
+Version: 0.1.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
+Project-URL: Issues, https://github.com/qodevai/apollo-cli/issues
+Author-email: Jan Scheffler <jan.scheffler@qodev.ai>
+License: MIT
+License-File: LICENSE
+Keywords: api,apollo,cli,contacts,crm,sales
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: cyclopts>=3.0
+Requires-Dist: qodev-apollo-api>=0.1.0
+Requires-Dist: rich>=13.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.13.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.25.0; extra == 'dev'
+Requires-Dist: pytest-mock>=3.15; extra == 'dev'
+Requires-Dist: pytest>=9.0; extra == 'dev'
+Requires-Dist: ruff>=0.15; extra == 'dev'
+Description-Content-Type: text/markdown
+
+[![CI](https://github.com/qodevai/apollo-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/qodevai/apollo-cli/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/qodev-apollo-cli)](https://pypi.org/project/qodev-apollo-cli/)
+
+# qodev-apollo-cli
+
+Agent-friendly CLI for the Apollo.io API. Designed for both human and AI-agent workflows, with structured JSON output, consistent flags, and predictable error codes.
+
+## Why this CLI?
+
+- **Agent-friendly** — `--json` on every command, consistent flags, predictable exit codes
+- **Built for AI agent workflows** — works seamlessly with Claude Code, scripts, and automation pipelines
+- **Comprehensive** — Access contacts, accounts, deals, enrichment, tasks, notes, and more
+- **Dual output modes** — Beautiful markdown tables for humans, structured JSON for agents
+
+## Installation
+
+```bash
+pip install qodev-apollo-cli
+```
+
+Or run directly without installing:
+
+```bash
+uvx qodev-apollo-cli
+```
+
+## Quick Start
+
+```bash
+# Set your Apollo API key
+export APOLLO_API_KEY="your_api_key_here"
+```
+
+```bash
+# Install AI agent skill files (for Claude Code, etc.)
+$ qodev-apollo-cli install --skills
+
+# Search contacts
+$ qodev-apollo-cli contacts search --query "engineer" --limit 5
+Jane Smith     VP Engineering     Acme Corp     jane@acme.com
+
+# Get contact details as JSON (for scripts/agents)
+$ qodev-apollo-cli --json contacts get <contact-id>
+{"id": "...", "name": "Jane Smith", "title": "VP Engineering", ...}
+
+# Enrich a company (free)
+$ qodev-apollo-cli enrich org acme.com
+
+# Search deals in a specific stage
+$ qodev-apollo-cli deals search --stage-id <stage-id>
+
+# Check API usage
+$ qodev-apollo-cli usage
+```
+
+## Commands
+
+| Group | Subcommand | Description |
+|---|---|---|
+| **contacts** | `search` | Search contacts (`--query`, `--stage-id`, `--linkedin-url`) |
+| | `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`) |
+| | `stages` | List all contact stages |
+| **accounts** | `search` | Search companies/accounts (`--query`, `--domain`) |
+| | `get` | Get account details by ID |
+| **deals** | `search` | Search opportunities/deals (`--query`, `--stage-id`) |
+| | `get` | Get deal details by ID |
+| **pipelines** | `list` | List all deal pipelines |
+| | `get` | Get pipeline details |
+| | `stages` | List stages in a pipeline |
+| **stages** | `list` | List all contact stages |
+| | `get` | Get stage details |
+| **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`) |
+| **tasks** | `search` | Search tasks (`--type`, `--status`) |
+| | `create` | Create a task (`--contact-ids`, `--note`, `--due-at`) |
+| **calls** | `search` | Search call activities |
+| **emails** | `search` | Search email activities |
+| **news** | `search` | Search news (`--categories`) |
+| **jobs** | `search` | Search job postings (`--job-titles`, `--company-domains`) |
+| **usage** | (default) | Show API usage stats and rate limits |
+| **install** | `--skills` | Install AI agent skill files to `.claude/skills/apollo/` |
+
+## Configuration
+
+### Authentication
+
+Set the `APOLLO_API_KEY` environment variable, or pass `--api-key` on each invocation:
+
+```bash
+export APOLLO_API_KEY="your_api_key_here"
+```
+
+Get your API key from [Apollo.io Settings → API](https://app.apollo.io/#/settings/integrations/api).
+
+### Global Options
+
+| Flag | Description | Default |
+|---|---|---|
+| `--json` | Output as JSON (for scripting / agents) | `false` |
+| `--api-key` | Apollo API key (overrides `APOLLO_API_KEY`) | |
+| `--limit` | Results per page | `25` |
+| `--page` | Page number | `1` |
+
+### Exit Codes
+
+| Code | Meaning |
+|---|---|
+| `0` | Success |
+| `80` | Authentication error (invalid API key) |
+| `81` | Rate limit exceeded |
+| `82` | API error (server error, invalid request) |
+| `83` | Validation error (missing required fields) |
+
+## JSON Output
+
+All commands support `--json` for structured output:
+
+```bash
+qodev-apollo-cli --json contacts search --query "engineer" | jq '.items[0].name'
+```
+
+Paginated responses include:
+
+```json
+{
+  "items": [...],
+  "total": 142,
+  "page": 1,
+  "limit": 25
+}
+```
+
+## Common Workflows
+
+### Find and enrich a contact
+
+```bash
+# Search by keyword
+qodev-apollo-cli contacts search --query "jane smith"
+
+# Get full details
+qodev-apollo-cli contacts get <contact-id>
+
+# Enrich person data (1 credit)
+qodev-apollo-cli enrich person jane@example.com
+```
+
+### Pipeline management
+
+```bash
+# List all pipelines
+qodev-apollo-cli pipelines list
+
+# Get stages in a pipeline
+qodev-apollo-cli pipelines stages <pipeline-id>
+
+# Search deals in specific stage
+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"
+
+# Auto-create if not found
+qodev-apollo-cli contacts find-by-linkedin "https://linkedin.com/in/janesmith" --create
+
+# Assign to stage on creation
+qodev-apollo-cli contacts find-by-linkedin "https://linkedin.com/in/janesmith" \
+  --create --stage-id <stage-id>
+```
+
+### Company enrichment (FREE)
+
+```bash
+# Enrich by domain (no credits used)
+qodev-apollo-cli enrich org acme.com
+
+# View as JSON
+qodev-apollo-cli --json enrich org acme.com | jq '.industry'
+```
+
+## License
+
+MIT -- see [LICENSE](LICENSE) for details.

qodev_apollo_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,37 @@
+apollo_cli/__init__.py,sha256=IJruWa5HWY14O2wD7u-JPUC5zuTTVesIF_eudLiEDWI,102
+apollo_cli/__main__.py,sha256=e_aD87eADAUZbJOmWbhRv6YvO_Q0EcpC-anVrKIoKd8,88
+apollo_cli/app.py,sha256=XsKvWw9EBO5RSVVZgH06GMWFhuCGc2dqYTbr6qkAFJY,4046
+apollo_cli/context.py,sha256=R8bDD1XWIzOdR2aGoFcMidAH8CBC9dWp3B8kYB8G8xw,997
+apollo_cli/help_reference.py,sha256=oI4YLlBzBlGPVYdErh8rvffmVsoeIs0R687WPOWSggc,3949
+apollo_cli/output.py,sha256=5Odu8QF9EhZe4baVQNRC3FDl22sJ1g7g8Hv7cIQtThc,4653
+apollo_cli/commands/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+apollo_cli/commands/accounts.py,sha256=K9fu_SroSGvDc6vofsrD_G1YxN3zd-Ms3s2DeZ7ti4A,1488
+apollo_cli/commands/calls.py,sha256=YHA5DO5sKDXcQZkrME9BXni12CoP-vUNMcj3qvEyPgU,1474
+apollo_cli/commands/contacts.py,sha256=-hFdDta7JCeNrKD0XRelIbKWnsrnW-jg4BHQWSc2qEA,4828
+apollo_cli/commands/deals.py,sha256=PQ84FI2MzTwGasp2zbzbVEbIMaZz9eDNWRKrvbyqJa0,1414
+apollo_cli/commands/emails.py,sha256=I9ysuwa2AjVOjVPQuoCOhNzT0P7c-XHIjHoEi1qX8fg,938
+apollo_cli/commands/enrich.py,sha256=FWKmo-LcPNilsLybfX3fZN6wMYpKzW8_YQXIUglesoA,873
+apollo_cli/commands/install.py,sha256=W7OKbiTaSGCWVA4BCpRMRgjnPCX1lYrCHiaEVnvSTCM,1795
+apollo_cli/commands/jobs.py,sha256=IJvmwDGRZvhr2gp2ukFYo0kuBRmHw8JUPjpBqiX2_Lk,949
+apollo_cli/commands/news.py,sha256=T9qXVg0r_dkJeJb8IzNBqN9--zLXS1JJ9LfjSImoe4Q,922
+apollo_cli/commands/notes.py,sha256=85_kyo0-gIhA-jRu742AF2Gyst_DKySdpZ8F-eFM4ik,2117
+apollo_cli/commands/people.py,sha256=z36kQ8DIoK_o-CHGz7koFNP-e2fBOH5zMaOpHdRVHVo,1102
+apollo_cli/commands/pipelines.py,sha256=5JlVZLY09ACdMmB2wpCu8uRHg4-UV3FMbwm5XqmhJ4s,2947
+apollo_cli/commands/tasks.py,sha256=BTi__oeZPaZLfWqUNfsooTtPmyZVZPAdamKJyMPvVvA,2399
+apollo_cli/commands/usage.py,sha256=ZJJQkdy8_muw0_O6l7CQo0km5jevaDQFYKwJUEbY3hE,2082
+apollo_cli/formatters/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+apollo_cli/formatters/accounts.py,sha256=9eTCpWvZf3t_YOgb5QzP-MrRCYJ_iCFSH9_wUZ5IkH8,1955
+apollo_cli/formatters/contacts.py,sha256=MT_oa6US1INg5PO9x9XWS4kpeSXfx8a1nMUp3R9DgCE,2608
+apollo_cli/formatters/deals.py,sha256=BO0gOOtfEKEQJEwkrepD708qz7d95CAfnSPSI8q-uPo,1378
+apollo_cli/formatters/generic.py,sha256=MiS-dDJ6W4LK59wIzVoQ4hHYGu9psKbefId1jcnRngo,2797
+apollo_cli/skills/SKILL.md,sha256=AUlar5IL6t-qs_Hal0L9iUEQKhcL4qP7o11UGYQFGMo,5050
+apollo_cli/skills/__init__.py,sha256=rT983nJxm9BbPKNDLwg15O8uHanhkNzmsCNBPwEOTPU,43
+apollo_cli/skills/references/__init__.py,sha256=fi5VN06uz4rvSjl5CzsEvIZqJVzaDUYTmUVW7wrtYoE,56
+apollo_cli/skills/references/account-workflows.md,sha256=qQJG6fbFmUGtSj4QMTTSnjtY1q6ZD2R4tO0kkBcMzbg,4663
+apollo_cli/skills/references/contact-workflows.md,sha256=5SelRI3oGBr8bRjxFvVCqOnAMGlbVutlI2UxlZWPUkc,2597
+apollo_cli/skills/references/deal-workflows.md,sha256=ZjeByBysMG3RDGXa3n2Ob5OpjdGoAWEHcUMNoOGXTho,2878
+qodev_apollo_cli-0.1.0.dist-info/METADATA,sha256=99sV9PZC2qWzKUufMKte2_ERbXWC6MtyzWrbollZC-w,6967
+qodev_apollo_cli-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+qodev_apollo_cli-0.1.0.dist-info/entry_points.txt,sha256=Kh08lw9mT78Pe1N8t5WuXomEd10cbBGa_JL0u5I0Tgo,57
+qodev_apollo_cli-0.1.0.dist-info/licenses/LICENSE,sha256=fBLVUpYuzVv0LgdVUWUtGELVlWVv5qKYrPNlJ9PCFaI,1067
+qodev_apollo_cli-0.1.0.dist-info/RECORD,,

qodev_apollo_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

qodev_apollo_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+qodev-apollo-cli = apollo_cli.app:main

qodev_apollo_cli-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 qodev GmbH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.