Apidog CLI Options

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.

Basic Apidog CLI Syntax

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.

Authentication

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.

CLI Schema

Use cli-schema to inspect and validate JSON files before creating or updating complex resources. This helps reduce request failures caused by malformed data.

Command	Description	Example
`cli-schema list`	List all schema keys supported by the CLI.	`apidog cli-schema list`
`cli-schema get`	Print the JSON Schema for a command data file.	`apidog cli-schema get endpoint-create`
`cli-schema validate`	Validate a local JSON file against a schema key.	`apidog cli-schema validate endpoint-create --file ./endpoint.json`

Schema keys usually combine the command path and action, such as endpoint-create, test-scenario-update, and merge-request-create.

Teams and Projects

Team and project commands are the starting point for managing resources through the CLI. Use them to find the IDs required by project-level commands.

Team Management

Command	Description	Example
`team list`	List teams accessible to the current account.	`apidog team list`
`team get`	View details of a specific team.	`apidog team get <teamId>`

Project Management

Command	Description	Example
`project list`	List projects accessible to the current account.	`apidog project list`
`project get`	View project details.	`apidog project get <projectId>`
`project create`	Create a project under a team.	`apidog project create --team <teamId> --name "New Project"`

Project Settings

Command	Description	Example
`project settings get`	View project-level settings.	`apidog project settings get --project <projectId>`
`project settings update`	Update project settings with a JSON file.	`apidog project settings update --project <projectId> --file ./project-settings.json`
`cli-schema get project-settings-update`	View the schema for project settings updates.	`apidog cli-schema get project-settings-update`

Environments and Variables

Use these commands to manage runtime environments, global variables, and team variables used by API debugging and automated tests.

Environment Management

Command	Description	Example
`environment list`	List environments in a project.	`apidog environment list --project <projectId>`
`environment get`	View environment details, such as base URLs.	`apidog environment get <environmentId> --project <projectId>`
`environment create`	Create an environment.	`apidog environment create <name> --project <projectId> --base-url <url>`
`environment update`	Update an environment.	`apidog environment update <environmentId> --project <projectId> --file ./environment.json`
`environment delete`	Delete an environment.	`apidog environment delete <environmentId> --project <projectId>`
`cli-schema get environment-update`	View the schema for environment updates.	`apidog cli-schema get environment-update`

Variable Management

Command	Description	Example
`variables list`	List variables by scope.	`apidog variables list --project <projectId> --scope global`
`variables get`	View the value of a variable.	`apidog variables get --project <projectId> --scope global --key <key>`
`variables set`	Create or update a variable.	`apidog variables set --project <projectId> --scope global --key <key> --value <value>`
`variables delete`	Delete a variable.	`apidog variables delete --project <projectId> --scope global --key <key>`
`variables import`	Import variables from a local file.	`apidog variables import --project <projectId> --scope global --file ./variables.json`
`variables export`	Export variables to a local file.	`apidog variables export --project <projectId> --scope global --output ./variables.json`

API Design Resources

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.

HTTP API Endpoints

Command	Description	Example
`endpoint list`	List HTTP API endpoints in a project.	`apidog endpoint list --project <projectId>`
`endpoint get`	View endpoint details.	`apidog endpoint get <endpointId> --project <projectId>`
`endpoint create`	Create an endpoint from a JSON file.	`apidog endpoint create --project <projectId> --file ./endpoint.json`
`endpoint update`	Update an endpoint.	`apidog endpoint update <endpointId> --project <projectId> --file ./endpoint.json`
`endpoint delete`	Delete an endpoint.	`apidog endpoint delete <endpointId> --project <projectId>`
`cli-schema get endpoint-create`	View the schema for endpoint creation.	`apidog cli-schema get endpoint-create`
`cli-schema get endpoint-update`	View the schema for endpoint updates.	`apidog cli-schema get endpoint-update`

Data Schemas

Command	Description	Example
`schema list`	List data schemas in a project.	`apidog schema list --project <projectId>`
`schema get`	View schema details.	`apidog schema get <schemaId> --project <projectId>`
`schema create`	Create a data schema from a JSON file.	`apidog schema create --project <projectId> --file ./schema.json`
`schema update`	Update a data schema.	`apidog schema update <schemaId> --project <projectId> --file ./schema.json`
`schema delete`	Delete a data schema.	`apidog schema delete <schemaId> --project <projectId>`
`cli-schema get schema-create`	View the schema for data schema creation.	`apidog cli-schema get schema-create`
`cli-schema get schema-update`	View the schema for data schema updates.	`apidog cli-schema get schema-update`

Markdown Documents

Command	Description	Example
`doc list`	List Markdown documents.	`apidog doc list --project <projectId>`
`doc get`	View Markdown document details.	`apidog doc get <docId> --project <projectId>`
`doc create`	Create a Markdown document.	`apidog doc create --project <projectId> --file ./doc.json`
`doc update`	Update a Markdown document.	`apidog doc update <docId> --project <projectId> --file ./doc.json`
`doc delete`	Delete a Markdown document.	`apidog doc delete <docId> --project <projectId>`

Resource Folders

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"`
`folder move`	Move a folder to another parent folder.	`apidog folder move <folderId> --project <projectId> --type endpoint --parent <parentId>`
`folder update`	Update folder name, description, or parent.	`apidog folder update <folderId> --project <projectId> --type endpoint --name "New Folder Name"`
`folder delete`	Delete a folder.	`apidog folder delete <folderId> --project <projectId> --type endpoint`
`cli-schema get folder-create`	View the schema for folder creation.	`apidog cli-schema get folder-create`
`cli-schema get folder-update`	View the schema for folder updates.	`apidog cli-schema get folder-update`

--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.

Mock Rules

Command	Description	Example
`mock list`	List mock rules in a project or under an endpoint.	`apidog mock list --project <projectId> --http-api-id <endpointId>`
`mock get`	View a mock rule.	`apidog mock get <mockId> --project <projectId>`
`mock create`	Create a mock rule from a JSON file.	`apidog mock create --project <projectId> --file ./mock.json`
`mock update`	Update a mock rule.	`apidog mock update <mockId> --project <projectId> --file ./mock.json`
`mock delete`	Delete a mock rule.	`apidog mock delete <mockId> --project <projectId>`
`cli-schema get mock-create`	View the schema for mock rule creation.	`apidog cli-schema get mock-create`
`cli-schema get mock-update`	View the schema for mock rule updates.	`apidog cli-schema get mock-update`

Common Parameters

Command	Description	Example
`common-parameter list`	List reusable common parameters.	`apidog common-parameter list --project <projectId>`
`common-parameter get`	View common parameter details.	`apidog common-parameter get <commonParameterId> --project <projectId>`
`common-parameter create`	Create a common parameter from a JSON file.	`apidog common-parameter create --project <projectId> --file ./common-parameter.json`
`common-parameter update`	Update a common parameter.	`apidog common-parameter update <commonParameterId> --project <projectId> --file ./common-parameter.json`
`common-parameter import`	Import common parameters from a file.	`apidog common-parameter import --project <projectId> --file ./common-parameters.json`
`common-parameter export`	Export common parameters to a local file.	`apidog common-parameter export --project <projectId> --output ./common-parameters.json`

Response Components

Command	Description	Example
`response-component list`	List reusable response components.	`apidog response-component list --project <projectId>`
`response-component get`	View response component details.	`apidog response-component get <responseComponentId> --project <projectId>`
`response-component create`	Create a response component from a JSON file.	`apidog response-component create --project <projectId> --file ./response-component.json`
`response-component update`	Update a response component.	`apidog response-component update <responseComponentId> --project <projectId> --file ./response-component.json`
`response-component delete`	Delete a response component.	`apidog response-component delete <responseComponentId> --project <projectId>`

Security Schemes

Command	Description	Example
`security-scheme list`	List security schemes in a project.	`apidog security-scheme list --project <projectId>`
`security-scheme get`	View security scheme details.	`apidog security-scheme get <schemeId> --project <projectId>`
`security-scheme create`	Create a security scheme from a JSON file.	`apidog security-scheme create --project <projectId> --file ./scheme.json`
`security-scheme update`	Update a security scheme.	`apidog security-scheme update <schemeId> --project <projectId> --file ./scheme.json`
`security-scheme delete`	Delete a security scheme.	`apidog security-scheme delete <schemeId> --project <projectId>`

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.

Automated Testing

Use these commands to manage API test cases, test scenarios, test suites, test data, test reports, runners, and scheduled tasks.

API Test Cases

Command	Description	Example
`test-case list`	List API test cases, optionally filtered by endpoint.	`apidog test-case list --project <projectId> --endpoint <endpointId>`
`test-case category`	List test case categories.	`apidog test-case category --project <projectId>`
`test-case get`	View API test case details.	`apidog test-case get <caseId> --project <projectId>`
`test-case create`	Create an API test case from a JSON file.	`apidog test-case create --project <projectId> --file ./case.json`
`test-case update`	Update an API test case.	`apidog test-case update <caseId> --project <projectId> --file ./case.json`
`test-case delete`	Delete an API test case.	`apidog test-case delete <caseId> --project <projectId>`
`cli-schema get test-case-create`	View the schema for test case creation.	`apidog cli-schema get test-case-create`
`cli-schema get test-case-update`	View the schema for test case updates.	`apidog cli-schema get test-case-update`

Test Scenarios

Command	Description	Example
`test-scenario list`	List test scenarios in a project.	`apidog test-scenario list --project <projectId>`
`test-scenario get`	View test scenario details.	`apidog test-scenario get <scenarioId> --project <projectId>`
`test-scenario create`	Create a test scenario.	`apidog test-scenario create --project <projectId> --file ./scenario.json`
`test-scenario update`	Update a test scenario.	`apidog test-scenario update <scenarioId> --project <projectId> --file ./scenario.json`
`test-scenario delete`	Delete a test scenario.	`apidog test-scenario delete <scenarioId> --project <projectId>`
`test-scenario run`	Run a test scenario.	`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`

Test Suites

Command	Description	Example
`test-suite list`	List test suites in a project.	`apidog test-suite list --project <projectId>`
`test-suite get`	View test suite details.	`apidog test-suite get <testSuiteId> --project <projectId>`
`test-suite create`	Create a test suite.	`apidog test-suite create --project <projectId> --file ./suite.json`
`test-suite update`	Update a test suite.	`apidog test-suite update <testSuiteId> --project <projectId> --file ./suite.json`
`test-suite delete`	Delete a test suite.	`apidog test-suite delete <testSuiteId> --project <projectId>`
`test-suite run`	Run a test suite.	`apidog test-suite run <testSuiteId> --project <projectId> --environment <environmentId>`

Test Data

Command	Description	Example
`test-data list`	List test data sets.	`apidog test-data list --project <projectId>`
`test-data get`	View test data set details.	`apidog test-data get <dataId> --project <projectId>`
`test-data create`	Create a test data set from a JSON file.	`apidog test-data create --project <projectId> --file ./test-data.json`
`test-data update`	Update a test data set.	`apidog test-data update <dataId> --project <projectId> --file ./test-data.json`
`test-data delete`	Delete a test data set.	`apidog test-data delete <dataId> --project <projectId>`

Test Reports

Command	Description	Example
`test-report list`	List test reports in a project.	`apidog test-report list --project <projectId>`
`test-report get`	View test report details.	`apidog test-report get <reportId> --project <projectId>`
`test-report download`	Download a test report to a local file.	`apidog test-report download <reportId> --project <projectId> --format json --output ./report.json`
`test-report delete`	Delete a test report.	`apidog test-report delete <reportId> --project <projectId>`

Runners

Command	Description	Example
`runner list`	List runners in a project or team.	`apidog runner list --project <projectId>`
`runner get`	View runner details.	`apidog runner get <runnerId> --project <projectId>`
`runner create`	Create a team runner.	`apidog runner create --team <teamId> --name <name> --runner-type <runnerType> --server-type <serverType>`
`runner check`	Check runner health.	`apidog runner check <runnerId> --team <teamId>`
`runner delete`	Delete a runner.	`apidog runner delete <runnerId> --project <projectId>`

Scheduled Tasks

Command	Description	Example
`scheduled-task list`	List scheduled tasks in a project.	`apidog scheduled-task list --project <projectId>`
`scheduled-task get`	View scheduled task details.	`apidog scheduled-task get <taskId> --project <projectId>`
`scheduled-task create`	Create a scheduled task from a JSON file.	`apidog scheduled-task create --project <projectId> --file ./scheduled-task.json`
`scheduled-task update`	Update a scheduled task.	`apidog scheduled-task update <taskId> --project <projectId> --file ./scheduled-task.json`
`scheduled-task delete`	Delete a scheduled task.	`apidog scheduled-task delete <taskId> --project <projectId>`
`scheduled-task run`	Trigger a scheduled task manually.	`apidog scheduled-task run <taskId> --project <projectId>`

Core Run Command: `apidog run`

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.

Online Execution

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:

Local Execution

When running offline tests using exported files, use the following command.

Specify the URL or file path of the Apidog test scenario. For example:

Run Options

Option	Description
`--access-token <accessToken>`	Set authentication token for online execution
`-t, --test-scenario <testScenarioId>`	Specify test scenario ID to run
`-f, --test-scenario-folder <folderId>`	Specify test scenario directory ID to run
`--test-suite <testSuiteId>`	Specify test suite ID to run
`--project <projectId>`	Specify project ID
`--branch <branchName>`	Specify the branch name; if omitted, the server defaults to the main branch
`-r, --reporters [reporters]`	Specify test report types (default: `["cli"]`)
`--out-dir <outDir>`	Output directory for test reports (default: `./apidog-reports`)
`--out-file <outFile>`	Output test report file name with no need to add a file extension. You can use `{FOLDER_NAME}`, `{SCENARIO_NAME}`, and `{GENERATE_TIME}`
`--out-json-failures-separated <outJsonFailuresSeparated>`	Export failures as separate JSON file
`-e, --environment <environmentId>`	Specify runtime environment
`-n, --iteration-count <n>`	Set number of iterations
`-d, --iteration-data <path>`	Set data for case iterations (JSON or CSV)
`--on-error <behavior>`	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>.

Import and Export

Use import and export commands to bring external API documents into Apidog or export project data to formats used by other tools.

Import Project Data

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.

Command	Description	Example
`import`	Import a local file into a project by format.	`apidog import --project <projectId> --format openapi --file ./openapi.json`

Auto Import Settings

Use import auto-import to maintain auto import settings for long-term synchronization from external sources.

Command	Description	Example
`import auto-import list`	List auto import settings in a project.	`apidog import auto-import list --project <projectId>`
`import auto-import create`	Create an auto import setting.	`apidog import auto-import create --project <projectId> --file ./auto-import.json`
`import auto-import get`	View an auto import setting.	`apidog import auto-import get <settingId> --project <projectId>`
`import auto-import delete`	Delete an auto import setting.	`apidog import auto-import delete <settingId> --project <projectId>`
`cli-schema get import-auto-import-create`	View the schema for auto import settings.	`apidog cli-schema get import-auto-import-create`

Export Project Data

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.

Command	Description	Example
`export`	Export project data by format.	`apidog export --project <projectId> --format openapi --output ./openapi.json`
`export --format apidog`	Export native project data.	`apidog export --project <projectId> --format apidog --output ./project.apidog.json`
`export --scope apis`	Export selected APIs in native format.	`apidog export --project <projectId> --format apidog --scope apis --api-ids 1001,1002 --output ./selected.apidog.json`
`export --scope tags`	Export APIs by tags in native format.	`apidog export --project <projectId> --format apidog --scope tags --include-tags pet,store --output ./tagged.apidog.json`
`export --format openapi --scope folders`	Export selected folders in OpenAPI format.	`apidog export --project <projectId> --format openapi --scope folders --folder-ids 2001 --output ./openapi.json`

OAS Export Settings

Use export settings to maintain reusable OAS export settings.

Command	Description	Example
`export settings list`	List OAS export settings.	`apidog export settings list --project <projectId>`
`export settings create`	Create an OAS export setting.	`apidog export settings create --project <projectId> --file ./export-setting.json`
`export settings get`	View an OAS export setting.	`apidog export settings get <settingId> --project <projectId>`
`export settings update`	Update an OAS export setting.	`apidog export settings update <settingId> --project <projectId> --file ./export-setting.json`
`export settings delete`	Delete an OAS export setting.	`apidog export settings delete <settingId> --project <projectId>`
`cli-schema get export-settings-create`	View the schema for OAS export setting creation.	`apidog cli-schema get export-settings-create`
`cli-schema get export-settings-update`	View the schema for OAS export setting updates.	`apidog cli-schema get export-settings-update`

Use these commands to publish and share API documentation.

Documentation Sites

Command	Description	Example
`docs-site list`	List documentation sites.	`apidog docs-site list --project <projectId>`
`docs-site get`	View documentation site details.	`apidog docs-site get <siteId> --project <projectId>`
`docs-site create`	Create a documentation site.	`apidog docs-site create --project <projectId> --file ./docs-site.json`
`docs-site update`	Update documentation site settings.	`apidog docs-site update <siteId> --project <projectId> --file ./docs-site.json`
`docs-site delete`	Delete a documentation site.	`apidog docs-site delete <siteId> --project <projectId>`

Shared Documents

Command	Description	Example
`shared-doc list`	List shared documents.	`apidog shared-doc list --project <projectId>`
`shared-doc get`	View shared document details.	`apidog shared-doc get <docId> --project <projectId>`
`shared-doc create`	Create a shared document.	`apidog shared-doc create --project <projectId> --file ./shared-doc.json`
`shared-doc update`	Update shared document settings.	`apidog shared-doc update <docId> --project <projectId> --file ./shared-doc.json`
`shared-doc delete`	Delete a shared document.	`apidog shared-doc delete <docId> --project <projectId>`

Branch Management

Use branch commands to isolate changes, collaborate on project resources, and merge selected resources between branches.

Iteration Branches

Command	Description	Example
`branch list --type all`	List all branch types in a project.	`apidog branch list --project <projectId> --type all`
`branch list --type sprint`	List iteration branches.	`apidog branch list --project <projectId> --type sprint`
`branch get --type sprint`	View an iteration branch.	`apidog branch get <branchName> --project <projectId> --type sprint`
`branch create --type sprint`	Create an iteration branch.	`apidog branch create --project <projectId> --type sprint --name <branchName> --from main`
`branch update --type sprint`	Update an iteration branch.	`apidog branch update <branchName> --project <projectId> --type sprint --name <newName>`
`branch merge`	Merge explicitly selected resources from one branch to another.	`apidog branch merge --project <projectId> --from <sourceBranchName> --to <targetBranchName> --endpoint-ids <ids>`
`branch pick-to`	Pick selected resources from a source branch to a target branch.	`apidog branch pick-to --project <projectId> --from <sourceBranchName> --to <targetBranchName> --endpoint-ids <ids>`
`branch archive --type sprint`	Archive an iteration branch before deletion.	`apidog branch archive <branchName> --project <projectId> --type sprint`
`branch delete --type sprint`	Delete an archived iteration branch.	`apidog branch delete <branchName> --project <projectId> --type sprint`

AI Branches

Command	Description	Example
`branch list --type ai`	List AI branches.	`apidog branch list --project <projectId> --type ai`
`branch get --type ai`	View an AI branch.	`apidog branch get <branchName> --project <projectId> --type ai`
`branch create --type ai`	Create an AI branch from a source branch.	`apidog branch create --project <projectId> --type ai --name <aiBranchName> --from <sourceBranchName>`
`branch update --type ai`	Update an AI branch.	`apidog branch update <branchName> --project <projectId> --type ai --name <newName>`
`branch archive --type ai`	Archive an AI branch before deletion.	`apidog branch archive <branchName> --project <projectId> --type ai`
`branch delete --type ai`	Delete an archived AI branch.	`apidog branch delete <branchName> --project <projectId> --type ai`

General Branches

Command	Description	Example
`branch list --type general`	List general branches.	`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.

Merge Requests

Use merge-request when the target branch requires a review flow. Merge requests and direct merges only merge explicitly selected resources.

Command	Description	Example
`merge-request preview`	Scan candidate changes before creating a merge request or direct merge.	`apidog merge-request preview --project <projectId> --from <sourceBranchName> --to <targetBranchName>`
`merge-request list`	List merge requests.	`apidog merge-request list --project <projectId> --to <targetBranchName>`
`merge-request get`	View merge request details.	`apidog merge-request get <mergeRequestId> --project <projectId> --to <targetBranchName>`
`merge-request create`	Create a merge request.	`apidog merge-request create --project <projectId> --to <targetBranchName> --from <sourceBranchName> --reviewer-ids <userIds> --endpoint-ids <ids>`
`merge-request update`	Update a merge request.	`apidog merge-request update <mergeRequestId> --project <projectId> --to <targetBranchName> --file ./merge-request.json`
`merge-request approve`	Approve a merge request.	`apidog merge-request approve <mergeRequestId> --project <projectId> --to <targetBranchName> --file ./approve.json`
`merge-request reject`	Reject a merge request.	`apidog merge-request reject <mergeRequestId> --project <projectId> --to <targetBranchName>`
`merge-request delete`	Delete a merge request.	`apidog merge-request delete <mergeRequestId> --project <projectId> --to <targetBranchName>`

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.

Other Resources

Use these commands to manage project extension resources and external connections.

Custom Fields

Command	Description	Example
`custom-field list`	List custom fields.	`apidog custom-field list --project <projectId>`
`custom-field create`	Create a custom field.	`apidog custom-field create --project <projectId> --file ./custom-field.json`
`custom-field update`	Update a custom field.	`apidog custom-field update <customFieldId> --project <projectId> --file ./custom-field.json`
`custom-field delete`	Delete a custom field.	`apidog custom-field delete <customFieldId> --project <projectId>`

WebSocket APIs

Command	Description	Example
`websocket list`	List WebSocket APIs.	`apidog websocket list --project <projectId>`
`websocket get`	View WebSocket API details.	`apidog websocket get <websocketId> --project <projectId>`
`websocket create`	Create a WebSocket API.	`apidog websocket create --project <projectId> --name <name> --url <url>`
`websocket update`	Update a WebSocket API.	`apidog websocket update <websocketId> --project <projectId> --file ./websocket.json`
`websocket delete`	Delete a WebSocket API.	`apidog websocket delete <websocketId> --project <projectId>`

Socket.IO APIs

Command	Description	Example
`socketio list`	List Socket.IO APIs.	`apidog socketio list --project <projectId>`
`socketio get`	View Socket.IO API details.	`apidog socketio get <socketioId> --project <projectId>`
`socketio create`	Create a Socket.IO API.	`apidog socketio create --project <projectId> --file ./socketio.json`
`socketio update`	Update a Socket.IO API.	`apidog socketio update <socketioId> --project <projectId> --file ./socketio.json`
`socketio delete`	Delete a Socket.IO API.	`apidog socketio delete <socketioId> --project <projectId>`

Common Scripts

Command	Description	Example
`common-script list`	List common scripts.	`apidog common-script list --project <projectId>`
`common-script get`	View common script details.	`apidog common-script get <scriptId> --project <projectId>`
`common-script create`	Create a common script.	`apidog common-script create --project <projectId> --file ./common-script.json`
`common-script update`	Update a common script.	`apidog common-script update <scriptId> --project <projectId> --file ./common-script.json`
`common-script delete`	Delete a common script.	`apidog common-script delete <scriptId> --project <projectId>`

Database Connections

Command	Description	Example
`database-connection list`	List database connections.	`apidog database-connection list --project <projectId>`
`database-connection get`	View database connection details.	`apidog database-connection get <connectionId> --project <projectId>`
`database-connection create`	Create a database connection.	`apidog database-connection create --project <projectId> --file ./database-connection.json`
`database-connection update`	Update a database connection.	`apidog database-connection update <connectionId> --project <projectId> --file ./database-connection.json`
`database-connection delete`	Delete a database connection.	`apidog database-connection delete <connectionId> --project <projectId>`

Vault Providers

Command	Description	Example
`vault list`	List vault providers.	`apidog vault list --project <projectId>`
`vault get`	View vault provider details.	`apidog vault get <vaultProviderId> --project <projectId>`
`vault create`	Create a vault provider.	`apidog vault create --project <projectId> --file ./vault.json`
`vault update`	Update a vault provider.	`apidog vault update <vaultProviderId> --project <projectId> --file ./vault.json`
`vault delete`	Delete a vault provider.	`apidog vault delete <vaultProviderId> --project <projectId>`

Git Connections

Command	Description	Example
`git-connection list`	List Git connections.	`apidog git-connection list --project <projectId>`
`git-connection get`	View Git connection details.	`apidog git-connection get <connectionId> --project <projectId>`
`git-connection create`	Create a Git connection.	`apidog git-connection create --project <projectId> --file ./git-connection.json`
`git-connection update`	Update a Git connection.	`apidog git-connection update <connectionId> --project <projectId> --file ./git-connection.json`
`git-connection delete`	Delete a Git connection.	`apidog git-connection delete <connectionId> --project <projectId>`

Management and Settings

Use these commands for project administration, notifications, recycle bin resources, change history, and audit logs.

Notifications

Command	Description	Example
`notification list`	List notification configurations.	`apidog notification list --project <projectId>`
`notification get`	View notification details.	`apidog notification get <notificationId> --project <projectId>`
`notification create`	Create a notification configuration.	`apidog notification create --project <projectId> --file ./notification.json`
`notification update`	Update a notification configuration.	`apidog notification update <notificationId> --project <projectId> --file ./notification.json`
`notification delete`	Delete a notification configuration.	`apidog notification delete <notificationId> --project <projectId>`

Recycle Bin

Command	Description	Example
`recycle list`	List resources in the recycle bin.	`apidog recycle list --project <projectId>`
`recycle restore`	Restore a resource from the recycle bin.	`apidog recycle restore <itemId> --project <projectId>`
`recycle delete`	Permanently delete a recycle bin resource.	`apidog recycle delete <itemId> --project <projectId>`

History

Command	Description	Example
`history list`	List project change history.	`apidog history list --project <projectId>`
`history get`	View change history details.	`apidog history get <historyId> --project <projectId>`

Audit Logs

Command	Description	Example
`audit-log list`	List project audit logs.	`apidog audit-log list --project <projectId>`
`audit-log get`	View audit log details.	`apidog audit-log get <auditLogId> --project <projectId>`

Advanced Usage

Uploading Files in CLI

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.

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.

In Apidog, navigate to your test scenario and locate the step that requires file upload. Click on Bulk Edit button as shown below.

Batch Edit button in test scenario step details

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.

File path configuration in batch edit mode

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.

Using Database Operations in CLI

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:

For test scenarios that include database operations, you'll see a prompt in the command line generation interface: "Download the database configuration file."

Download this file and place it in the directory where you plan to run the Apidog CLI.

The automatically generated command line will include the --database-connection option. You can use this command line as is to run your tests.

Uploading Local CLI Test Reports to the Cloud

To upload your local CLI test reports to the cloud, you can add the --upload-report parameter at the end of your CLI command. Here's how to do it:

Add the --upload-report parameter to your CLI command:

This command will run your tests and automatically upload the test report to the cloud after completion.

To view the uploaded report:

Go to the "Test Reports" section in your Apidog dashboard.

Look for the "Team Reports" column.

Note: For reports uploaded via CLI, the "Tester" field will be displayed as empty.

Using External Scripts/Programs in CLI

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:

1. Local Path

To avoid confusion in managing local scripts, it's recommended to:

Organize all script files by category

Place them in a specific directory

Specify the corresponding local path in the CLI command

2. Cloud Code Repository

Alternatively, you can:

Host script files in a cloud-based code repository

Set up pull commands in your CI/CD workflow to fetch external scripts to the local environment

Specify the actual path of the external scripts in the CLI 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

[
    {
        "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.

HTTP/2

The CLI can be configured to use specific protocol versions for sending requests by using the --preferred-http-version parameter.

Protocol version parameter values:

"HTTP/2" - HTTP/2 Application-Layer Protocol Negotiation (ALPN), supported only for HTTPS requests.

"HTTP/2-with-prior-knowledge" - HTTP/2 with prior knowledge.

"HTTP/1" - HTTP/1.1.

The parameter supports the following configurations:

Setting different protocol versions for HTTPS and HTTP requests:

Setting the same protocol version for both HTTPS and HTTP:

Setting HTTP/2 for both HTTPS and HTTP (unsupported values will be automatically ignored):

FAQ

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.

Basic Apidog CLI Syntax#

Authentication#

CLI Schema#

Teams and Projects#

Team Management#

Project Management#

Project Settings#

Environments and Variables#

Environment Management#

Variable Management#

API Design Resources#

HTTP API Endpoints#

Data Schemas#

Markdown Documents#

Resource Folders#

Mock Rules#

Common Parameters#

Response Components#

Security Schemes#

Automated Testing#

API Test Cases#

Test Scenarios#

Test Suites#

Test Data#

Test Reports#

Runners#

Scheduled Tasks#

Core Run Command: apidog run#

Online Execution#

Local Execution#

Run Options#

Import and Export#

Import Project Data#

Auto Import Settings#

Export Project Data#

OAS Export Settings#

Documentation Sharing#

Documentation Sites#

Shared Documents#

Branch Management#

Iteration Branches#

AI Branches#

General Branches#

Merge Requests#

Other Resources#

Custom Fields#

WebSocket APIs#

Socket.IO APIs#

Common Scripts#

Database Connections#

Vault Providers#

Git Connections#

Management and Settings#

Notifications#

Recycle Bin#

History#

Audit Logs#

Advanced Usage#

Uploading Files in CLI#

Using Database Operations in CLI#

Uploading Local CLI Test Reports to the Cloud#

Using External Scripts/Programs in CLI#

1. Local Path#

2. Cloud Code Repository#

SSL#

Client Certificate#

Using Single SSL Client Certificate#

Using SSL Client Certificates Configuration File (Supports Multiple Certificates)#

HTTP/2#

FAQ#

Basic Apidog CLI Syntax

Authentication

CLI Schema

Teams and Projects

Team Management

Project Management

Project Settings

Environments and Variables

Environment Management

Variable Management

API Design Resources

HTTP API Endpoints

Data Schemas

Markdown Documents

Resource Folders

Mock Rules

Common Parameters

Response Components

Security Schemes

Automated Testing

API Test Cases

Test Scenarios

Test Suites

Test Data

Test Reports

Runners

Scheduled Tasks

Core Run Command: `apidog run`

Online Execution

Local Execution

Run Options

Import and Export

Import Project Data

Auto Import Settings

Export Project Data

OAS Export Settings

Documentation Sharing

Documentation Sites

Shared Documents

Branch Management

Iteration Branches

AI Branches

General Branches

Merge Requests

Other Resources

Custom Fields

WebSocket APIs

Socket.IO APIs

Common Scripts

Database Connections

Vault Providers

Git Connections

Management and Settings

Notifications

Recycle Bin

History

Audit Logs

Advanced Usage

Uploading Files in CLI

Using Database Operations in CLI

Uploading Local CLI Test Reports to the Cloud

Using External Scripts/Programs in CLI

1. Local Path

2. Cloud Code Repository

SSL

Client Certificate

Using Single SSL Client Certificate

Using SSL Client Certificates Configuration File (Supports Multiple Certificates)

HTTP/2

FAQ