# Command-line tool

> Use the mobilevalidate CLI to check phone numbers and e-mails, run bulk jobs from files, and read results as tables, JSON or NDJSON.

Canonical: https://mobilevalidate.com/docs/cli · Last updated: 2026-09-25

The `mobilevalidate` command-line tool comes with the [SDK](/docs/sdk). You can use it to check numbers and e-mail addresses, run bulk jobs from files and read results without writing code. In a terminal it prints tables. When piped, it prints NDJSON or JSON, so it fits into shell scripts and data pipelines.

## How do I run it?

Run it with `npx`, no install needed. `--sandbox` uses the public sandbox key, so this works without signing up:

```bash tabs=off
npx mobilevalidate check +447700900001 +447700900002 registered@test.mobilevalidate.com --sandbox
```

Without `--sandbox`, the key comes from `MOBILEVALIDATE_API_KEY` or `--api-key`. The API URL comes from `--base-url` or `MOBILEVALIDATE_BASE_URL` (default `https://api.mobilevalidate.com`). The CLI needs Node 18 or later and never prints your key.

## Which commands are there?

```text
mobilevalidate check <number|email...|-> [--checks whatsapp,telegram,email] [--country GB] [--max-age 7d] [--wait 60] [--max-cost 1.00] [--json]
mobilevalidate check-email <address...|-> [--checks email,gmail]
mobilevalidate services [--json]
mobilevalidate lookup <lkp_id> [--wait 30]
mobilevalidate jobs create --file list.csv [--checks whatsapp,email] [--wait [seconds]]
mobilevalidate jobs get <job_id> [--wait 30]
mobilevalidate jobs results <job_id> [--registered true|false|null] [--limit 500]
mobilevalidate jobs download <job_id> [--format csv|ndjson] [--output results.csv]
mobilevalidate jobs cancel <job_id>
mobilevalidate webhooks verify --secret whsec_… --file body.json --headers headers.txt
mobilevalidate webhooks sign --secret whsec_… --file body.json
mobilevalidate webhooks list | test <endpoint_id>
mobilevalidate account | limits
```

- `check` takes numbers and e-mail addresses together. The default checks are `whatsapp` for numbers and `email` for addresses. With several `--checks` you get one table column per service; `spam` adds `SPAM RISK` and `SPAM SCORE`.
- `jobs create --wait` waits for the job (up to 600 s by default), then prints its results.
- `jobs download` writes the whole result file (CSV by default) to stdout, or streams it to `--output <path>`.
- `check-email` runs a job for bulk-only e-mail checks such as `gmail` and waits for it within `--wait`.
- `webhooks sign` prints signed headers for a body, so you can test your receiver locally; `webhooks verify` checks a delivery you captured.
- On an API error the CLI prints the code and message, then the API's `suggestion`, the docs link and the request ID.

## How do I feed it lists?

Use `-` to read from stdin, one identifier per line (commas and tabs also work):

```bash
cat numbers.txt | mobilevalidate check - --checks whatsapp,carrier
mobilevalidate jobs create --file leads.csv --wait
```

For CSV files, the CLI uses the `phone`, `number`, `msisdn`, `mobile` or `e164` column and/or the `email` column. If none of these exists, it uses the first column, and cells containing `@` are sent as e-mails. Lists longer than 100 entries belong in `jobs create`. Requests that look like sequential number ranges or generated e-mail lists are rejected by the API, whichever client sends them.

## What do the exit codes mean?

| Code | Meaning |
|---|---|
| `0` | Success, all results conclusive |
| `1` | The request failed (API error, network), the job failed, or a webhook signature is invalid |
| `2` | Usage error (bad flags or arguments) |
| `3` | At least one result is not conclusive: unknown, pending, unsupported country, invalid, duplicate or suppressed |

Exit code `3` lets a script tell "everything answered" apart from "some rows need another look" without parsing the output. Output formats: a table on a terminal, NDJSON (one result per line) when piped, and one JSON document with `--json`.

## Frequently asked questions

### Does the CLI log the numbers I check?

No. Pass lists on stdin or from a file rather than as arguments if your shell history is shared. The CLI never prints your API key.

### How do I use the CLI in a script?

Pipe its output: when stdout is not a terminal it prints NDJSON, one result per line, or a single JSON document with --json. Exit code 3 means at least one result was unknown, pending or invalid.