Copy page

CLI

CLI commands

This reference describes CLI version 1.2.3. Each command on this page calls the Tomba API with your credentials, so it uses credits and counts toward your limits exactly like the endpoint it calls: see Credit costs and Rate limits. Commands with their own pages: tomba bulk, tomba chat, tomba serve, tomba skill, tomba login and tomba logout, and tomba version, tomba completion, and tomba update.

Global flags

Every command accepts these flags.

Output and errors

By default, commands print a formatted summary. --json prints the response as JSON, syntax-colored only when the output is a terminal. --yaml output always contains terminal color codes, even with --no-color, so use --json when you redirect or parse the output. --csv suits flat responses; nested objects aren't flattened.

The list subcommands of lead, leads-list, attribute, key, and flag number the rows in their text output but don't show IDs. Run them with --json to get the id values that get, update, and delete take.

When a request fails, or when search, finder, author, enrich, linkedin, verify, sources, or count has no result, the CLI prints a short message instead of the response, even with --json. API errors appear as error: <HTTP status>, status code: <code>, such as error: 429 Too Many Requests, status code: 429; the response body isn't shown. See Status codes. The exit status is 0 in all of these cases; only usage errors, such as an unknown or missing flag, exit with 1. In scripts, parse the output rather than the exit status, and add --no-color.

Aliases

The help for tomba search and tomba sources lists the alias s, and the help for tomba verify lists t, but those aliases run tomba finder and tomba status.

tomba search

Find the email addresses Tomba has for a domain. Calls GET /v1/domain-search.

Code
tomba search --target <domain> [--limit 10|20|50] [--page <n>]

Code
tomba search --target stripe.com
tomba search --target stripe.com --limit 50 --page 2
tomba search --target stripe.com --json --output stripe.json

The text output shows the organization, then a table of addresses with name, position, department, and confidence score. The Free plan restricts --limit and --page; see Free plan limits.

tomba finder

Find a person's email address from their name and company domain. Calls GET /v1/email-finder.

Code
tomba finder --target <domain> --first <first name> --last <last name> [--enrich-mobile]
tomba finder --target <domain> --full "<full name>" [--enrich-mobile]

Code
tomba finder --target stripe.com --first Jane --last Doe
tomba finder --target stripe.com --full "Jane Doe" --enrich-mobile

tomba author

Find the email address of an article's author. Calls GET /v1/author-finder.

Code
tomba author --target <article URL>

Code
tomba author --target "https://stripe.com/blog/example-article"

tomba enrich

Look up the person behind an email address: name, position, company, social profiles, and sources. Calls GET /v1/enrich. For separate person and company profiles, use tomba enrichment.

Code
tomba enrich --target <email> [--enrich-mobile]

Code
tomba enrich --target jane.doe@stripe.com
tomba enrich --target jane.doe@stripe.com --enrich-mobile --json

tomba enrichment

Get a person profile, a company profile, or both. Each subcommand takes its input with --target and has no other flags.

Code
tomba enrichment person --target <email>
tomba enrichment company --target <domain>
tomba enrichment combined --target <email>

tomba enrichment person

Get the profile of the person who owns an email address. Calls GET /v1/people/find.

Code
tomba enrichment person --target jane.doe@stripe.com

tomba enrichment company

Get the profile of the company behind a domain. Calls GET /v1/companies/find.

Code
tomba enrichment company --target stripe.com

tomba enrichment combined

Get the person and company profiles for an email address in one request. Calls GET /v1/combined/find.

Code
tomba enrichment combined --target jane.doe@stripe.com --json

tomba verify

Check whether an email address is deliverable. Calls GET /v1/email-verifier. For what the status and result values mean, see Email verifier response.

Code
tomba verify --target <email>

Code
tomba verify --target jane.doe@stripe.com
tomba verify --target jane.doe@stripe.com --json

For an address at a webmail or disposable email domain, the CLI prints a warning instead of the result, even with --json. The verification still runs and uses credits as usual.

tomba linkedin

Find the email address for a LinkedIn profile. Calls GET /v1/linkedin.

Code
tomba linkedin --target <profile URL> [--enrich-mobile]

Code
tomba linkedin --target "https://www.linkedin.com/in/jane-doe-example"

tomba sources

List the public web pages where Tomba found an email address. Calls GET /v1/email-sources.

Code
tomba sources --target <email>

Code
tomba sources --target jane.doe@stripe.com

tomba count

Count the email addresses Tomba has for a domain, by department and seniority. Calls GET /v1/email-count.

Code
tomba count --target <domain>

Code
tomba count --target stripe.com

tomba status

Check whether a domain belongs to a webmail or disposable email provider. Calls GET /v1/domain-status.

Code
tomba status --target <domain>

Code
tomba status --target gmail.com

tomba format

Get the email address patterns a domain uses, such as {first}.{last}. Calls GET /v1/email-format.

Code
tomba format --target <domain>

Code
tomba format --target stripe.com

tomba location

Get a company's employee counts by location. Calls GET /v1/location.

Code
tomba location --target <domain>

Code
tomba location --target stripe.com

tomba autocomplete

Suggest companies, with their domains and email counts, from part of a name. Calls GET /v1/domain-suggestions.

Code
tomba autocomplete --target <text>

Code
tomba autocomplete --target strip

tomba phone-finder

Find phone numbers from an email address, a domain, or a LinkedIn profile. Calls GET /v1/phone-finder.

Code
tomba phone-finder --email <email> [--full]
tomba phone-finder --domain <domain> [--full]
tomba phone-finder --linkedin <profile URL> [--full]

Pass one input. If you pass more than one, the CLI sends only the first of --email, --domain, and --linkedin. The input type affects the cost.

Code
tomba phone-finder --email jane.doe@stripe.com
tomba phone-finder --domain stripe.com --full
tomba phone-finder --linkedin "https://www.linkedin.com/in/jane-doe-example"

tomba phone-validator

Check whether a phone number is valid, and get its formats, line type, and carrier. Calls GET /v1/phone-validator.

Code
tomba phone-validator --phone <number> [--country-code <code>]

Code
tomba phone-validator --phone "+14155552671"
tomba phone-validator --phone 4155552671 --country-code US

tomba reveal

Search for companies with a natural-language query or with filters. Calls POST /v1/reveal/search.

Code
tomba reveal --query "<description>" [--page <n>]
tomba reveal [filter flags] [--page <n>]

Use --query or filter flags, not both: the API rejects a request that has both. Each filter flag takes a comma-separated list, or you can repeat the flag; the CLI sends the values as include filters. Accepted values are listed in Search Companies.

Code
tomba reveal --query "Fintech companies in France"
tomba reveal --country US,GB --size 51-200,201-500
tomba reveal --country FR --size 51-200 --page 2 --json

On the Free plan, company search returns only the first page and ignores some filters; see Free plan limits.

tomba similar

Find companies similar to a domain. Calls GET /v1/similar.

Code
tomba similar --target <domain>

Code
tomba similar --target stripe.com

tomba technology

List the technologies detected on a domain's website. Calls GET /v1/technology.

Code
tomba technology --target <domain>

Code
tomba technology --target stripe.com

tomba flag

Report data from Tomba that's wrong, such as an address that bounced, and list your reports. Some confirmed reports return a credit; see Refunds for incorrect data.

tomba flag create

Report an item. Calls POST /v1/flag.

Code
tomba flag create --type <type> --value <item> --reason <reason> [--comment <text>]

Code
tomba flag create --type email --value jane.doe@stripe.com --reason hard_bounce
tomba flag create --type phone --value "+14155552671" --reason wrong_phone --comment "Number disconnected"

tomba flag list

List your reports and their review status. Calls GET /v1/flag. The text output leaves the reported item blank; use --json.

Code
tomba flag list --json

tomba lead

Manage the leads saved in your account. Get lead IDs from tomba lead list --json.

Code
tomba lead list [--page <n>] [--limit <n>]
tomba lead get --id <id>
tomba lead create --email <email> --list-id <id> [--first-name <name>] [--last-name <name>]
tomba lead update --id <id> [--email <email>] [--first-name <name>] [--last-name <name>]
tomba lead delete --id <id>

tomba lead list

List leads, newest first. Calls GET /v1/leads.

tomba lead get

Get one lead. Calls GET /v1/leads/{id}. Requires --id.

tomba lead create

Save a lead. Calls POST /v1/leads.

The CLI sends --list-id as a string, which the API doesn't accept as a list ID, so the lead is saved without a list. To add a lead to a list, use the dashboard or POST /v1/leads with a numeric list_id.

Code
tomba lead create --email jane.doe@stripe.com --list-id 1 --first-name Jane --last-name Doe

tomba lead update

Change a lead's email address or name. Calls PUT /v1/leads/{id}.

tomba lead delete

Delete a lead. Calls DELETE /v1/leads/{id}. Requires --id.

tomba leads-list

Manage lead lists. Get list IDs from tomba leads-list list --json.

Code
tomba leads-list list
tomba leads-list get --id <id>
tomba leads-list create --name <name>
tomba leads-list update --id <id> --name <name>
tomba leads-list delete --id <id>

tomba leads-list list

List your lead lists. Calls GET /v1/leads_lists. Takes no flags.

tomba leads-list get

Get one list. Calls GET /v1/leads_lists/{id}. Requires --id.

tomba leads-list create

Create a list. Calls POST /v1/leads_lists. Requires --name.

Code
tomba leads-list create --name "Q3 prospects"

tomba leads-list update

Rename a list. Calls PUT /v1/leads_lists/{id}. Requires --id and --name.

tomba leads-list delete

Delete a list. Calls DELETE /v1/leads_lists/{id}. Requires --id.

tomba attribute

Manage custom lead attributes. Get attribute IDs from tomba attribute list --json.

Code
tomba attribute list
tomba attribute get --id <id>
tomba attribute create --name <name> --type <type>
tomba attribute delete --id <id>

tomba attribute list

List your custom attributes. Calls GET /v1/attributes. Takes no flags.

tomba attribute get

Get one attribute. Calls GET /v1/attributes/{id}. Requires --id.

tomba attribute create

Create an attribute. Calls POST /v1/attributes. Requires --name and --type; the accepted types are listed in Create a Lead Attribute.

Code
tomba attribute create --name "Company size" --type string

tomba attribute update

Calls PUT /v1/attributes/{id} with --id and --name. The API also requires the attribute's type, which the CLI doesn't send, so this subcommand fails with error: 422 Unprocessable Entity. Rename attributes in the dashboard or with the API.

tomba attribute delete

Delete an attribute. Calls DELETE /v1/attributes/{id}. Requires --id.

tomba key

Manage the API keys of your workspace. For how keys expire and how to replace them, see Key expiry and Rotate keys. Get key IDs from tomba key list --json.

Code
tomba key list
tomba key get --id <id>
tomba key create
tomba key delete --id <id>

tomba key list

List the keys of every member of your workspace. Calls GET /v1/keys. The text output shortens each key; --json shows full values, IDs, and expiry dates.

tomba key get

Get one key. Calls GET /v1/keys/{id}. Requires --id.

tomba key create

Create a key with a generated name and the default lifetime. Calls POST /v1/keys. The text output shows only the new key's ID; run tomba key create --json to get the key itself, in data.message. The command takes no flags; to set a name or a shorter lifetime, use the dashboard or the API.

tomba key delete

Delete a key. Calls DELETE /v1/keys/{id}. Requires --id. Requests that use the key fail from then on, including the CLI's own if you logged in with that key.

tomba key reset

Calls PUT /v1/keys/{id}/reset, a route the API doesn't have, so it fails with error: 404 Not Found. To rotate a key, use the dashboard or PUT /v1/keys/{id}.

tomba whoami

Show the account the CLI is signed in to. Calls GET /v1/me.

Code
tomba whoami
tomba whoami --json

The text output shows your account details and plan name. --json adds your search and verification allowances and usage, in requests.domains and requests.verifications (Check usage), and your API secret, in secret_token. Don't share --json or --output output from this command.

tomba usage

Show your daily usage. Calls GET /v1/usage.

Code
tomba usage

The CLI keeps only the verification counts from the response; search and other counts show as 0. For your balances, use tomba whoami --json, the Usage page of the dashboard, or GET /v1/usage.

tomba logs

Show your 20 most recent logged requests, newest first. Calls GET /v1/logs. Only charged lookups are logged, including repeats charged 0; see Duplicate requests. The text output lists each request's method, URI, type, and date; --json adds its cost.

Code
tomba logs
tomba logs --json

The command takes no paging flags. To page through older entries, call GET /v1/logs with page and limit.