Apidog CLI: Công cụ API Client cho Terminal

Không gian làm việc API của bạn nằm trong giao diện đồ họa (GUI), nhưng phần lớn ngày làm việc lại diễn ra trong terminal. Mỗi lần chuyển đổi giữa hai môi trường đều làm gián đoạn luồng công việc; trong CI (Continuous Integration) hoặc khi làm việc với AI agent, GUI thậm chí không phải là một lựa chọn. Apidog CLI đưa toàn bộ nền tảng Apidog—kiểm thử, endpoints, schema, môi trường, mock expectation và tài liệu—vào shell bạn đang sử dụng.

Dùng thử Apidog ngay hôm nay

Trước hết, cần phân biệt rõ: Apidog CLI không phải một curl khác. Nếu chỉ cần gửi một yêu cầu GET và xem JSON nhanh, curl hoặc HTTPie là lựa chọn phù hợp; bài tổng hợp các REST client terminal và TUI tập trung vào nhóm công cụ tương tác này.

Apidog CLI là client dành cho workspace API của bạn. Nó có thể chạy test scenario đã xây dựng, đọc hoặc cập nhật API contract, cũng như import/export specification thông qua các lệnh mà script CI hoặc AI agent có thể gọi.

“Sống trong terminal” nghĩa là gì?

Các HTTP tool trong terminal thường xử lý từng request riêng lẻ. Apidog CLI hoạt động ở cấp độ dự án: chạy kiểm thử, quản lý contract, xuất bản tài liệu và điều phối tài nguyên workspace.

Công việc	Nhóm lệnh
Chạy kiểm thử	run, test-scenario, test-suite, test-case, test-data, test-report
Quản lý contract	endpoint, schema, folder, common-parameter, response-component, security-scheme
Xuất bản tài liệu và mock	doc, docs-site, shared-doc, mock
Cấu hình và kết nối	environment, variables, vault, database-connection, websocket, socketio
Hoạt động nhóm	branch, merge-request, runner, scheduled-task, audit-log, import, export

Bắt đầu với --help để kiểm tra cú pháp của bất kỳ nhóm lệnh nào:

apidog run --help
apidog endpoint --help
apidog cli-schema --help

Mỗi lệnh trả về JSON có cấu trúc. Phần lớn phản hồi còn có agentHints.nextSteps, giúp bạn hoặc AI agent biết bước tiếp theo cần thực hiện thay vì phải tự suy đoán quy trình.

Cài đặt và xác thực

Apidog CLI được phân phối qua npm tại apidog-cli, hỗ trợ macOS, Linux và Windows. Yêu cầu Node.js 16 trở lên.

npm install -g apidog-cli
apidog --version

Sau khi cài đặt, đăng nhập bằng API access token. Trong ứng dụng Apidog, mở avatar tài khoản → Account Settings → sao chép token trong mục API Access Token.

apidog login --with-token <YOUR_TOKEN>

Token được lưu tại ~/.apidog/config.toml. Không commit tệp này vào repository hoặc in token ra log CI.

Trong CI, truyền token từ hệ thống secrets bằng --access-token:

apidog run \
  --access-token "$APIDOG_ACCESS_TOKEN" \
  --project <project_id> \
  --branch <branch_name> \
  -t <scenario_id> \
  -e <env_id> \
  -r cli,junit

Các cờ toàn cục quan trọng:

• --project: chọn dự án.
• --branch: chọn nhánh.
• --access-token: ghi đè thông tin đăng nhập đã lưu.
• --api-base-url: kết nối tới triển khai Apidog self-hosted.

Xem thêm hướng dẫn xác thực Apidog CLI để cấu hình token trong CI.

Chạy test scenario trong terminal và CI

Đây là workflow chính của CLI:

1. Tạo test scenario trong trình chỉnh sửa trực quan của Apidog.
2. Chuỗi các request, trích xuất biến từ response và thêm assertion.
3. Sao chép lệnh từ tab CI/CD của scenario.
4. Chạy scenario trong local shell hoặc pipeline CI.

# Sao chép scenario ID và environment ID từ tab CI/CD
apidog run -t <scenario_id> -e <env_id> -r cli

Lệnh trả về:

• Mã thoát 0 khi tất cả assertion thành công.
• Mã thoát khác 0 khi có bất kỳ lỗi nào.

Điều này cho phép pipeline thất bại tự nhiên mà không cần wrapper script bổ sung:

apidog run \
  -t <scenario_id> \
  -e <staging_env_id> \
  -r cli,junit

# CI runner sẽ đánh dấu job failed nếu lệnh trả về mã khác 0.

Để chạy cùng một scenario trên nhiều môi trường, thay đổi -e:

# Development
apidog run -t <scenario_id> -e <dev_env_id> -r cli

# Staging
apidog run -t <scenario_id> -e <staging_env_id> -r cli

# Production
apidog run -t <scenario_id> -e <prod_env_id> -r cli

Chạy kiểm thử dựa trên dữ liệu

Bạn có thể cung cấp tệp CSV hoặc JSON để lặp scenario trên từng dòng dữ liệu. Đây là cách triển khai kiểm thử dựa trên dữ liệu mà không phải nhân bản các bước test.

Nếu đây là lần đầu bạn chạy API test bằng CLI, hãy theo hướng dẫn kiểm thử REST API từng bước.

Xuất báo cáo cho CI

Apidog CLI hỗ trợ bốn định dạng báo cáo:

Định dạng	Mục đích
cli	In kết quả từng bước trong terminal
html	Tạo báo cáo HTML
json	Tạo kết quả JSON để xử lý tự động
junit	Tích hợp với dashboard và CI tooling hỗ trợ JUnit

Các báo cáo tệp được lưu trong thư mục apidog-reports/. Có thể kết hợp nhiều định dạng:

apidog run \
  -t <scenario_id> \
  -e <env_id> \
  -r cli,junit,html

Xem cấu trúc từng loại output trong hướng dẫn báo cáo kiểm thử.

Đối với các lần chạy không nên phụ thuộc vào laptop cá nhân, dùng runner và scheduled-task để quản lý self-hosted runner và lịch thực thi. Đây cũng là cơ chế phía sau kiểm thử API theo lịch trong Apidog.

Quản lý API contract mà không mở ứng dụng

Apidog CLI không chỉ chạy test. Bạn có thể truy vấn và cập nhật tài nguyên trong API project trực tiếp từ terminal:

# Liệt kê endpoints của một dự án
apidog endpoint list --project <project_id>

# Lấy chi tiết schema
apidog schema get <schema_id>

# Liệt kê environments
apidog environment list

# Liệt kê mock expectations
apidog mock list

Các tài nguyên có thể truy vấn hoặc chỉnh sửa gồm:

• Endpoints
• Data schemas
• Folders
• Environments
• Variables
• Security schemes
• Reusable components
• Mock expectations
• Tài liệu đã xuất bản
• WebSocket endpoints
• Socket.IO endpoints
• Database connection configurations

Lệnh mock quản lý mock expectation: các cặp request-response cố định được mock server trả về. Các lệnh doc và docs-site quản lý tài liệu đã xuất bản.

Import và export OpenAPI, Swagger, Postman Collection

CLI hỗ trợ các định dạng quan trọng:

• OpenAPI 3.x
• Swagger 2.0
• Postman Collections

Swagger 2.0 là đặc tả mà nhiều toolchain chuẩn hóa. Bạn có thể dùng Apidog CLI trong migration script để lấy specification từ hệ thống cũ, import vào Apidog, rồi quản lý quá trình đó qua version control.

# Import OpenAPI specification vào project
apidog import openapi.json --project <project_id>

# Export specification từ project
apidog export --format openapi

Workflow an toàn cho AI agent

Các bản phát hành CLI năm 2026 tập trung vào khả năng để AI coding agent vận hành API workspace theo quy trình có kiểm soát.

1. Dùng JSON output và bước gợi ý

Mỗi lệnh trả về JSON mà agent có thể parse. agentHints.nextSteps chỉ ra hành động tiếp theo, bao gồm hướng khôi phục khi có lỗi.

2. Kiểm tra schema trước khi ghi dữ liệu

Nhóm lệnh cli-schema công bố hình dạng JSON mà các lệnh ghi yêu cầu:

# Liệt kê schema khả dụng
apidog cli-schema list

# Lấy schema chi tiết
apidog cli-schema get <schema_id>

# Xác thực payload trước khi create hoặc update
apidog cli-schema validate <payload.json>

Workflow ghi an toàn nên luôn là:

1. Lấy schema.
2. Tạo JSON payload theo schema.
3. Chạy cli-schema validate.
4. Chỉ chạy create hoặc update sau khi payload hợp lệ.

3. Cung cấp kiến thức CLI cho agent

Lệnh skill đóng gói kiến thức vận hành CLI theo định dạng agent có thể tải trực tiếp. Đọc thêm về lý do xây dựng Apidog CLI skill.

Theo các phép đo được nêu trong bài phân tích này, agent làm việc thông qua CLI schema sử dụng ít hơn khoảng 30% tool call và ít hơn 25% token so với agent tự đoán payload.

4. Cô lập thay đổi bằng quyền và AI branch

Theo mặc định, thao tác ghi do AI thực hiện trên một branch sẽ bị chặn cho đến khi người dùng bật External AI Edit Permissions.

Trong Apidog client 2.8.32 trở lên, cấu hình này nằm tại:

Project Settings → Feature Settings → AI Feature Settings

Một cách khác là dùng AI branch:

1. Tạo branch riêng cho agent.
2. Agent import tài nguyên cần thiết và thực hiện chỉnh sửa.
3. Agent trả kết quả dưới dạng merge request.
4. Con người xem xét và merge khi sẵn sàng.

AI branch không được sử dụng sẽ tự động archive sau 24 giờ, tránh tích lũy các thử nghiệm chưa hoàn tất.

Apidog CLI không phải là gì

Ba giới hạn cần biết trước khi chọn công cụ:

Không phải interactive request client

Apidog CLI không có mục tiêu thay thế curl, HTTPie hoặc TUI client cho các request ngẫu hứng. Nếu bạn cần gõ một POST nhanh và format response ngay lập tức, những công cụ đó phù hợp hơn.

Không phải mã nguồn mở

Gói CLI là độc quyền và npm là kênh cài đặt duy nhất. Để thực hiện thao tác ngoài --help, bạn cần tài khoản Apidog.

Gói miễn phí bao gồm workflow được mô tả trong bài viết. Nếu yêu cầu bắt buộc của đội ngũ là license có thể kiểm toán, một open-source runner sẽ là lựa chọn phù hợp hơn.

Không hoạt động độc lập với Apidog project

Scenario, endpoint và environment tồn tại trong Apidog project, không phải trong các tệp local. Đổi lại, bạn có một nguồn dữ liệu thống nhất cho API design, testing, mocking và documentation.

Apidog CLI phù hợp ở đâu trong terminal toolchain?

Khác biệt chính giữa các API test runner là nơi các test artifact được tạo và lưu trữ:

Công cụ	Nơi tạo artifact
Newman / Postman CLI	Postman collections
Hurl / Bruno	Tệp văn bản
Apidog CLI	Apidog visual editor, cùng project với contract, mock và docs

Đọc thêm trong bài Apidog CLI vs Newman và danh sách các công cụ kiểm thử API terminal hàng đầu.

Một thiết lập thực tế cho nhiều team:

• Dùng curl hoặc xh để kiểm tra API nhanh.
• Dùng apidog run để chạy test suite trong CI.
• Dùng junit hoặc html report để xuất artifact.
• Dùng branch và merge request để kiểm soát thay đổi API contract.

Để bắt đầu với GitHub Actions, sử dụng pipeline có thể copy-paste trong hướng dẫn GitHub Actions.

FAQ

Apidog CLI có miễn phí sử dụng không?

Có. Gói npm được cài đặt miễn phí, và gói miễn phí của Apidog cho phép xây dựng scenario cũng như chạy chúng qua CLI. Các gói trả phí bổ sung tính năng cho đội nhóm, không phải quyền truy cập CLI cơ bản.

Apidog CLI có thay thế curl hoặc HTTPie không?

Không. curl và HTTPie phù hợp cho request ngẫu hứng; Apidog CLI chạy test scenario đã lưu và quản lý tài nguyên dự án. Một terminal workflow thực tế thường dùng cả hai.

Có thể chạy headless hoàn toàn trong CI không?

Có. Truyền --access-token từ CI secret, chạy apidog run với scenario ID và dùng exit code để quyết định trạng thái build. Runner không cần cài ứng dụng desktop.

CLI có thể import và export định dạng nào?

OpenAPI 3.x, Swagger 2.0 và Postman Collections theo cả hai hướng. Điều này hỗ trợ migration vào Apidog và tích hợp specification ra các hệ thống khác.

Làm thế nào để AI agent sử dụng CLI an toàn?

Dùng quy trình schema-validate-write:

apidog cli-schema get <schema_id>
apidog cli-schema validate <payload.json>
# Chỉ ghi dữ liệu sau khi validate thành công

Kết hợp với External AI Edit Permissions hoặc AI branch để cô lập thay đổi trước khi merge. Xem ví dụ trong cách sử dụng Apidog CLI trong Claude Code.

Terminal là nơi test của bạn chạy và AI agent của bạn làm việc. Đưa API workspace vào cùng môi trường giúp loại bỏ lần chuyển đổi ngữ cảnh cuối cùng. Tải Apidog, cài đặt CLI từ npm và chạy một scenario từ đầu đến cuối. Khi cần thêm lệnh ngoài run, xem tài liệu tham khảo đầy đủ tại trang Apidog CLI.