Apidog CLI is used to run automated tests and manage Apidog project resources from a terminal or CI/CD pipeline. It supports test execution, API design resource management, environments and variables, import and export, documentation publishing, branch collaboration, and project administration.
Most project resource commands use --project <projectId> to specify the project. You can use --branch <branchName> to operate on a specific branch. If --branch is omitted, the server uses the default branch.
Before accessing private projects, log in or provide an access token.
Command
Description
Example
login
Log in with an access token and save it locally.
apidog login --with-token <token>
logout
Log out and clear the saved local token.
apidog logout
whoami
Show information about the current authenticated user.
apidog whoami
You can also pass a token directly when running commands:
If you're using GitHub Actions, you can store your access token under your repository's Settings --> Secrets and Variables --> Actions --> Repository variables. Then use ${{ vars.APIDOG_ACCESS_TOKEN }} to reference it.
Use cli-schema to inspect and validate JSON files before creating or updating complex resources. This helps reduce request failures caused by malformed data.
Use these commands to manage API design resources, including HTTP API endpoints, schemas, folders, mock rules, common parameters, response components, and security schemes. When creating or updating complex resources, it is recommended to run cli-schema get <schemaKey> and cli-schema validate <schemaKey> --file <path> first.
Use folder commands to manage folder trees for different resource types. The --type option selects the resource type, such as endpoint, schema, test-scenario, response-component, security-scheme, test-suite, or test-data.
Command
Description
Example
folder list
List folders by resource type.
apidog folder list --project <projectId> --type endpoint
folder create
Create a folder by resource type.
apidog folder create --project <projectId> --type endpoint --name "New Folder"
--type selects the resource folder type. It is not the folder name. The description field is supported only for endpoint and test-scenario folders; other folder types support name and parent updates only.
API paths are API resource paths, not local file paths. If your shell rewrites values that start with /, wrap the path in quotes, for example --path '/api/users', or use --file to provide endpoint data.For API test cases or test scenario HTTP steps, responseId should use an endpoint response definition ID from endpoint.responses[].id, not a response component ID. To reuse a response component, link it in the endpoint response definition first.
apidog test-scenario run <scenarioId> --project <projectId> --environment <environmentId>
cli-schema get test-scenario-create
View the schema for test scenario creation.
apidog cli-schema get test-scenario-create
cli-schema get test-scenario-update
View the schema for test scenario updates.
apidog cli-schema get test-scenario-update
When creating or updating scenario case data with the CLI, scenario cases can reference endpoints, API test cases, and other test scenarios. Use cli-schema get test-scenario-create or cli-schema get test-scenario-update to confirm the required reference fields before preparing the JSON file.
This is the main command for running test scenarios, test scenario folders, test suites, or local exported files. You can copy generated commands from the Apidog client CI/CD panel and run them in your terminal or CI/CD workflow.
When running real-time tests through the Apidog server, use the following command.
Use the Apidog access token along with the ID of a specific test scenario, test scenario directory, or test suite. For example:
The Apidog CLI package is the same for all regions. If your test scenario or test suite was created in Apidog Europe, specify the EU API base URL with --api-base-url:
Set error handling behavior (ignore, continue, or end)
--variables <path>
Load environment or global variables from a local file
--global-var <value>
Set global variables (key=value format)
--env-var <value>
Set environment variables (key=value format)
--notification <ids>
Send notifications after the run finishes
--notification-failed-event <ids>
Send notifications only when the run fails
--external-program-path <path>
Specify file path for external programs
--database-connection <path>
Specify file path for database configuration
--ignore-redirects
Prevent automatic redirects
--silent
Prevent console output
--color <value>
Enable or disable colored console output
--delay-request [n]
Specify delay between requests (ms)
--timeout-request [n]
Specify request timeout (ms)
--timeout-script [n]
Specify script execution timeout (ms)
-k, --insecure
Disable SSL verification
--ssl-client-cert-list <path>
Specify client certificate config path
--ssl-client-cert <path>
Specify client certificate path (PEM)
--ssl-client-key <path>
Specify client certificate private key path
--ssl-client-passphrase <passphrase>
Specify client certificate passphrase
--ssl-extra-ca-certs <path>
Specify additional trusted CA certificates
-b, --bigint
Enable bigint compatibility
--upload-report [value]
Upload test report overview to cloud
--preferred-http-version <preferredHttpVersion>
Set preferred HTTP protocol version
--verbose
Display detailed request and response information
--lang <language>
Set CLI language (en)
-h, --help
Display help information
When creating or updating complex test resources such as test scenarios, test suites, test cases, test data, or scheduled tasks, use cli-schema get <schemaKey> first, then validate your local file with cli-schema validate <schemaKey> --file <path>.
The import command imports a local file into a project. Supported formats include openapi, postman, har, insomnia, jmeter, wsdl, yapi, rap2, apidoc, hoppscotch, markdown, jsonschema, and apidog.
The import command can also import data into project modules. The options below apply to module-aware converted imports:
Option
Description
Example
--module-import-mode <mode>
Module import mode: match-name matches existing modules by name (default, creates when unmatched); new creates all modules.
apidog import --project <projectId> --format apidog --file ./project.apidog.json --module-import-mode new
--module-map <mapping>
Module mapping, can be repeated: <source module name|source:sourceModuleId>=<targetModuleId|default|new>. The source module name is the converted module name (for OpenAPI, the spec info.title).
Converted imports (such as OpenAPI) name their module after the spec info.title. --module-map has higher priority than --module-import-mode; modules that are not explicitly mapped still follow the module import mode. To update an existing module in place, map info.title to the target module ID — otherwise, re-importing a file whose info.title has changed is treated as a new module.
The export command exports project data to a local file. Supported formats include openapi, markdown, html, postman, and apidog.For native apidog export, scope supports all, apis, and tags. Folder scope is available for OpenAPI export only.
apidog branch list --project <projectId> --type general
branch get --type general
View a general branch.
apidog branch get <branchName> --project <projectId> --type general
branch create --type general
Create a general branch.
apidog branch create --project <projectId> --type general --name <branchName> --from main
branch update --type general
Update a general branch.
apidog branch update <branchName> --project <projectId> --type general --name <newName>
branch delete --type general
Delete a general branch.
apidog branch delete <branchName> --project <projectId> --type general
Branch creation commands mainly use command-line options such as --type, --name, and --from. cli-schema get branch-*-create is used to inspect the create option structure. For the actual command options, run apidog branch create -h.
To keep project resources safe, CLI write permissions may be restricted by default. You can edit source branch data through an AI branch, or enable external editing permissions in project feature settings when direct editing is required for the main branch, standard iteration branches, or general branches. Changes made on an AI branch still need user confirmation before merge or merge-request.AI branch names are recommended to include the date, source branch, and purpose, for example ai/20260312-from-main-user-register.
For branch merge and pick operations, resource ID options use plural names and comma-separated numeric IDs, such as --endpoint-ids 1,2, --doc-ids 3,4, and --test-suite-ids 5,6.
When working with APIs that require file uploads, accurately setting the path of the file to be uploaded is crucial. You should store the file in the same machine where the tests run and reference it using either its absolute or relative path. Follow these steps to reference a file to upload.
1
Copy the required file to the machine running the CLI beforehand. For example, if you're using GitHub Actions as your CI/CD pipeline, copy the required file to the same GitHub repository to that of your workflow.
2
In Apidog, navigate to your test scenario and locate the step that requires file upload. Click on Bulk Edit button as shown below.
3
Copy the path of the file you copied to the CLI machine. Then replace the file field parameter value with the file path on the CLI machine. For example, if you put a png file under data folder in a GitHub repo, you can use data/to-be-uploaded.png to reference it.
After this configuration, the file can be correctly sent to Apidog through the CLI.
If you want to run this test scenario locally again, you'll need to modify the file path in the parameter value back to the path on your local machine.
When your test scenarios include database operations, you need to take a few extra steps because database configurations are saved locally, not in the cloud. This means you can't directly run the CLI in cloud mode for these scenarios. Here's how to handle this situation:
1
For test scenarios that include database operations, you'll see a prompt in the command line generation interface: "Download the database configuration file."
2
Download this file and place it in the directory where you plan to run the Apidog CLI.
3
The automatically generated command line will include the --database-connection option. You can use this command line as is to run your tests.
You can reference external scripts or programs when running the Apidog CLI by adding their path at the end of the command. Here's how to do it:
In this example, the CLI is instructed to reference programs located in the ./scripts directory. If no hierarchy is specified, the default is the current CLI execution directory.There are two main approaches to managing these external scripts:
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.
The CLI can be configured to use specific protocol versions for sending requests by using the --preferred-http-version parameter.Protocol version parameter values:
1.
"HTTP/2" - HTTP/2 Application-Layer Protocol Negotiation (ALPN), supported only for HTTPS requests.
2.
"HTTP/2-with-prior-knowledge" - HTTP/2 with prior knowledge.
3.
"HTTP/1" - HTTP/1.1.
The parameter supports the following configurations:
1.
Setting different protocol versions for HTTPS and HTTP requests:
2.
Setting the same protocol version for both HTTPS and HTTP:
3.
Setting HTTP/2 for both HTTPS and HTTP (unsupported values will be automatically ignored):
How to handle the error message Invalid character in header content['Authorization']?
This error is usually caused by invalid characters in the Authorization header, such as non-ASCII characters, line breaks, or extra spaces. If you're certain that running test scenarios in the Apidog client or web interface doesn't produce any errors, please check whether you've set INITIAL values for variables in your environment and confirm that the Authorization value matches the expected format.
How can I edit project data directly without using an AI branch?
Project write permissions may be restricted for safety. Check the project's feature settings and enable external editing permissions when direct editing is required.
