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

pip install qodev-apollo-cli

Or run directly without installing:

uvx qodev-apollo-cli

Quick Start

# Set your Apollo API key
export APOLLO_API_KEY="your_api_key_here"

# 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

Configuration

Authentication

Set the APOLLO_API_KEY environment variable, or pass --api-key on each invocation:

export APOLLO_API_KEY="your_api_key_here"

Get your API key from Apollo.io Settings → API.

Global Options

Exit Codes

JSON Output

All commands support --json for structured output:

qodev-apollo-cli --json contacts search --query "engineer" | jq '.items[0].name'

Paginated responses include:

{
  "items": [...],
  "total": 142,
  "page": 1,
  "limit": 25
}

Common Workflows

Find and enrich a contact

# 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

# 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>

Updating deals and tasks

# Move a deal forward: set the next step, its date, and the stage by name
qodev-apollo-cli deals update <deal-id> \
  --next-step "Send contract" --next-step-date 2026-09-07 --stage-name "Negotiation"

# Reassign a deal to a different account/owner
qodev-apollo-cli deals update <deal-id> --account-id <account-id> --owner-id <user-id>

# Reschedule a task
qodev-apollo-cli tasks update <task-id> --due-at 2026-09-09 --status scheduled

--due-at (on tasks create, tasks connect, and tasks update) accepts:

• YYYY-MM-DD — defaults to 09:00 Europe/Berlin
• YYYY-MM-DDTHH:MM (no timezone) — assumed Europe/Berlin
• a full ISO 8601 datetime with its own offset (e.g. 2026-09-09T07:00:00Z)

All forms are converted to UTC before being sent to Apollo.

LinkedIn integration

# Read-only lookup by LinkedIn URL (returns 0..n contacts, never writes)
qodev-apollo-cli contacts search --linkedin-url "https://linkedin.com/in/janesmith"

# 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"

# 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)

# 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 for details.