Skip to main content

Apidog CLI

Apidog CLI is mainly designed to run Apidog test cases in the command line. It is used for automation testing.

Command Options​

Install CLI​

The Apidog CLI relies on Node.js version number >= v10. Please install Node.js before using it.

sudo npm install -g apidog-cli

Command-line Options​

Command Parameters​

  • apidog [options]
  • -h, --help

View help information.

  • -v, --version

Show Apidog version.

  • apidog run <file-source> [options]

file-source needs to be the path for test cases files exported from Apidog.

More Options​

  -r, --reporters [reporters]                               Specify test report file extension, support cli, html, json (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
  --out-json-failures-separated <outJsonFailuresSeparated>  When generating a JSON report for test results, export the details of failures to a separate JSON file
  -n, --iteration-count <n>                                 Define the number of iterations to run
  -d, --iteration-data <path>                               Define the data which use for iterations (either JSON or CSV)
  --global-var <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" 
  --env-var <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"
  --external-program-path <path>                            Specify the file path of external program, by default is current directory
  --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)
  -b, --bigint                                              Compatible bigint (default: false)
  --verbose                                                 Show detailed information of each request
  -h, --help                                                display help for command

SSL​

Client Certificate​

Apidog CLI supports passing in client certificates.

Using Single SSL Client Certificate​

  • --ssl-client-cert Specify the path of the public SSL client certificate.

  • --ssl-client-key Specify the path of the private SSL client certificate (optional).

  • --ssl-client-passphrase Specify SSL client passphrase (optional).

Using SSL Client Certificates Configuration File (supports multiple certificates)​

  • --ssl-client-cert-list Specify the path of the JSON file of the SSL client certificate list. For example:ssl-client-cert-list.json
ssl-client-cert-list.json

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

This option supports setting different SSL client certificates based on URL or hostname. It takes precedence over the --ssl-client-cert, --ssl-client-key, and --ssl-client-passphrase options. These options will be used as fallback options if there is no match for the URL in the list.

Version Upgrade​

CLI Use the command below to upgrade the Apidog version.

$ npm install apidog-cli@latest -g

Use the CLI​

There are two usage scenarios of Apidog CLI, please click the title to view the details:

  1. Run online data in real time
  2. Run a test file that has been exported locally

FAQs​

How to Fix the Error when Using CLI?​

  • Invalid character in header content["Authorization"]

Getting Invalid character in header content error after running Apidog CLI command in terminal:

To make sure there are no abnormalities when running automated tests in Apidog client/web, please check whether remote values are set in environment.

How to Pass File Parameters Using CLI?​

  1. First, go back to the request parameters in the "APIs" → "Edit" → "Bulk Edit". Change the path of the uploaded file to a variable by batch editing.

  1. After saving as an API use case, import API Cases in Testing.

  2. Finally, when running in the corresponding application (such as jenkins), modify the actual value of this path variable.

How to Upload Local CLI Test Reports to The Cloud?​

Add the --upload-report parameter at the end of the CLI command line, for example:

apidog run https://api.apidog.com/api/v1/projects/2689726/api-test/ci-config/364654/detail\?token\=******* -r html,cli --upload-report

View it in the "Team Report" section under "Test Reports". The tester field of the test reports uploaded by CLI will be left blank.

How to Reference External Scripts/Programs in The CLI?​

You can specify the path of an external script or program to be referenced at the end of the Apidog CLI command. For example, in the following command line, specify that the CLI references a program located at ./scripts path. If layer levels are not specified, the default is the current CLI execution directory.

--external-program-path ./scripts
  1. Local path

To avoid management chaos of local scripts, it is recommended to organize all script files systematically under a specific directory and specify the corresponding local path in the CLI.

  1. Cloud code repository

You can also host the script files in a cloud-based code repository, then set up a CI/CD workflow to pull the external scripts locally. Finally, specify the actual path of the external script in the CLI.