Quy ước chung của SePay CLI

Tra cú pháp lệnh SePay CLI, các nhóm lệnh và flag dùng chung, rồi xem lệnh nào hỏi xác nhận hoặc không hoàn tác được trước khi chạy.

||

Cú pháp chung

Mọi lệnh SePay CLI có cùng dạng:

$ sepay <nhóm> <lệnh> [đối số] [flag]
  • <nhóm>: Nhóm chức năng (ví dụ transaction, bank-account).
  • <lệnh>: Hành động (list, create, delete).
  • [đối số]: Tham số không có tên, thường là xid của đối tượng, ví dụ <webhook-xid>. Bỏ trống thì CLI hỏi chọn trong terminal (Chọn tương tác khi bỏ trống).
  • [flag]: Tham số có tên, bắt đầu bằng -- (hoặc dạng ngắn -o).

Chọn tương tác khi bỏ trống

Khi bỏ trống một đối số hoặc flag bắt buộc, CLI hỏi giá trị trong terminal thay vì báo lỗi. Ở phần usage của --help và trường args của sepay --map=json, đối số trong dấu < > như <webhook-xid> được hỏi khi chạy trong terminal và bắt buộc phải truyền khi chạy không tương tác. Đối số trong dấu [ ] là tùy chọn thật sự: bỏ trống thì lệnh vẫn chạy, ví dụ sepay webhook logs [webhook-xid] không kèm xid liệt kê log của mọi webhook.

Ví dụ, sepay bank-account get không kèm xid hiện danh sách tài khoản để chọn:

$ sepay ba getenv: sandbox? Bank account> ACB · 0000000002 · NGUYEN VAN AABBANK · 0000000001 · TRAN MINH C (sandbox)↑/↓ move · type to filter · enter select

Chọn xong, lệnh chạy như khi truyền xid:

? Bank account › ABBANK · 0000000001 · TRAN MINH C (sandbox)FIELD    VALUEID       90b2c5af-xxxx-xxxx-xxxx-fa163e2f7c98Bank     ABBANK (Ngân hàng TMCP An Bình)Account  0000000001...

Các kiểu hỏi

KiểuKhi nàoThao tác
Chọn mộtBỏ trống xid của đối tượng (<bank-account-xid>, <webhook-xid>, <profile>), ví dụ bank-account get, webhook delete, auth switchMũi tên lên/xuống để di chuyển, gõ để lọc (không phân biệt hoa thường, khớp một phần), Enter để chọn. Mỗi dòng hiện mô tả dễ đọc; giá trị gửi đi vẫn là xid
Chọn nhiềuwebhook update không kèm flag chỉnh sửa: hỏi "What do you want to edit?", sau đó nhập giá trị từng trường đã chọnPhím cách để đánh dấu, mũi tên phải/trái để chọn hết hoặc bỏ hết, Enter để xác nhận
Nhập giá trịBỏ trống flag bắt buộc, ví dụ --amount của sandbox simulate, --forward của webhook listen, --name của bankhub company createGõ giá trị rồi Enter
Nhập ẩnNhập secret, ví dụ chọn nhập khóa ở bankhub ipn set: không có --api-key thì CLI hỏi giữ khóa đang lưu, nhập khóa mới hoặc tắt xác thựcKý tự gõ vào không hiện trên màn hình
Nhiều bướcwebhook create, sandbox init không kèm flagTrả lời lần lượt từng câu hỏi; --yes dùng giá trị mặc định (sandbox init)

Danh sách chọn rỗng thì CLI báo chưa có dữ liệu và gợi ý lệnh tạo, ví dụ no bank accounts found; create one first (sepay bank-account create).

Bấm Ctrl+C hoặc Esc ở bất kỳ câu hỏi nào để hủy lệnh: CLI dừng với exit code 130 và không in lỗi.

Khi nào không hỏi

CLI chỉ hỏi khi có đủ các điều kiện sau:

  • stdin và stdout đều là terminal.
  • Không có --no-input.
  • Output là bảng (không có --json hoặc -o yaml).
  • Không có --quiet.

Thiếu một điều kiện nào thì CLI không hỏi mà dừng với exit code 2 và nêu giá trị còn thiếu, ví dụ a bank account xid is required hoặc --amount is required. Script và AI agent truyền đủ đối số và flag (Script, AI agent); --no-input bảo đảm lệnh báo lỗi ngay thay vì chờ nhập.

Nhóm lệnh chính

Mọi lệnh con và flag riêng của từng lệnh có ở Danh sách lệnh.

NhómViết tắtMô tảMôi trường
transactiontx, txnQuản lý giao dịchCả sandbox & production
bank-accountbaQuản lý tài khoản ngân hàngCả sandbox & production*
va-Quản lý tài khoản ảo (Virtual Account)Cả sandbox & production*
paycodepcXem, đặt và thêm tiền tố mã thanh toánCả sandbox & production
webhookwhQuản lý webhook & lắng ngheCả sandbox & production*
quota-Kiểm tra hạn mứcCả sandbox & production
login / logout / auth-Quản lý phiên đăng nhậpCả sandbox & production
api-Gọi một endpoint API bất kỳCả sandbox & production
sandboxsbxTạo dữ liệu sandbox, xóa dữ liệuChỉ sandbox
pg-Cổng thanh toánSandbox
bankhubbhBank HubSandbox
einvoiceinvHóa đơn điện tửSandbox
apikeyakQuản lý API TokenSandbox
configcfgCấu hình CLIKhông gọi server
help-Xem hướng dẫn lệnh, hoặc một chủ đề với sepay help <chủ đề>: environment, errors, exit-codes, glossaryKhông gọi server
completion-Tạo script gợi ý lệnhKhông gọi server
version-Xem phiên bản CLIKhông gọi server

* Một số lệnh chỉ chạy trên sandbox (danh sách). Trên production, lệnh cần đúng scope của nó (Scope).

Một số lệnh chưa được hỗ trợ: report cashflow, bankhub va list, bankhub va get, bankhub sandbox link-request accept, bankhub sandbox link-request reject, einvoice error-notification create, einvoice error-notification list, einvoice error-notification get, einvoice invoice download, einvoice invoice delete. Các lệnh này bị ẩn khỏi --help, trả exit code 3 và có "implemented": false trong sepay --map=json.

Viết tắt lệnh con

Viết tắtLệnhVí dụ
lslistsepay tx ls
st, lsauth status: các profile lưu trên máysepay auth ls
swauth switchsepay auth sw agent
showget (trong pg ipn, pg merchant, bankhub ipn) và bankhub webhook listsepay pg merchant show
logwebhook logssepay wh log
rm, deldeletesepay ba del <bank-account-xid>
newcreatesepay wh new
taillistensepay wh tail
editupdatesepay ba edit <bank-account-xid>

Flag dùng chung

FlagDạng ngắnKiểuMặc địnhMô tả
--env-stringdefault_env (sandbox nếu chưa đặt)Chọn môi trường (sandbox | production).
--profile-pstring-Chọn profile đăng nhập khác.
--output-ostringtableĐịnh dạng kết quả: table | json | yaml.
--json-boolfalseIn kết quả dạng JSON (tương đương -o json).
--yes-yboolfalseBỏ qua câu hỏi xác nhận. Với lệnh sửa dữ liệu trên production, chỉ được nhận khi lệnh có --env production và id tài nguyên (luật); không thay bước gõ lại mã giao dịch của webhook replay --force trên production.
--no-input-boolfalseKhông hỏi người dùng; thiếu tham số sẽ lỗi.
--idempotency-key-stringTự tạoDùng lại key để tránh tạo trùng khi lệnh bị gián đoạn. Chỉ có tác dụng với lệnh gửi key (danh sách).
--quiet-qboolfalseẨn thông tin phụ.
--verbose-vboolfalseIn log debug (token luôn được che).
--no-color-boolfalseTắt màu trong output.
--config-stringconfig.yml trong thư mục cấu hìnhDùng tệp cấu hình khác (đường dẫn tới tệp, không phải thư mục). Vị trí thư mục cấu hình: Môi trường và cấu hình.
--map-string-In cây lệnh rồi thoát: tree | paths | json; chỉ ghi --map là tree (AI agent).
--help-h--Xem hướng dẫn chi tiết lệnh.
--version-boolfalseIn phiên bản CLI rồi thoát, giống sepay version; nhận cả --json và -o yaml.

Xác nhận và lệnh không hoàn tác

Lệnh sửa dữ liệu trên production

Mọi lệnh sửa dữ liệu trên production chỉ chạy khi bạn tự xác nhận trên terminal của mình. AI không tự xác nhận thay bạn: gặp lệnh này, AI đưa lệnh để bạn tự chạy.

Luật này áp cho mọi lệnh có confirms: terminal trong sepay --map=json --env production:

  • webhook create, webhook update, webhook delete, webhook replay
  • bank-account update
  • paycode create, paycode update
  • api với method khác GET, HEAD

Khi lệnh nhắm tới production, CLI kiểm 4 điều theo thứ tự. Điều đầu tiên không đạt thì lệnh dừng với exit code 2, chưa gửi request nào:

  1. Có --env production ngay trên lệnh. default_env: production trong cấu hình không tính.
  2. Có --yes thì lệnh phải nêu id của đúng một tài nguyên nó sửa (bảng dưới).
  3. Không có --yes thì phải có terminal để hỏi (không chạy qua pipe, không có --no-input, --json, -o yaml, --quiet).
  4. Không có --yes thì câu hỏi <thao tác> on production? [y/N] phải được trả lời y. Enter hoặc n là hủy (exit code 2); Esc, Ctrl+C là exit code 130.

Có đủ --env production, id tài nguyên và --yes thì lệnh chạy không hỏi, kể cả không có terminal. Cách này dành cho script bạn tự viết (Script); agent không tự thêm --yes cho lệnh production.

LệnhId tài nguyênKhông có id
webhook update, webhook delete<webhook-xid>Chỉ chạy trên terminal: CLI cho chọn webhook
webhook replay<transaction-id> hoặc --transactionChỉ chạy trên terminal: CLI cho chọn lần gửi gần đây
bank-account update<bank-account-xid>Chỉ chạy trên terminal: CLI cho chọn tài khoản
paycode update--structure <prefix>Chỉ chạy trên terminal. --enable, --disable bật tắt nhận diện cho cả công ty nên luôn chỉ chạy trên terminal
webhook create, paycode createKhông có (tạo mới)Chỉ chạy trên terminal
api -X <method ghi>Đoạn cuối của path là UUID hoặc số, ví dụ /webhooks/<xid>. Id của tài nguyên cha không tính: POST /bank-accounts/<xid>/va là tạo mớiChỉ chạy trên terminal

webhook replay --force trên production còn bắt gõ lại mã giao dịch trên terminal; --yes không thay được bước này.

Trước câu hỏi hoặc request, CLI in env: production và ! live: <thao tác> targets PRODUCTION.

Câu báo khi lệnh bị dừng (exit code 2, error_code: usage_error). Không có terminal thì câu báo không bao giờ gợi ý thêm --yes hay --env production:

Trường hợpCâu báo khi không có terminal
Thiếu --env production<action> targets production without --env production on the command line (default_env does not count); ask the user to run this command in their own terminal
--yes với lệnh không có id<action> names no single resource, so --yes cannot confirm it on production; ask the user to run this command in their own terminal
Không --yes, không hỏi được<action> on production needs confirmation; ask the user to run this command in their own terminal
webhook replay --force--force on production must be confirmed on a terminal, and --yes does not confirm it; ask the user to run this command in their own terminal
Trả lời n hoặc Enter<action> cancelled

Có terminal thì câu báo thay vế ask the user… bằng cách sửa lệnh, ví dụ add --env production to the command; default_env does not count.

auth revoke --all và logout --all là ngoại lệ: chúng chỉ kết thúc phiên đăng nhập (đăng nhập lại là dùng tiếp), không đụng tiền hay dữ liệu thanh toán, nên --yes xác nhận được ở mọi môi trường dù không có id.

Chạy thử

Thêm --dry-run vào lệnh sửa dữ liệu trên production (mọi lệnh ở mục trên) để xem lệnh sẽ gửi gì mà không gửi request ghi nào. Chạy được ở cả sandbox và production:

  • Không hỏi, không cần --yes. Các bước đọc trước khi ghi vẫn chạy, nên trên production vẫn cần scope read. sepay api --dry-run không gửi gì, kể cả GET.
  • Không bị 4 điều kiện của luật chặn: câu báo mà lần chạy thật sẽ dừng được ghi vào would_refuse.
  • Exit code 0. Bước đọc lỗi thì exit code như lệnh đọc đó (1, 4, 5, 8).
  • Dạng bảng: stderr in Dry run: nothing was sent.; stdout in bảng FIELD BEFORE AFTER các trường sẽ đổi (tạo mới: FIELD VALUE; xóa: tài nguyên như lệnh get in).
$ sepay webhook update <webhook-xid> --url https://example.com/new-hook --env production --dry-run -o json{"dry_run": true,"request": {  "method": "PUT",  "path": "/webhooks/<webhook-xid>",  "body": { "url": "https://example.com/new-hook" }},"before": { "id": "<webhook-xid>", "webhook_url": "https://example.com/hook" },"after": { "id": "<webhook-xid>", "webhook_url": "https://example.com/new-hook" },"not_checked": ["what the server normalises, derives or refuses; after the real run, get shows what it stored"],"would_refuse": ["update webhook on production needs confirmation; ask the user to run this command in their own terminal"]}
TrườngÝ nghĩa
requestRequest lần chạy thật sẽ gửi: method, path, body (secret in ***); sepay api có thêm query, headers
beforeTài nguyên hiện tại, như get -o json; null khi tạo mới
afterbefore cộng các trường lệnh gửi lên; null khi xóa, gửi lại. Không phải giá trị server sẽ lưu
not_checkedLuôn một dòng: server có thể chuẩn hóa hoặc từ chối; chạy thật xong thì xem bằng get
would_refuseCâu báo lần chạy thật sẽ dừng; [] khi lần chạy thật sẽ chạy

webhook replay --dry-run đặt bản xem trước (transaction_id, amount, sent_to, last_result) vào before. sepay api --dry-run chỉ in dry_run, request, would_refuse.

Lệnh luôn hỏi xác nhận trên sandbox

  • apikey delete
  • bank-account delete
  • bankhub company update
  • bankhub ipn set
  • bankhub link-token revoke
  • bankhub webhook set
  • einvoice invoice issue
  • pg ipn set
  • pg order cancel
  • pg order void
  • sandbox reset
  • va revoke
  • webhook delete
  • webhook replay

Lệnh hỏi xác nhận tùy cách gọi

  • api -X DELETE (trên sandbox)
  • auth logout --all, logout --all
  • auth revoke --all
  • config set default_env production

Lệnh không hoàn tác

Các lệnh dưới đây không hoàn tác được (destructive: "irreversible" trong sepay --map=json).

  • apikey delete
  • auth revoke
  • bank-account delete
  • bankhub link-token revoke
  • bankhub webhook set
  • einvoice invoice issue
  • pg order cancel
  • pg order void
  • sandbox reset
  • va revoke
  • webhook delete

einvoice invoice create với is_draft: false cũng không hoàn tác được nhưng không hỏi xác nhận.

Khi không có terminal

Khi không hỏi được (không có terminal, hoặc có --no-input/--json/-o yaml/--quiet), lệnh cần xác nhận mà thiếu --yes, hoặc thiếu đối số bắt buộc, dừng với exit code 2 và chưa gửi request. Trên sandbox, lỗi thiếu xác nhận có dạng Error: delete webhook <xid>? requires confirmation; pass --yes. Trên production, lệnh sửa dữ liệu dừng theo luật ở trên.