# AI chat

`tomba chat` takes requests in plain language, such as "Find the head of sales at Stripe and verify their email", and lets an OpenAI model decide which Tomba lookups to run. It uses your own OpenAI API key.

## Requirements

- The CLI, signed in to Tomba ([Authentication](/cli/authentication)).
- An OpenAI API key in the `OPENAI_API_KEY` environment variable. OpenAI bills its usage to that key.

## Data and credits

The CLI sends your messages, its instructions to the model, the list of available lookups, and the full response of every lookup it runs to OpenAI's Chat Completions API (`https://api.openai.com/v1/chat/completions`), from your machine and with your key. In batch mode, it also sends values from each CSV row.

<Callout type="caution">
    Lookup results sent to OpenAI include personal data, such as people's names,
    email addresses, and phone numbers.
</Callout>

The model chooses the lookups, and one request can lead to several of them. Each is a Tomba API request billed as described in [Credit costs](/usage-and-quotas#credit-costs), and the CLI doesn't ask before running it.

An interactive chat saves nothing locally: the conversation is kept in memory until you exit. Batch mode writes one CSV file.

## Start a chat

```bash
export OPENAI_API_KEY="sk-..."
tomba chat
```

Type a request at the `You:` prompt. The CLI prints the lookups the model ran, such as `workflow: domain_search -> email_finder -> email_verifier`, followed by the model's answer. Type `quit`, `exit`, or `q` to leave.

| Flag             | Type   | Default                | Description                                                 |
| ---------------- | ------ | ---------------------- | ----------------------------------------------------------- |
| `--model`        | string | `gpt-4o`               | OpenAI model to use. It must support tool calling.          |
| `--file`         | string | —                      | CSV file to process in batch mode.                          |
| `--type`         | string | `enrich`               | Batch operation: `enrich`, `verify`, `finder`, or `search`. |
| `--output`, `-o` | string | `<input>_enriched.csv` | Output file in batch mode.                                  |

The help for `--type` also lists `linkedin` and `author`, but the CLI builds no request for those types, so their rows fail.

## Lookups the model can run

| Tool               | Calls                                                    |
| ------------------ | -------------------------------------------------------- |
| `domain_search`    | [`GET /v1/domain-search`](/api/finder#domain-search)     |
| `email_finder`     | [`GET /v1/email-finder`](/api/finder#email-finder)       |
| `email_verifier`   | [`GET /v1/email-verifier`](/api/verifier#email-verifier) |
| `email_enrichment` | [`GET /v1/enrich`](/api/finder#email-enrichment)         |
| `email_count`      | [`GET /v1/email-count`](/api/finder#email-count)         |
| `email_sources`    | [`GET /v1/email-sources`](/api/email#email-sources)      |
| `linkedin_finder`  | [`GET /v1/linkedin`](/api/finder#linkedin-finder)        |
| `author_finder`    | [`GET /v1/author-finder`](/api/finder#author-finder)     |
| `domain_status`    | [`GET /v1/domain-status`](/api/domain#domain-status)     |
| `phone_finder`     | [`GET /v1/phone-finder`](/api/phone#phone-finder)        |

## Batch mode

```bash
tomba chat --file contacts.csv --type verify
```

For each row, the CLI sends the model one request built from the row:

| `--type`           | Request sent for each row                                                                               |
| ------------------ | ------------------------------------------------------------------------------------------------------- |
| `enrich`, `verify` | The value of the column named `email`, `e-mail`, `mail`, or `email_address`; without one, the whole row |
| `search`           | The value of the column named `domain`, `company_domain`, or `website`; without one, the whole row      |
| `finder`           | Every non-empty column, as `column=value` pairs                                                         |

Rows are processed one at a time. When all rows are done, the CLI writes the output file, with your input columns followed by the same result columns as [`tomba bulk`](/cli/bulk), and prints a table of the first 20 rows. It doesn't resume an interrupted run. The input must be a comma-separated file with a header row, and every row must have the same number of fields.

To run a single lookup per row without OpenAI, use [`tomba bulk`](/cli/bulk).

## Examples

```bash
# Interactive chat with another model
tomba chat --model gpt-4o-mini

# Enrich every address in a file
tomba chat --file contacts.csv --type enrich

# Find addresses from name and company columns, writing to a chosen file
tomba chat --file prospects.csv --type finder --output prospects_found.csv
```