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 selectChọ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ểu | Khi nào | Thao tác |
|---|---|---|
| Chọn một | Bỏ trống xid của đối tượng (<bank-account-xid>, <webhook-xid>, <profile>), ví dụ bank-account get, webhook delete, auth switch | Mũ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ều | webhook 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ọn | Phí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 create | Gõ giá trị rồi Enter |
| Nhập ẩn | Nhậ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ực | Ký tự gõ vào không hiện trên màn hình |
| Nhiều bước | webhook create, sandbox init không kèm flag | Trả 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ó
--jsonhoặ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óm | Viết tắt | Mô tả | Môi trường |
|---|---|---|---|
transaction | tx, txn | Quản lý giao dịch | Cả sandbox & production |
bank-account | ba | Quản lý tài khoản ngân hàng | Cả sandbox & production* |
va | - | Quản lý tài khoản ảo (Virtual Account) | Cả sandbox & production* |
paycode | pc | Xem, đặt và thêm tiền tố mã thanh toán | Cả sandbox & production |
webhook | wh | Quản lý webhook & lắng nghe | Cả sandbox & production* |
quota | - | Kiểm tra hạn mức | Cả sandbox & production |
login / logout / auth | - | Quản lý phiên đăng nhập | Cả sandbox & production |
api | - | Gọi một endpoint API bất kỳ | Cả sandbox & production |
sandbox | sbx | Tạo dữ liệu sandbox, xóa dữ liệu | Chỉ sandbox |
pg | - | Cổng thanh toán | Sandbox |
bankhub | bh | Bank Hub | Sandbox |
einvoice | inv | Hóa đơn điện tử | Sandbox |
apikey | ak | Quản lý API Token | Sandbox |
config | cfg | Cấu hình CLI | Khô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, glossary | Không gọi server |
completion | - | Tạo script gợi ý lệnh | Không gọi server |
version | - | Xem phiên bản CLI | Khô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ắt | Lệnh | Ví dụ |
|---|---|---|
ls | list | sepay tx ls |
st, ls | auth status: các profile lưu trên máy | sepay auth ls |
sw | auth switch | sepay auth sw agent |
show | get (trong pg ipn, pg merchant, bankhub ipn) và bankhub webhook list | sepay pg merchant show |
log | webhook logs | sepay wh log |
rm, del | delete | sepay ba del <bank-account-xid> |
new | create | sepay wh new |
tail | listen | sepay wh tail |
edit | update | sepay ba edit <bank-account-xid> |
Flag dùng chung
| Flag | Dạng ngắn | Kiểu | Mặc định | Mô tả |
|---|---|---|---|---|
--env | - | string | default_env (sandbox nếu chưa đặt) | Chọn môi trường (sandbox | production). |
--profile | -p | string | - | Chọn profile đăng nhập khác. |
--output | -o | string | table | Định dạng kết quả: table | json | yaml. |
--json | - | bool | false | In kết quả dạng JSON (tương đương -o json). |
--yes | -y | bool | false | Bỏ 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 | - | bool | false | Không hỏi người dùng; thiếu tham số sẽ lỗi. |
--idempotency-key | - | string | Tự tạo | Dù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 | -q | bool | false | Ẩn thông tin phụ. |
--verbose | -v | bool | false | In log debug (token luôn được che). |
--no-color | - | bool | false | Tắt màu trong output. |
--config | - | string | config.yml trong thư mục cấu hình | Dù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 | - | bool | false | In 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 replaybank-account updatepaycode create,paycode updateapivới method khácGET,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:
- Có
--env productionngay trên lệnh.default_env: productiontrong cấu hình không tính. - Có
--yesthì lệnh phải nêu id của đúng một tài nguyên nó sửa (bảng dưới). - Không có
--yesthì phải có terminal để hỏi (không chạy qua pipe, không có--no-input,--json,-o yaml,--quiet). - Không có
--yesthì câu hỏi<thao tác> on production? [y/N]phải được trả lờiy.Enterhoặcnlà 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ệnh | Id tài nguyên | Khô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 --transaction | Chỉ 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 create | Khô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ới | Chỉ 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ợp | Câ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 scoperead.sepay api --dry-runkhô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:
stderrinDry run: nothing was sent.;stdoutin bảngFIELD BEFORE AFTERcác trường sẽ đổi (tạo mới:FIELD VALUE; xóa: tài nguyên như lệnhgetin).
$ 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 |
|---|---|
request | Request lần chạy thật sẽ gửi: method, path, body (secret in ***); sepay api có thêm query, headers |
before | Tài nguyên hiện tại, như get -o json; null khi tạo mới |
after | before 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_checked | Luô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_refuse | Câ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 deletebank-account deletebankhub company updatebankhub ipn setbankhub link-token revokebankhub webhook seteinvoice invoice issuepg ipn setpg order cancelpg order voidsandbox resetva revokewebhook deletewebhook 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 --allauth revoke --allconfig 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 deleteauth revokebank-account deletebankhub link-token revokebankhub webhook seteinvoice invoice issuepg order cancelpg order voidsandbox resetva revokewebhook 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.