---
title: "Command line | Proxy Mail QA"
description: "npx proxymail-qa: make a test address, wait for its code or link, show its persona and get form values from a terminal, an npm script, a JetBrains run configuration or CI."
url: https://proxymail.qa/docs/cli
---

# Command line

The [proxymail-qa](https://www.npmjs.com/package/proxymail-qa) package has a command, from version 0.13.0\. Use it in a terminal while you test by hand, in npm scripts, in a JetBrains or VS Code run configuration, or in a CI step. It runs on Node 18 or later and needs no install beyond `npx`.

### Step 1: Set the API key

Create an [API key](https://proxymail.qa/docs/api-keys) and set it as `PROXYMAIL_QA_API_KEY`. The command reads the key only from the environment, never from an option, so it stays out of your shell history.

```sh
export PROXYMAIL_QA_API_KEY=qa_...
```

### Step 2: Make a test address

In a terminal it shows the address, the password, and the persona’s name, username, date of birth and country, ready to type into the sign-up form. The password is saved on the address and shown only this once.

```sh
npx proxymail-qa new --password --country JP
```

### Step 3: Wait for the code or link

Sign up with the address, then:

A wait holds for 30 seconds unless you give `--timeout`. If nothing arrives, it says why as far as Proxy Mail QA can tell and exits with 1.

```sh
npx proxymail-qa wait-code k7f2@mailclub.dev
npx proxymail-qa wait-link k7f2@mailclub.dev --type reset
```

## Commands

| Command             | What it does                                                                                                                                           |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| new                 | Makes a test address with a persona. \--password, \--country, \--age or \--dob, \--one-name, \--label, \--site, \--environment, \--days, \--no-persona |
| wait-code <address> | Waits for a sign-in code. \--type coupon for a coupon, \--since, \--service, \--unused, \--timeout                                                     |
| wait-link <address> | Waits for a link. \--type verify, reset, magic\_signin or invite (several with commas), \--app for the link that opens a mobile app                    |
| persona <address>   | Shows the address’s persona                                                                                                                            |
| form-values <file>  | What to type in each field of a form: see below                                                                                                        |

`npx proxymail-qa help <command>` lists a command’s options. Add `--json` to any command for the whole answer as JSON.

## In scripts and CI

When its output goes to a pipe or a variable, a command prints just the value: the address, the code or the link. `new --password` prints the address, then the password on a second line.

```sh
ADDRESS=$(npx proxymail-qa new --site staging.example.com --environment staging)
# …sign up with $ADDRESS…
CODE=$(npx proxymail-qa wait-code "$ADDRESS" --timeout 60)
```

The password is printed so a script can use it: keep it in a variable and don’t echo it to a CI log. In a run (`PROXYMAIL_QA_RUN`, which the [GitHub Action](https://proxymail.qa/docs/ci) sets), every call is added to the run’s report.

As npm scripts, so the team runs the same commands:

package.json

```json
{
  "scripts": {
    "inbox": "proxymail-qa new --password --site localhost:3000 --environment local",
    "code": "proxymail-qa wait-code"
  }
}
```

`npm run inbox`, then `npm run code -- k7f2@mailclub.dev`. In JetBrains IDEs, add a run configuration of type npm for each script, or a Shell Script configuration that runs `npx proxymail-qa new`.

## Form values

`form-values` takes a JSON file that lists a form’s fields, and answers with what to type in each one, from a new address or one you name with `--address`. It fills the project’s [custom fields](https://proxymail.qa/docs/custom-fields) and the names, dates and passwords a form asks for, as the [Node.js client’s formValues](https://proxymail.qa/docs/node#values-for-a-sign-up-form) does.

signup-form.json

```json
{
  "fields": [
    { "id": "email", "type": "email", "label": "Email" },
    { "id": "name", "label": "Full name" },
    { "id": "team", "type": "select", "label": "Team size", "options": [{ "value": "1-10" }, { "value": "11-50" }] }
  ],
  "page": "/signup"
}
```

```sh
npx proxymail-qa form-values signup-form.json --site staging.example.com --country PK
```

It prints JSON: the address, the persona, the password when one was made, and a value per field. Options on the command line win over the same ones in the file. Use `-` instead of a file name to read the fields from standard input.

## Exit codes

| Code | Meaning                                                                      |
| ---- | ---------------------------------------------------------------------------- |
| 0    | Done                                                                         |
| 1    | The API refused, or nothing arrived in time. The reason is on standard error |
| 2    | The command was wrong, or PROXYMAIL\_QA\_API\_KEY isn’t set                  |

[Previous](https://proxymail.qa/docs/python.html): Python

[Next](https://proxymail.qa/docs/vscode.html): VS Code and Cursor
