Apidog CLI 用於從終端機或 CI/CD 管線執行自動化測試並管理 Apidog 專案資源。它支援測試執行、API 設計資源管理、環境與變數、匯入與匯出、文件發布、分支協作，以及專案管理。基本 Apidog CLI 語法#
大多數專案資源命令會使用 --project <projectId> 來指定專案。你可以使用 --branch <branchName> 在特定分支上操作。如果省略 --branch，伺服器會使用預設分支。| 命令 | 說明 | 範例 |
|---|
login | 使用存取權杖登入並將其儲存在本機。 | apidog login --with-token <token> |
logout | 登出並清除已儲存的本機權杖。 | apidog logout |
whoami | 顯示目前已驗證使用者的資訊。 | apidog whoami |
如果你使用 GitHub Actions，可以將存取權杖儲存在儲存庫的 Settings --> Secrets and Variables --> Actions --> Repository variables 下。然後使用 ${{ vars.APIDOG_ACCESS_TOKEN }} 來參照它。
CLI Schema#
使用 cli-schema 在建立或更新複雜資源前檢查並驗證 JSON 檔案。這有助於減少因資料格式錯誤而造成的請求失敗。| 命令 | 說明 | 範例 |
|---|
cli-schema list | 列出 CLI 支援的所有 schema key。 | apidog cli-schema list |
cli-schema get | 印出命令資料檔案的 JSON Schema。 | apidog cli-schema get endpoint-create |
cli-schema validate | 依據 schema key 驗證本機 JSON 檔案。 | apidog cli-schema validate endpoint-create --file ./endpoint.json |
Schema key 通常會結合命令路徑與動作，例如 endpoint-create、test-scenario-update 和 merge-request-create。團隊與專案#
團隊與專案命令是透過 CLI 管理資源的起點。使用它們來尋找專案層級命令所需的 ID。團隊管理#
| 命令 | 說明 | 範例 |
|---|
team list | 列出目前帳號可存取的團隊。 | apidog team list |
team get | 檢視特定團隊的詳細資料。 | apidog team get <teamId> |
專案管理#
| 命令 | 說明 | 範例 |
|---|
project list | 列出目前帳號可存取的專案。 | apidog project list |
project get | 檢視專案詳細資料。 | apidog project get <projectId> |
project create | 在團隊下建立專案。 | apidog project create --team <teamId> --name "New Project" |
專案設定#
| 命令 | 說明 | 範例 |
|---|
project settings get | 檢視專案層級設定。 | apidog project settings get --project <projectId> |
project settings update | 使用 JSON 檔案更新專案設定。 | apidog project settings update --project <projectId> --file ./project-settings.json |
cli-schema get project-settings-update | 檢視專案設定更新的 schema。 | apidog cli-schema get project-settings-update |
環境與變數#
使用這些命令來管理 API 偵錯與自動化測試所使用的執行階段環境、全域變數與團隊變數。環境管理#
| 命令 | 說明 | 範例 |
|---|
environment list | 列出專案中的環境。 | apidog environment list --project <projectId> |
environment get | 檢視環境詳細資料，例如 base URL。 | apidog environment get <environmentId> --project <projectId> |
environment create | 建立環境。 | apidog environment create <name> --project <projectId> --base-url <url> |
environment update | 更新環境。 | apidog environment update <environmentId> --project <projectId> --file ./environment.json |
environment delete | 刪除環境。 | apidog environment delete <environmentId> --project <projectId> |
cli-schema get environment-update | 檢視環境更新的 schema。 | apidog cli-schema get environment-update |
變數管理#
| 命令 | 說明 | 範例 |
|---|
variables list | 依範圍列出變數。 | apidog variables list --project <projectId> --scope global |
variables get | 檢視變數的值。 | apidog variables get --project <projectId> --scope global --key <key> |
variables set | 建立或更新變數。 | apidog variables set --project <projectId> --scope global --key <key> --value <value> |
variables delete | 刪除變數。 | apidog variables delete --project <projectId> --scope global --key <key> |
variables import | 從本機檔案匯入變數。 | apidog variables import --project <projectId> --scope global --file ./variables.json |
variables export | 將變數匯出到本機檔案。 | apidog variables export --project <projectId> --scope global --output ./variables.json |
API 設計資源#
使用這些命令管理 API 設計資源，包括 HTTP API 端點、schema、資料夾、模擬規則、通用參數、回應元件與安全性方案。建立或更新複雜資源時，建議先執行 cli-schema get <schemaKey> 和 cli-schema validate <schemaKey> --file <path>。HTTP API 端點#
| 命令 | 說明 | 範例 |
|---|
endpoint list | 列出專案中的 HTTP API 端點。 | apidog endpoint list --project <projectId> |
endpoint get | 檢視端點詳細資料。 | apidog endpoint get <endpointId> --project <projectId> |
endpoint create | 從 JSON 檔案建立端點。 | apidog endpoint create --project <projectId> --file ./endpoint.json |
endpoint update | 更新端點。 | apidog endpoint update <endpointId> --project <projectId> --file ./endpoint.json |
endpoint delete | 刪除端點。 | apidog endpoint delete <endpointId> --project <projectId> |
cli-schema get endpoint-create | 檢視端點建立的 schema。 | apidog cli-schema get endpoint-create |
cli-schema get endpoint-update | 檢視端點更新的 schema。 | apidog cli-schema get endpoint-update |
資料 Schema#
| 命令 | 說明 | 範例 |
|---|
schema list | 列出專案中的資料 schema。 | apidog schema list --project <projectId> |
schema get | 檢視 schema 詳細資料。 | apidog schema get <schemaId> --project <projectId> |
schema create | 從 JSON 檔案建立資料 schema。 | apidog schema create --project <projectId> --file ./schema.json |
schema update | 更新資料 schema。 | apidog schema update <schemaId> --project <projectId> --file ./schema.json |
schema delete | 刪除資料 schema。 | apidog schema delete <schemaId> --project <projectId> |
cli-schema get schema-create | 檢視資料 schema 建立的 schema。 | apidog cli-schema get schema-create |
cli-schema get schema-update | 檢視資料 schema 更新的 schema。 | apidog cli-schema get schema-update |
Markdown 文件#
| 命令 | 說明 | 範例 |
|---|
doc list | 列出 Markdown 文件。 | apidog doc list --project <projectId> |
doc get | 檢視 Markdown 文件詳細資料。 | apidog doc get <docId> --project <projectId> |
doc create | 建立 Markdown 文件。 | apidog doc create --project <projectId> --file ./doc.json |
doc update | 更新 Markdown 文件。 | apidog doc update <docId> --project <projectId> --file ./doc.json |
doc delete | 刪除 Markdown 文件。 | apidog doc delete <docId> --project <projectId> |
資源資料夾#
使用 folder 命令管理不同資源類型的資料夾樹。--type 選項會選擇資源類型，例如 endpoint、schema、test-scenario、response-component、security-scheme、test-suite 或 test-data。| 命令 | 說明 | 範例 |
|---|
folder list | 依資源類型列出資料夾。 | apidog folder list --project <projectId> --type endpoint |
folder create | 依資源類型建立資料夾。 | apidog folder create --project <projectId> --type endpoint --name "New Folder" |
folder move | 將資料夾移至另一個父資料夾。 | apidog folder move <folderId> --project <projectId> --type endpoint --parent <parentId> |
folder update | 更新資料夾名稱、描述或父資料夾。 | apidog folder update <folderId> --project <projectId> --type endpoint --name "New Folder Name" |
folder delete | 刪除資料夾。 | apidog folder delete <folderId> --project <projectId> --type endpoint |
cli-schema get folder-create | 檢視資料夾建立的 schema。 | apidog cli-schema get folder-create |
cli-schema get folder-update | 檢視資料夾更新的 schema。 | apidog cli-schema get folder-update |
--type 會選擇資源資料夾類型。它不是資料夾名稱。description 欄位僅支援 endpoint 和 test-scenario 資料夾；其他資料夾類型僅支援名稱與父資料夾更新。
模擬規則#
| 命令 | 說明 | 範例 |
|---|
mock list | 列出專案中或端點下的模擬規則。 | apidog mock list --project <projectId> --http-api-id <endpointId> |
mock get | 檢視模擬規則。 | apidog mock get <mockId> --project <projectId> |
mock create | 從 JSON 檔案建立模擬規則。 | apidog mock create --project <projectId> --file ./mock.json |
mock update | 更新模擬規則。 | apidog mock update <mockId> --project <projectId> --file ./mock.json |
mock delete | 刪除模擬規則。 | apidog mock delete <mockId> --project <projectId> |
cli-schema get mock-create | 檢視模擬規則建立的 schema。 | apidog cli-schema get mock-create |
cli-schema get mock-update | 檢視模擬規則更新的 schema。 | apidog cli-schema get mock-update |
通用參數#
| 命令 | 說明 | 範例 |
|---|
common-parameter list | 列出可重複使用的通用參數。 | apidog common-parameter list --project <projectId> |
common-parameter get | 檢視通用參數詳細資料。 | apidog common-parameter get <commonParameterId> --project <projectId> |
common-parameter create | 從 JSON 檔案建立通用參數。 | apidog common-parameter create --project <projectId> --file ./common-parameter.json |
common-parameter update | 更新通用參數。 | apidog common-parameter update <commonParameterId> --project <projectId> --file ./common-parameter.json |
common-parameter import | 從檔案匯入通用參數。 | apidog common-parameter import --project <projectId> --file ./common-parameters.json |
common-parameter export | 將通用參數匯出到本機檔案。 | apidog common-parameter export --project <projectId> --output ./common-parameters.json |
回應元件#
| 命令 | 說明 | 範例 |
|---|
response-component list | 列出可重複使用的回應元件。 | apidog response-component list --project <projectId> |
response-component get | 檢視回應元件詳細資料。 | apidog response-component get <responseComponentId> --project <projectId> |
response-component create | 從 JSON 檔案建立回應元件。 | apidog response-component create --project <projectId> --file ./response-component.json |
response-component update | 更新回應元件。 | apidog response-component update <responseComponentId> --project <projectId> --file ./response-component.json |
response-component delete | 刪除回應元件。 | apidog response-component delete <responseComponentId> --project <projectId> |
安全性方案#
| 命令 | 說明 | 範例 |
|---|
security-scheme list | 列出專案中的安全性方案。 | apidog security-scheme list --project <projectId> |
security-scheme get | 檢視安全性方案詳細資料。 | apidog security-scheme get <schemeId> --project <projectId> |
security-scheme create | 從 JSON 檔案建立安全性方案。 | apidog security-scheme create --project <projectId> --file ./scheme.json |
security-scheme update | 更新安全性方案。 | apidog security-scheme update <schemeId> --project <projectId> --file ./scheme.json |
security-scheme delete | 刪除安全性方案。 | apidog security-scheme delete <schemeId> --project <projectId> |
API 路徑是 API 資源路徑，不是本機檔案路徑。如果你的 shell 會重寫以 / 開頭的值，請用引號包住路徑，例如 --path '/api/users'，或使用 --file 提供端點資料。對於 API 測試案例或測試情境 HTTP 步驟，responseId 應使用來自 endpoint.responses[].id 的端點回應定義 ID，而不是回應元件 ID。若要重複使用回應元件，請先在端點回應定義中連結它。
自動化測試#
使用這些命令管理 API 測試案例、測試情境、測試套件、測試資料、測試報告、runner 與排程任務。API 測試案例#
| 命令 | 說明 | 範例 |
|---|
test-case list | 列出 API 測試案例，可選擇依端點篩選。 | apidog test-case list --project <projectId> --endpoint <endpointId> |
test-case category | 列出測試案例分類。 | apidog test-case category --project <projectId> |
test-case get | 檢視 API 測試案例詳細資料。 | apidog test-case get <caseId> --project <projectId> |
test-case create | 從 JSON 檔案建立 API 測試案例。 | apidog test-case create --project <projectId> --file ./case.json |
test-case update | 更新 API 測試案例。 | apidog test-case update <caseId> --project <projectId> --file ./case.json |
test-case delete | 刪除 API 測試案例。 | apidog test-case delete <caseId> --project <projectId> |
cli-schema get test-case-create | 檢視測試案例建立的 schema。 | apidog cli-schema get test-case-create |
cli-schema get test-case-update | 檢視測試案例更新的 schema。 | apidog cli-schema get test-case-update |
測試情境#
| 命令 | 說明 | 範例 |
|---|
test-scenario list | 列出專案中的測試情境。 | apidog test-scenario list --project <projectId> |
test-scenario get | 檢視測試情境詳細資料。 | apidog test-scenario get <scenarioId> --project <projectId> |
test-scenario create | 建立測試情境。 | apidog test-scenario create --project <projectId> --file ./scenario.json |
test-scenario update | 更新測試情境。 | apidog test-scenario update <scenarioId> --project <projectId> --file ./scenario.json |
test-scenario delete | 刪除測試情境。 | apidog test-scenario delete <scenarioId> --project <projectId> |
test-scenario run | 執行測試情境。 | apidog test-scenario run <scenarioId> --project <projectId> --environment <environmentId> |
cli-schema get test-scenario-create | 檢視測試情境建立的 schema。 | apidog cli-schema get test-scenario-create |
cli-schema get test-scenario-update | 檢視測試情境更新的 schema。 | apidog cli-schema get test-scenario-update |
測試套件#
| 命令 | 說明 | 範例 |
|---|
test-suite list | 列出專案中的測試套件。 | apidog test-suite list --project <projectId> |
test-suite get | 檢視測試套件詳細資料。 | apidog test-suite get <testSuiteId> --project <projectId> |
test-suite create | 建立測試套件。 | apidog test-suite create --project <projectId> --file ./suite.json |
test-suite update | 更新測試套件。 | apidog test-suite update <testSuiteId> --project <projectId> --file ./suite.json |
test-suite delete | 刪除測試套件。 | apidog test-suite delete <testSuiteId> --project <projectId> |
test-suite run | 執行測試套件。 | apidog test-suite run <testSuiteId> --project <projectId> --environment <environmentId> |
測試資料#
| 命令 | 說明 | 範例 |
|---|
test-data list | 列出測試資料集。 | apidog test-data list --project <projectId> |
test-data get | 檢視測試資料集詳細資料。 | apidog test-data get <dataId> --project <projectId> |
test-data create | 從 JSON 檔案建立測試資料集。 | apidog test-data create --project <projectId> --file ./test-data.json |
test-data update | 更新測試資料集。 | apidog test-data update <dataId> --project <projectId> --file ./test-data.json |
test-data delete | 刪除測試資料集。 | apidog test-data delete <dataId> --project <projectId> |
測試報告#
| 命令 | 說明 | 範例 |
|---|
test-report list | 列出專案中的測試報告。 | apidog test-report list --project <projectId> |
test-report get | 檢視測試報告詳細資料。 | apidog test-report get <reportId> --project <projectId> |
test-report download | 將測試報告下載到本機檔案。 | apidog test-report download <reportId> --project <projectId> --format json --output ./report.json |
test-report delete | 刪除測試報告。 | apidog test-report delete <reportId> --project <projectId> |
Runners#
| 命令 | 說明 | 範例 |
|---|
runner list | 列出專案或團隊中的 runner。 | apidog runner list --project <projectId> |
runner get | 檢視 runner 詳細資料。 | apidog runner get <runnerId> --project <projectId> |
runner create | 建立團隊 runner。 | apidog runner create --team <teamId> --name <name> --runner-type <runnerType> --server-type <serverType> |
runner check | 檢查 runner 健康狀態。 | apidog runner check <runnerId> --team <teamId> |
runner delete | 刪除 runner。 | apidog runner delete <runnerId> --project <projectId> |
排程任務#
| 命令 | 說明 | 範例 |
|---|
scheduled-task list | 列出專案中的排程任務。 | apidog scheduled-task list --project <projectId> |
scheduled-task get | 檢視排程任務詳細資料。 | apidog scheduled-task get <taskId> --project <projectId> |
scheduled-task create | 從 JSON 檔案建立排程任務。 | apidog scheduled-task create --project <projectId> --file ./scheduled-task.json |
scheduled-task update | 更新排程任務。 | apidog scheduled-task update <taskId> --project <projectId> --file ./scheduled-task.json |
scheduled-task delete | 刪除排程任務。 | apidog scheduled-task delete <taskId> --project <projectId> |
scheduled-task run | 手動觸發排程任務。 | apidog scheduled-task run <taskId> --project <projectId> |
核心執行命令：apidog run#
這是用於執行測試情境、測試情境資料夾、測試套件或本機匯出檔案的主要命令。你可以從 Apidog 用戶端 CI/CD 面板複製產生的命令，並在終端機或 CI/CD 工作流程中執行。線上執行#
透過 Apidog 伺服器執行即時測試時，請使用下列命令。搭配 Apidog 存取權杖與特定測試情境、測試情境目錄或測試套件的 ID 使用。例如：本機執行#
指定 Apidog 測試情境的 URL 或檔案路徑。例如：執行選項#
| 選項 | 說明 |
|---|
--access-token <accessToken> | 設定線上執行的驗證權杖 |
-t, --test-scenario <testScenarioId> | 指定要執行的測試情境 ID |
-f, --test-scenario-folder <folderId> | 指定要執行的測試情境目錄 ID |
--test-suite <testSuiteId> | 指定要執行的測試套件 ID |
--project <projectId> | 指定專案 ID |
--branch <branchName> | 指定分支名稱；若省略，伺服器預設使用 main 分支 |
-r, --reporters [reporters] | 指定測試報告類型（預設：["cli"]） |
--out-dir <outDir> | 測試報告輸出目錄（預設：./apidog-reports） |
--out-file <outFile> | 測試報告輸出檔名，無需加上副檔名。你可以使用 {FOLDER_NAME}、{SCENARIO_NAME} 和 {GENERATE_TIME} |
--out-json-failures-separated <outJsonFailuresSeparated> | 將失敗項目匯出為獨立 JSON 檔案 |
-e, --environment <environmentId> | 指定執行階段環境 |
-n, --iteration-count <n> | 設定迭代次數 |
-d, --iteration-data <path> | 設定案 例迭代資料（JSON 或 CSV） |
--on-error <behavior> | 設定錯誤處理行為（ignore、continue 或 end） |
--variables <path> | 從本機檔案載入環境或全域變數 |
--global-var <value> | 設定全域變數（key=value 格式） |
--env-var <value> | 設定環境變數（key=value 格式） |
--notification <ids> | 執行完成後傳送通知 |
--notification-failed-event <ids> | 僅在執行失敗時傳送通知 |
--external-program-path <path> | 指定外部程式的檔案路徑 |
--database-connection <path> | 指定資料庫設定的檔案路徑 |
--ignore-redirects | 防止自動重新導向 |
--silent | 防止主控台輸出 |
--color <value> | 啟用或停用彩色主控台輸出 |
--delay-request [n] | 指定請求之間的延遲（ms） |
--timeout-request [n] | 指定請求逾時時間（ms） |
--timeout-script [n] | 指定指令碼執行逾時時間（ms） |
-k, --insecure | 停用 SSL 驗證 |
--ssl-client-cert-list <path> | 指定用戶端憑證設定路徑 |
--ssl-client-cert <path> | 指定用戶端憑證路徑（PEM） |
--ssl-client-key <path> | 指定用戶端憑證私鑰路徑 |
--ssl-client-passphrase <passphrase> | 指定用戶端憑證密碼片語 |
--ssl-extra-ca-certs <path> | 指定其他受信任的 CA 憑證 |
-b, --bigint | 啟用 bigint 相容性 |
--upload-report [value] | 將測試報告概覽上傳到雲端 |
--preferred-http-version <preferredHttpVersion> | 設定偏好的 HTTP 通訊協定版本 |
--verbose | 顯示詳細請求與回應資訊 |
--lang <language> | 設定 CLI 語言（en） |
-h, --help | 顯示說明資訊 |
建立或更新複雜測試資源（例如測試情境、測試套件、測試案例、測試資料或排程任務）時，請先使用 cli-schema get <schemaKey>，然後使用 cli-schema validate <schemaKey> --file <path> 驗證你的本機檔案。
匯入與匯出#
使用匯入與匯出命令，將外部 API 文件帶入 Apidog，或將專案資料匯出為其他工具使用的格式。匯入專案 資料#
import 命令會將本機檔案匯入專案。支援的格式包括 openapi、postman、har、insomnia、jmeter、wsdl、yapi、rap2、apidoc、hoppscotch、markdown、jsonschema 和 apidog。| 命令 | 說明 | 範例 |
|---|
import | 依格式將本機檔案匯入專案。 | apidog import --project <projectId> --format openapi --file ./openapi.json |
自動匯入設定#
使用 import auto-import 維護從外部來源長期同步的自動匯入設定。| 命令 | 說明 | 範例 |
|---|
import auto-import list | 列出專案中的自動匯入設定。 | apidog import auto-import list --project <projectId> |
import auto-import create | 建立自動匯入設定。 | apidog import auto-import create --project <projectId> --file ./auto-import.json |
import auto-import get | 檢視自動匯入設定。 | apidog import auto-import get <settingId> --project <projectId> |
import auto-import delete | 刪除自動匯入設定。 | apidog import auto-import delete <settingId> --project <projectId> |
cli-schema get import-auto-import-create | 檢視自動匯入設定的 schema。 | apidog cli-schema get import-auto-import-create |
匯出專案資料#
export 命令會將專案資料匯出到本機檔案。支援的格式包括 openapi、markdown、html、postman 和 apidog。對於原生 apidog 匯出，範圍支援 all、apis 和 tags。資料夾範圍僅適用於 OpenAPI 匯出。| 命令 | 說明 | 範例 |
|---|
export | 依格式匯出專案資料。 | apidog export --project <projectId> --format openapi --output ./openapi.json |
export --format apidog | 匯出原生專案資料。 | apidog export --project <projectId> --format apidog --output ./project.apidog.json |
export --scope apis | 以原生格式匯出選取的 API。 | apidog export --project <projectId> --format apidog --scope apis --api-ids 1001,1002 --output ./selected.apidog.json |
export --scope tags | 以原生格式依標籤匯出 API。 | apidog export --project <projectId> --format apidog --scope tags --include-tags pet,store --output ./tagged.apidog.json |
export --format openapi --scope folders | 以 OpenAPI 格式匯出選取的資料夾。 | apidog export --project <projectId> --format openapi --scope folders --folder-ids 2001 --output ./openapi.json |
OAS 匯出設定#
使用 export settings 維護可重複使用的 OAS 匯出設定。| 命令 | 說明 | 範例 |
|---|
export settings list | 列出 OAS 匯出設定。 | apidog export settings list --project <projectId> |
export settings create | 建立 OAS 匯出設定。 | apidog export settings create --project <projectId> --file ./export-setting.json |
export settings get | 檢視 OAS 匯出設定。 | apidog export settings get <settingId> --project <projectId> |
export settings update | 更新 OAS 匯出設定。 | apidog export settings update <settingId> --project <projectId> --file ./export-setting.json |
export settings delete | 刪除 OAS 匯出設定。 | apidog export settings delete <settingId> --project <projectId> |
cli-schema get export-settings-create | 檢視 OAS 匯出設定建立的 schema。 | apidog cli-schema get export-settings-create |
cli-schema get export-settings-update | 檢視 OAS 匯出設定更新的 schema。 | apidog cli-schema get export-settings-update |
文件分享#
文件網站#
| 命令 | 說明 | 範例 |
|---|
docs-site list | 列出文件網站。 | apidog docs-site list --project <projectId> |
docs-site get | 檢視文件網站詳細資料。 | apidog docs-site get <siteId> --project <projectId> |
docs-site create | 建立文件網站。 | apidog docs-site create --project <projectId> --file ./docs-site.json |
docs-site update | 更新文件網站設定。 | apidog docs-site update <siteId> --project <projectId> --file ./docs-site.json |
docs-site delete | 刪除文件網站。 | apidog docs-site delete <siteId> --project <projectId> |
共享文件#
| 命令 | 說明 | 範例 |
|---|
shared-doc list | 列出共享文件。 | apidog shared-doc list --project <projectId> |
shared-doc get | 檢視共享文件詳細資料。 | apidog shared-doc get <docId> --project <projectId> |
shared-doc create | 建立共享文件。 | apidog shared-doc create --project <projectId> --file ./shared-doc.json |
shared-doc update | 更新共享文件設定。 | apidog shared-doc update <docId> --project <projectId> --file ./shared-doc.json |
shared-doc delete | 刪除共享文件。 | apidog shared-doc delete <docId> --project <projectId> |
分支管理#
使用分支命令來隔離變更、協作處理專案資源，以及在分支之間合併選取的資源。迭代分支#
| 命令 | 說明 | 範例 |
|---|
branch list --type all | 列出專案中的所有分支類型。 | apidog branch list --project <projectId> --type all |
branch list --type sprint | 列出迭代分支。 | apidog branch list --project <projectId> --type sprint |
branch get --type sprint | 檢視迭代分支。 | apidog branch get <branchName> --project <projectId> --type sprint |
branch create --type sprint | 建立迭代分支。 | apidog branch create --project <projectId> --type sprint --name <branchName> --from main |
branch update --type sprint | 更新迭代分支。 | apidog branch update <branchName> --project <projectId> --type sprint --name <newName> |
branch merge | 將明確選取的資源從一個分支合併到另一個分支。 | apidog branch merge --project <projectId> --from <sourceBranchName> --to <targetBranchName> --endpoint-ids <ids> |
branch pick-to | 將選取的資源從來源分支挑選到目標分支。 | apidog branch pick-to --project <projectId> --from <sourceBranchName> --to <targetBranchName> --endpoint-ids <ids> |
branch archive --type sprint | 在刪除前封存迭代分支。 | apidog branch archive <branchName> --project <projectId> --type sprint |
branch delete --type sprint | 刪除已封存的迭代分支。 | apidog branch delete <branchName> --project <projectId> --type sprint |
AI 分支#
| 命令 | 說明 | 範例 |
|---|
branch list --type ai | 列出 AI 分支。 | apidog branch list --project <projectId> --type ai |
branch get --type ai | 檢視 AI 分支。 | apidog branch get <branchName> --project <projectId> --type ai |
branch create --type ai | 從來源分支建立 AI 分支。 | apidog branch create --project <projectId> --type ai --name <aiBranchName> --from <sourceBranchName> |
branch update --type ai | 更新 AI 分支。 | apidog branch update <branchName> --project <projectId> --type ai --name <newName> |
branch archive --type ai | 在刪除前封存 AI 分支。 | apidog branch archive <branchName> --project <projectId> --type ai |
branch delete --type ai | 刪除已封存的 AI 分支。 | apidog branch delete <branchName> --project <projectId> --type ai |
一般分支#
| 命令 | 說明 | 範例 |
|---|
branch list --type general | 列出一般分支。 | apidog branch list --project <projectId> --type general |
branch get --type general | 檢視一般分支。 | apidog branch get <branchName> --project <projectId> --type general |
branch create --type general | 建立一般分支。 | apidog branch create --project <projectId> --type general --name <branchName> --from main |
branch update --type general | 更新一般分支。 | apidog branch update <branchName> --project <projectId> --type general --name <newName> |
branch delete --type general | 刪除一般分支。 | apidog branch delete <branchName> --project <projectId> --type general |
分支建立命令主要使用命令列選項，例如 --type、--name 和 --from。cli-schema get branch-*-create 用於檢查建立選項結構。若要查看實際命令選項，請執行 apidog branch create -h。
合併請求#
當目標分支需要審查流程時，請使用 merge-request。合併請求與直接合併都只會合併明確選取的資源。| 命令 | 說明 | 範例 |
|---|
merge-request preview | 在建立合併請求或直接合併前掃描候選變更。 | apidog merge-request preview --project <projectId> --from <sourceBranchName> --to <targetBranchName> |
merge-request list | 列出合併請求。 | apidog merge-request list --project <projectId> --to <targetBranchName> |
merge-request get | 檢視合併請求詳細資料。 | apidog merge-request get <mergeRequestId> --project <projectId> --to <targetBranchName> |
merge-request create | 建立合併請求。 | apidog merge-request create --project <projectId> --to <targetBranchName> --from <sourceBranchName> --reviewer-ids <userIds> --endpoint-ids <ids> |
merge-request update | 更新合併請求。 | apidog merge-request update <mergeRequestId> --project <projectId> --to <targetBranchName> --file ./merge-request.json |
merge-request approve | 核准合併請求。 | apidog merge-request approve <mergeRequestId> --project <projectId> --to <targetBranchName> --file ./approve.json |
merge-request reject | 拒絕合併請求。 | apidog merge-request reject <mergeRequestId> --project <projectId> --to <targetBranchName> |
merge-request delete | 刪除合併請求。 | apidog merge-request delete <mergeRequestId> --project <projectId> --to <targetBranchName> |
為了保障專案資源安全，CLI 寫入權限預設可能受到限制。你可以透過 AI 分支編輯來源分支資料，或在主分支、標準迭代分支或一般分支需要直接編輯時，在專案功能設定中啟用外部編輯權限。在 AI 分支上所做的變更仍需要使用者確認後，才能 merge 或 merge-request。建議 AI 分支名稱包含日期、來源分支與目的，例如 ai/20260312-from-main-user-register。
對於分支合併與挑選操作，資源 ID 選項會使用複數名稱與逗號分隔的數字 ID，例如 --endpoint-ids 1,2、--doc-ids 3,4 和 --test-suite-ids 5,6。
其他資源#
自訂欄位#
| 命令 | 說明 | 範例 |
|---|
custom-field list | 列出自訂欄位。 | apidog custom-field list --project <projectId> |
custom-field create | 建立自訂欄位。 | apidog custom-field create --project <projectId> --file ./custom-field.json |
custom-field update | 更新自訂欄位。 | apidog custom-field update <customFieldId> --project <projectId> --file ./custom-field.json |
custom-field delete | 刪除自訂欄位。 | apidog custom-field delete <customFieldId> --project <projectId> |
WebSocket API#
| 命令 | 說明 | 範例 |
|---|
websocket list | 列出 WebSocket API。 | apidog websocket list --project <projectId> |
websocket get | 檢視 WebSocket API 詳細資料。 | apidog websocket get <websocketId> --project <projectId> |
websocket create | 建立 WebSocket API。 | apidog websocket create --project <projectId> --name <name> --url <url> |
websocket update | 更新 WebSocket API。 | apidog websocket update <websocketId> --project <projectId> --file ./websocket.json |
websocket delete | 刪除 WebSocket API。 | apidog websocket delete <websocketId> --project <projectId> |
Socket.IO API#
| 命令 | 說明 | 範例 |
|---|
socketio list | 列出 Socket.IO API。 | apidog socketio list --project <projectId> |
socketio get | 檢視 Socket.IO API 詳細資料。 | apidog socketio get <socketioId> --project <projectId> |
socketio create | 建立 Socket.IO API。 | apidog socketio create --project <projectId> --file ./socketio.json |
socketio update | 更新 Socket.IO API。 | apidog socketio update <socketioId> --project <projectId> --file ./socketio.json |
socketio delete | 刪除 Socket.IO API。 | apidog socketio delete <socketioId> --project <projectId> |
通用指令碼#
| 命令 | 說明 | 範例 |
|---|
common-script list | 列出通用指令碼。 | apidog common-script list --project <projectId> |
common-script get | 檢視通用指令碼詳細資料。 | apidog common-script get <scriptId> --project <projectId> |
common-script create | 建立通用指令碼。 | apidog common-script create --project <projectId> --file ./common-script.json |
common-script update | 更新通用指令碼。 | apidog common-script update <scriptId> --project <projectId> --file ./common-script.json |
common-script delete | 刪除通用指令碼。 | apidog common-script delete <scriptId> --project <projectId> |
資料庫連線#
| 命令 | 說明 | 範例 |
|---|
database-connection list | 列出資料庫連線。 | apidog database-connection list --project <projectId> |
database-connection get | 檢視資料庫連線詳細資料。 | apidog database-connection get <connectionId> --project <projectId> |
database-connection create | 建立資料庫連線。 | apidog database-connection create --project <projectId> --file ./database-connection.json |
database-connection update | 更新資料庫連線。 | apidog database-connection update <connectionId> --project <projectId> --file ./database-connection.json |
database-connection delete | 刪除資料庫連線。 | apidog database-connection delete <connectionId> --project <projectId> |
Vault Provider#
| 命令 | 說明 | 範例 |
|---|
vault list | 列出 vault provider。 | apidog vault list --project <projectId> |
vault get | 檢視 vault provider 詳細資料。 | apidog vault get <vaultProviderId> --project <projectId> |
vault create | 建立 vault provider。 | apidog vault create --project <projectId> --file ./vault.json |
vault update | 更新 vault provider。 | apidog vault update <vaultProviderId> --project <projectId> --file ./vault.json |
vault delete | 刪除 vault provider。 | apidog vault delete <vaultProviderId> --project <projectId> |
Git 連線#
| 命令 | 說明 | 範例 |
|---|
git-connection list | 列出 Git 連線。 | apidog git-connection list --project <projectId> |
git-connection get | 檢視 Git 連線詳細資料。 | apidog git-connection get <connectionId> --project <projectId> |
git-connection create | 建立 Git 連線。 | apidog git-connection create --project <projectId> --file ./git-connection.json |
git-connection update | 更新 Git 連線。 | apidog git-connection update <connectionId> --project <projectId> --file ./git-connection.json |
git-connection delete | 刪除 Git 連線。 | apidog git-connection delete <connectionId> --project <projectId> |
管理與設定#
使用這些命令進行專案管理、通知、資源回收站、變更歷史與稽核日誌。| 命令 | 說明 | 範例 |
|---|
notification list | 列出通知設定。 | apidog notification list --project <projectId> |
notification get | 檢視通知詳細資料。 | apidog notification get <notificationId> --project <projectId> |
notification create | 建立通知設定。 | apidog notification create --project <projectId> --file ./notification.json |
notification update | 更新通知設定。 | apidog notification update <notificationId> --project <projectId> --file ./notification.json |
notification delete | 刪除通知設定。 | apidog notification delete <notificationId> --project <projectId> |
回收站#
| 命令 | 說明 | 範例 |
|---|
recycle list | 列出回收站中的資源。 | apidog recycle list --project <projectId> |
recycle restore | 從回收站還原資源。 | apidog recycle restore <itemId> --project <projectId> |
recycle delete | 永久刪除回收站資源。 | apidog recycle delete <itemId> --project <projectId> |
| 命令 | 說明 | 範例 |
|---|
history list | 列出專案變更歷史。 | apidog history list --project <projectId> |
history get | 檢視變更歷史詳細資料。 | apidog history get <historyId> --project <projectId> |
稽核日誌#
| 命令 | 說明 | 範例 |
|---|
audit-log list | 列出專案稽核日誌。 | apidog audit-log list --project <projectId> |
audit-log get | 檢視稽核日誌詳細資料。 | apidog audit-log get <auditLogId> --project <projectId> |
進階用法#
在 CLI 中上傳檔案#
使用需要上傳檔案的 API 時，準確設定要上傳檔案的路徑非常重要。你應該將檔案儲存在執行測試的同一台機器上，並使用其絕對或相對路徑來參照。請依照以下步驟參照要上傳的檔案。1
事先將所需檔案複製到執行 CLI 的機器上。例如，如果你使用 GitHub Actions 作為 CI/CD 管線，請將所需檔案複製到與工作流程相同的 GitHub 儲存庫中。
2
在 Apidog 中，前往你的測試情境並找到需要檔案上傳的步驟。如下所示，點選
Bulk Edit 按鈕。
3
複製你已複製到 CLI 機器上的檔案路徑。然後將檔案欄位參數值替換為 CLI 機器上的檔案路徑。例如，如果你將
png 檔案放在 GitHub repo 的
data 資料夾下，可以使用
data/to-be-uploaded.png 來參照它。
如果你想再次在本機執行此測試情境，則需要將參數值中的檔案路徑改回本機機器上的路徑。
在 CLI 中使用資料庫操作#
當你的測試情境包含資料庫操作時，由於資料庫設定儲存在本機而非雲端，因此需要額外幾個步驟。這表示你無法直接針對這些情境以雲端模式執行 CLI。以下是處理方式：1
對於包含資料庫操作的測試情境，你會在命令列產生介面看到提示：「Download the database configuration file。」
2
下載此檔案並將其放在你計畫執行 Apidog CLI 的目錄中。
3
自動產生的命令列會包含 --database-connection 選項。你可以直接使用此命令列執行測試。
將本機 CLI 測試報告上傳到雲端#
若要將本機 CLI 測試報告上傳到雲端，你可以在 CLI 命令結尾加上 --upload-report 參數。做法如下：1
將
--upload-report 參數加到 CLI 命令中：
2
此命令會執行測試，並在完成後自動將測試報告上傳到雲端。
3
若要檢視已上傳的報告：
前往 Apidog 儀表板中的「Test Reports」區段。
4
注意：對於透過 CLI 上傳的報告，「Tester」欄位會顯示為空白。
在 CLI 中使用外部指令碼/程式#
執行 Apidog CLI 時，你可以在命令結尾加入路徑來參照外部指令碼或程式。做法如下：在此範例中，CLI 會被指示參照位於 ./scripts 目錄中的程式。如果未指定階層，預設為目前 CLI 執行目錄。1. 本機路徑#
2. 雲端程式碼儲存庫#
在 CI/CD 工作流程中設定 pull 命令，將外部指令碼擷取到本機環境
SSL#
用戶端憑證#
使用單一 SSL 用戶端憑證#
--ssl-client-cert
指定 SSL 用戶端公開憑證的路徑。
--ssl-client-key
指定 SSL 用戶端私人憑證的路徑（選用）。
--ssl-client-passphrase
指定 SSL 用戶端密碼片語（選用）。
使用 SSL 用戶端憑證設定檔（支援多張憑證）#
--ssl-client-cert-list
指定 SSL 用戶端憑證清單 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"
}
]
--ssl-client-cert、--ssl-client-key 和 --ssl-client-passphrase 選項。如果清單中沒有符合 URL 的項目，這些選項將作為備援選項使用。HTTP/2#
CLI 可透過 --preferred-http-version 參數設定使用特定通訊協定版本來傳送請求。1.
"HTTP/2" - HTTP/2 Application-Layer Protocol Negotiation (ALPN)，僅支援 HTTPS 請求。
2.
"HTTP/2-with-prior-knowledge" - HTTP/2 with prior knowledge 。
1.
為 HTTPS 和 HTTP 請求設定不同的通訊協定版本： 2.
為 HTTPS 和 HTTP 設定相同的通訊協定版本： 3.
為 HTTPS 和 HTTP 都設定 HTTP/2（不支援的值會被自動忽略）： FAQ#
此錯誤通常是由 Authorization 標頭中的無效字元造成，例如非 ASCII 字元、換行符號或多餘空格。如果你確定在 Apidog 用戶端或網頁介面中執行測 試情境不會產生任何錯誤，請檢查是否已為環境中的變數設定 INITIAL 值，並確認 Authorization 值符合預期格式。
為了安全起見，專案寫入權限可能受到限制。當需要直接編輯時，請檢查專案的功能設定並啟用外部編輯權限。
