# The command line tool for Apidog

Apidog CLI is a command line tool to run `Test Case` of Apidog

## Getting started

To run Apidog CLI, please make sure your Node.js >= 10. [Install Node.js](https://nodejs.org/en/download/package-manager/)

### Installation

Install Apidog CLI with the follow command

```console
$ npm install -g apidog-cli
```

### Export data

Export your test case data as a Apidog CLI formatted file from Apidog

### Run test case

```console
$ apidog run examples/sample.apidog-cli.json -r cli,html
```

The test report will be saved in `apidog-reports` of current directory

- If you want to customize report, you can pass through the follow option `-r cli,json` to get the json formatted result

## Command options

### `apidog [options]`

- `-h`, `--help`
  Show command line help, including a list of options, and sample use cases.

- `-v`, `--version`
  Displays the current Apidog CLI version

### `apidog run <file-source> [options]`

`file-source` is the file path of the export test case data from Apidog

Options:

```
  --access-token <accessToken>          Set an authentication token and use it with the -t/-f command to specify a test scenario or test scenario folder to run
  -t, --test-scenario <testScenarioId>  Specify the test scenario ID to run the corresponding test scenario by ID
  -f, --test-scenario-folder <folderId> Specify the test scenario folder ID to run the corresponding test scenarios by folder ID
  -r, --reporters [reporters]           Specify test report file extension, support cli, html, json, junit (default: ["cli"])
  --out-dir <outDir>                    Test report final export dir, by default is apidog-reports folder in the current dir
                                        (default: "./apidog-reports")
  --out-file <outFile>                  Test report name, ignore file extension name, by default is apidog-report-{timestamp}-0
                                        (default: "apidog-report-2022-10-25-15-03-50-160-0")
  -e, --environment                     Specify the runtime environment. All test scenarios in this execution
  --variables                           Specify the file path containing the environment/global variables. If it's not specified, the environment/global variables will use initial values by default.
  -n, --iteration-count <n>             Define the number of iterations to run
  -d, --iteration-data <path|testDataId>           Define the data which use for iterations (either JSON or CSV)
  --on-error <value>                  Define the action when an error occurs (ignore|continue|end)
  --env-var <key=value>                 Specifies environment variables, in a key=value format. Multiple CLI environment variables can be added, for example: --env-var "user=123" --env-var "password=123"
  --global-var <key=value>              Specifies global variables, in a key=value format. Multiple CLI global variables can be added, for example: --global-var "user=123" --global-var "password=123"
  --notification <targetIds>            Notify the specified targets after execution. Use a comma (',') to add multiple target IDs.
  --notification-failed-event <targetIds>           Notify the specified targets only when a failure occurs after execution. Use a comma (',') to add multiple target IDs.
  --external-program-path <path>        Specify the file path of external program, by default is current dir
  --database-connection <path>          Specify the file path of database configuration, it is required when CLI run with URL
  --ignore-redirects                    Prevent Apidog from automatically following 3XX redirect response
  --silent                              Prevent Apidog CLI from showing output
  --color <value>                       Enable/Disable colored output (auto|on|off) (default: "auto")
  --delay-request [n]                   Specify the extent of delay between requests (milliseconds) (default: 0)
  --timeout-request [n]                 Specify a timeout for requests (milliseconds) (default: 0)
  --timeout-script [n]                  Specify a timeout for pre/post requests (milliseconds) (default: 0)
  -k, --insecure                        Disables SSL validations
  --ssl-client-cert-list <path>         Specify the path to a client certificates configurations (JSON)
  --ssl-client-cert <path>              Specify the path to a client certificate (PEM)
  --ssl-client-key <path>               Specify the path to a client certificate private key
  --ssl-client-passphrase <passphrase>  Specify the client certificate passphrase (for protected key)
  --ssl-extra-ca-certs <path>           Specify additionally trusted CA certificates (PEM)
  --upload-report                       Upload the overview of this test report to the cloud, and you can view this test report in the app
  -b, --bigint                          Compatible bigint (default: false)
  --verbose                             Show detailed information of each request
  --lang <language>                     Language setting (zh|en) (default: "en")
  -h, --help                            display help for command
```

### SSL

#### Client Certificates

Apidog CLI supports SSL client certificates

#### Using a single SSL client certificate

- `--ssl-client-cert`
  The path to the public client certificate file.

- `--ssl-client-key`
  The path to the private client key (optional).

- `--ssl-client-passphrase`
  The secret passphrase used to protect the private client key (optional).

#### Using SSL client certificates configuration file (supports multiple certificates per run)

- `--ssl-client-cert-list`
  The path to the SSL client certificate list configuration file (JSON format). See `ssl-client-cert-list.json`

```
ssl-client-cert-list.json

[
    {
        "name": "domain1",
        "matches": ["https://test.domain1.com/*", "https://www.domain1/*"],
        "key": {"src": "./client.domain1.key"},
        "cert": {"src": "./client.domain1.crt"},
        "passphrase": "changeme"
    },
    {
        "name": "domain2",
        "matches": ["https://domain2.com/*"],
        "key": {"src": "./client.domain2.key"},
        "cert": {"src": "./client.domain2.crt"},
        "passphrase": "changeme"
    }
]
```

This option allows setting different SSL client certificate according to URL or hostname. This option takes precedence over `--ssl-client-cert`, `--ssl-client-key` and `--ssl-client-passphrase` options. If there is no match for the URL in the list, these options are used as fallback.

## Update CLI

Upgrade Apidog CLI with the follow command

```console
$ npm install apidog-cli@latest -g
```

###