# Apollo CLI

[![Build Status](https://img.shields.io/badge/build-passing-brightgreen)](https://github.com/dipankar/apollo-io-cli)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Rust](https://img.shields.io/badge/rust-1.70%2B-orange.svg)](https://www.rust-lang.org/)
[![Apollo.io API](https://img.shields.io/badge/Apollo.io%20API-Full%20Coverage-blue)](https://docs.apollo.io/)

> **Agent-first Apollo.io CLI** — A powerful command-line interface for the Apollo.io API, designed for both humans and AI agents.

## Features

- **Full API Coverage** — 50+ Apollo.io API operations supported
- **Dual Interface** — Human-friendly subcommands AND agent-friendly `exec` command
- **JSON In, JSON Out** — All responses are valid JSON, including errors
- **Stdin Piping** — Pipe JSON data from files or other commands
- **Comprehensive Help** — Built-in examples for every command
- **Man Pages** — Unix man page documentation

## Quick Start

### Installation

```bash
# Install via npm (recommended)
npm install -g apollo-io-cli

# Or install via cargo
cargo install --git https://github.com/Skelf-Research/apollo-io-cli

# Or build from source
cargo build --release
# Binary is at ./target/release/apollo
```

### Configuration

Set your Apollo.io API key:

```bash
export APOLLO_API_KEY="your_api_key_here"
```

Get your API key from [Apollo.io Settings > Integrations > API](https://app.apollo.io/).

### Basic Usage

```bash
# Search for people
apollo search people --data '{"q_keywords": "software engineer", "person_titles": ["CTO", "VP Engineering"]}'

# Enrich a person by email
apollo enrichment people --data '{"email": "john@example.com"}'

# Create a contact
apollo contacts create --data '{"first_name": "John", "last_name": "Doe", "email": "john@example.com"}'

# List all deals
apollo deals list
```

## Usage Modes

### Subcommand Style (Human-Friendly)

Hierarchical commands with tab completion:

```bash
apollo contacts create --data '{"first_name": "John"}'
apollo accounts search --data '{"q_keywords": "tech"}'
apollo enrichment organization --domain "example.com"
```

### Exec Style (Agent-Friendly)

Single command with operation string — ideal for AI agents:

```bash
apollo exec contacts.create --data '{"first_name": "John"}'
apollo exec accounts.search --data '{"q_keywords": "tech"}'
apollo exec enrichment.organization --data '{"domain": "example.com"}'
```

### Stdin Piping

Pipe JSON data from files or other commands:

```bash
cat contacts.json | apollo exec contacts.bulk-create
echo '{"email": "test@example.com"}' | apollo enrichment people
```

### List All Operations

```bash
apollo operations
```

## All Operations

| Category | Operation | Description |
|----------|-----------|-------------|
| **Enrichment** | `enrichment.people` | Enrich data for a single person |
| | `enrichment.people-bulk` | Enrich data for multiple people |
| | `enrichment.organization` | Enrich data for a single organization |
| | `enrichment.organization-bulk` | Enrich data for multiple organizations |
| **Search** | `search.people` | Search for people (consumes credits) |
| | `search.people-api` | Search for people (credit-free, master key) |
| | `search.organizations` | Search for organizations |
| | `search.job-postings` | Get job postings for an organization |
| | `search.organization-info` | Get complete organization info |
| | `search.news` | Search for news articles |
| **Contacts** | `contacts.create` | Create a new contact |
| | `contacts.get` | Get a contact by ID |
| | `contacts.update` | Update a contact |
| | `contacts.search` | Search for contacts |
| | `contacts.bulk-create` | Bulk create contacts |
| | `contacts.bulk-update` | Bulk update contacts |
| | `contacts.bulk-stage-update` | Update stage for multiple contacts |
| | `contacts.bulk-owner-update` | Update owner for multiple contacts |
| | `contacts.stages` | List all contact stages |
| **Accounts** | `accounts.create` | Create a new account |
| | `accounts.get` | Get an account by ID |
| | `accounts.update` | Update an account |
| | `accounts.search` | Search for accounts |
| | `accounts.bulk-create` | Bulk create accounts |
| | `accounts.bulk-update` | Bulk update accounts |
| | `accounts.bulk-owner-update` | Update owner for multiple accounts |
| | `accounts.stages` | List all account stages |
| **Deals*** | `deals.create` | Create a new deal |
| | `deals.list` | List all deals |
| | `deals.get` | Get a deal by ID |
| | `deals.update` | Update a deal |
| | `deals.stages` | List all deal stages |
| **Sequences** | `sequences.search` | Search for sequences |
| | `sequences.activate` | Activate a sequence |
| | `sequences.add-contacts` | Add contacts to a sequence |
| | `sequences.update-status` | Update contact status in a sequence |
| | `sequences.emails` | Search for outreach emails |
| | `sequences.email-stats` | Get email statistics |
| **Tasks** | `tasks.create` | Create a new task |
| | `tasks.bulk-create` | Bulk create tasks |
| | `tasks.search` | Search for tasks |
| **Calls*** | `calls.create` | Create a call record |
| | `calls.search` | Search for calls |
| | `calls.update` | Update a call record |
| **Misc** | `misc.health` | Test API key validity |
| | `misc.usage` | View API usage stats and rate limits |
| | `misc.users` | List all users |
| | `misc.email-accounts` | List email accounts |
| | `misc.lists` | List all labels/lists |
| | `misc.custom-fields` | List all custom fields |
| | `misc.create-custom-field` | Create a custom field |
| | `misc.fields` | List all available fields |

*Note: Deals use `/opportunities` internally; Calls use `/phone_calls` internally in the Apollo API.

## Output Format

All responses are JSON:

```json
{
  "success": true,
  "data": { ... }
}
```

Errors also return JSON:

```json
{
  "success": false,
  "error": {
    "code": "invalid_input",
    "message": "Operation 'contacts.get' requires --id parameter"
  }
}
```

## Man Pages

Generate and install man pages:

```bash
# Generate man pages
cargo run --example gen_manpages

# Install man pages (Linux/macOS)
./install-man.sh

# View man page
man apollo
```

## Documentation

Full documentation available at [documentation/](documentation/).

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## License

MIT License - see [LICENSE](LICENSE) for details.

## Links

- [Apollo.io API Documentation](https://docs.apollo.io/)
- [Report Issues](https://github.com/dipankar/apollo-io-cli/issues)