General syntax
Every SePay CLI command has the same shape:
$ sepay <group> <command> [arguments] [flags]<group>: The feature group (for exampletransaction,bank-account).<command>: The action (list,create,delete).[arguments]: Unnamed parameters, usually the xid of a record, such as<webhook-xid>. If you omit one, the CLI prompts you to choose in a terminal (Interactive prompts for omitted arguments).[flags]: Named parameters that start with--(or the short form such as-o).
Interactive prompts for omitted arguments
When you omit a required argument or flag, the CLI asks for the value right in the terminal instead of returning an error. In the usage line of --help and the args field of sepay --map=json, an argument in < > such as <webhook-xid> is prompted for in a terminal and required when nothing can prompt. An argument in [ ] is truly optional: the command runs without it, for example sepay webhook logs [webhook-xid] with no xid lists the logs of every webhook.
For example, sepay bank-account get without an xid shows a list of accounts to choose from:
$ sepay ba getenv: sandbox? Bank account> ACB · 0000000002 · NGUYEN VAN AABBANK · 0000000001 · TRAN MINH C (sandbox)↑/↓ move · type to filter · enter selectOnce you choose, the command runs as if you had passed the 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...Prompt types
| Type | When | How to use it |
|---|---|---|
| Select one | You omit the xid of a record (<bank-account-xid>, <webhook-xid>, <profile>), for example bank-account get, webhook delete, auth switch | Use the up and down arrows to move, type to filter (case-insensitive, partial match), and press Enter to select. Each row shows a readable description; the value sent is still the xid |
| Select several | webhook update with no edit flags: it asks "What do you want to edit?", then asks for a value for each field you selected | Press Space to toggle an item, the right or left arrow to select all or none, and Enter to confirm |
| Enter a value | You omit a required flag, for example --amount of sandbox simulate, --forward of webhook listen, --name of bankhub company create | Type the value, then press Enter |
| Masked input | You enter a secret, for example when you choose to enter a key in bankhub ipn set: without --api-key, the CLI asks whether to keep the stored key, enter a new one or turn authentication off | The characters you type aren't displayed |
| Multi-step | webhook create or sandbox init with no flags | Answer each question in turn; --yes uses the defaults (sandbox init) |
If a selection list is empty, the CLI says there is no data yet and suggests the command to create some, for example no bank accounts found; create one first (sepay bank-account create).
Press Ctrl+C or Esc at any prompt to cancel the command: the CLI exits with exit code 130 and prints no error.
When prompts don't appear
The CLI prompts only when all of these conditions hold:
- Both stdin and stdout are terminals.
- There is no
--no-input. - The output is a table (no
--jsonor-o yaml). - There is no
--quiet.
If any condition fails, the CLI doesn't prompt; it exits with exit code 2 and names the missing value, for example a bank account xid is required or --amount is required. Scripts and AI agents pass every argument and flag (Scripts, AI agents); --no-input makes a command fail right away instead of waiting for input.
Main command groups
Every subcommand and its own flags are in the Command list.
| Group | Alias | Description | Environment |
|---|---|---|---|
transaction | tx, txn | Manage transactions | Sandbox & production |
bank-account | ba | Manage bank accounts | Sandbox & production* |
va | - | Manage virtual accounts (VA) | Sandbox & production* |
paycode | pc | View, set and add payment code prefixes | Sandbox & production |
webhook | wh | Manage webhooks and listen for them | Sandbox & production* |
quota | - | Check quota | Sandbox & production |
login / logout / auth | - | Manage sign-in sessions | Sandbox & production |
api | - | Call any API endpoint | Sandbox & production |
sandbox | sbx | Create and delete sandbox data | Sandbox only |
pg | - | Payment Gateway | Sandbox |
bankhub | bh | Bank Hub | Sandbox |
einvoice | inv | eInvoice | Sandbox |
apikey | ak | Manage API tokens | Sandbox |
config | cfg | Configure the CLI | No server call |
help | - | Show help for a command, or a topic with sepay help <topic>: environment, errors, exit-codes, glossary | No server call |
completion | - | Generate shell completion scripts | No server call |
version | - | Show the CLI version | No server call |
* Some commands run on the sandbox only (list). On production, each command needs its own scope (Scopes).
Some commands aren't supported yet: 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. They are hidden from --help, exit with exit code 3 and show "implemented": false in sepay --map=json.
Subcommand aliases
| Alias | Command | Example |
|---|---|---|
ls | list | sepay tx ls |
st, ls | auth status: the profiles stored on this machine | sepay auth ls |
sw | auth switch | sepay auth sw agent |
show | get (under pg ipn, pg merchant, bankhub ipn) and 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> |
Global flags
| Flag | Short | Type | Default | Description |
|---|---|---|---|---|
--env | - | string | default_env (sandbox if unset) | Select the environment (sandbox | production). |
--profile | -p | string | - | Use a different sign-in profile. |
--output | -o | string | table | Output format: table | json | yaml. |
--json | - | bool | false | Print the result as JSON (same as -o json). |
--yes | -y | bool | false | Skip the confirmation prompt. For a command that changes data on production, it is accepted only when the command has --env production and a resource id (rule); it doesn't replace typing the transaction id back for webhook replay --force on production. |
--no-input | - | bool | false | Never prompt; a missing argument is an error. |
--idempotency-key | - | string | Auto-generated | Reuse a key to avoid creating duplicates when a command is interrupted. Only applies to commands that send a key (list). |
--quiet | -q | bool | false | Hide extra information. |
--verbose | -v | bool | false | Print debug logs (tokens are always redacted). |
--no-color | - | bool | false | Turn off colors in the output. |
--config | - | string | config.yml in the configuration directory | Use a different configuration file (a path to the file, not a directory). For the directory location, see Environments and configuration. |
--map | - | string | - | Print the command tree and exit: tree | paths | json; --map alone means tree (AI agent). |
--help | -h | - | - | Show detailed help for a command. |
--version | - | bool | false | Print the CLI version and exit, like sepay version; works with --json and -o yaml. |
Confirmation and irreversible commands
Production writes
A command that changes data on production runs only when you confirm it on your own terminal. An AI does not confirm it for you: it hands you the command to run yourself.
This rule applies to every command with confirms: terminal in sepay --map=json --env production:
webhook create,webhook update,webhook delete,webhook replaybank-account updatepaycode create,paycode updateapiwith a method other thanGET,HEAD
When the command targets production, the CLI checks 4 conditions in order. At the first one that fails, the command exits with exit code 2 before sending any request:
--env productionis on the command line.default_env: productionin the configuration does not count.- With
--yes, the command must name the id of exactly one resource it changes (table below). - Without
--yes, there must be a terminal to prompt on (not run through a pipe, no--no-input,--json,-o yaml,--quiet). - Without
--yes, the prompt<action> on production? [y/N]must be answeredy.Enterorncancels (exit code 2); Esc, Ctrl+C give exit code 130.
With --env production, a resource id and --yes all present, the command runs without prompting, even without a terminal. This is meant for scripts you write yourself (Scripts); an agent never adds --yes to a production command.
| Command | Resource id | Without an id |
|---|---|---|
webhook update, webhook delete | <webhook-xid> | Terminal only: the CLI lets you pick a webhook |
webhook replay | <transaction-id> or --transaction | Terminal only: the CLI lets you pick a recent delivery |
bank-account update | <bank-account-xid> | Terminal only: the CLI lets you pick an account |
paycode update | --structure <prefix> | Terminal only. --enable, --disable switch detection on or off for the whole company, so they always run on a terminal only |
webhook create, paycode create | None (creates a new resource) | Terminal only |
api -X <write method> | The last path segment is a UUID or a number, e.g. /webhooks/<xid>. A parent resource's id does not count: POST /bank-accounts/<xid>/va creates a new resource | Terminal only |
webhook replay --force on production also makes you type the transaction id back on a terminal; --yes doesn't replace this step.
Before the prompt or the request, the CLI prints env: production and ! live: <action> targets PRODUCTION.
Messages when the command is stopped (exit code 2, error_code: usage_error). Without a terminal, the message never suggests adding --yes or --env production:
| Case | Message without a terminal |
|---|---|
--env production missing | <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 on a command without an id | <action> names no single resource, so --yes cannot confirm it on production; ask the user to run this command in their own terminal |
No --yes, can't prompt | <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 |
Answered n or Enter | <action> cancelled |
With a terminal, the message replaces the ask the user… part with how to fix the command, e.g. add --env production to the command; default_env does not count.
auth revoke --all and logout --all are exceptions: they only end sign-in sessions (signing in again restores access) and don't touch money or payment data, so --yes confirms them in every environment even without an id.
Dry run
Add --dry-run to a command that changes data on production (every command in the section above) to see what it would send without sending any write request. It works on both sandbox and production:
- No prompt, no
--yesneeded. The reads before the write still run, so on production thereadscope is still required.sepay api --dry-runsends nothing, not even a GET. - The 4 conditions of the rule don't block it: the message the real run would stop with goes into
would_refuse. - Exit code 0. If a read step fails, the exit code is that of the read command (1, 4, 5, 8).
- Table output:
stderrprintsDry run: nothing was sent.;stdoutprints aFIELD BEFORE AFTERtable of the fields that would change (create:FIELD VALUE; delete: the resource as thegetcommand prints it).
$ 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"]}| Field | Meaning |
|---|---|
request | The request the real run would send: method, path, body (secrets shown as ***); sepay api adds query, headers |
before | The current resource, as get -o json prints it; null on create |
after | before plus the fields the command sends; null on delete, replay. Not the value the server will store |
not_checked | Always one line: the server may normalise or refuse; after the real run, check with get |
would_refuse | The message the real run would stop with; [] when the real run would go ahead |
webhook replay --dry-run puts the preview (transaction_id, amount, sent_to, last_result) in before. sepay api --dry-run prints only dry_run, request, would_refuse.
Commands that always ask for confirmation on 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
Commands that ask in some invocations
api -X DELETE(on sandbox)auth logout --all,logout --allauth revoke --allconfig set default_env production
Irreversible commands
These commands can't be undone (destructive: "irreversible" in 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 with is_draft: false can't be undone either, but it doesn't ask for confirmation.
Without a terminal
When the CLI can't prompt (no terminal, or --no-input/--json/-o yaml/--quiet), a command that needs confirmation and has no --yes, or that lacks a required argument, exits with exit code 2 before sending any request. On sandbox, a missing confirmation reads like Error: delete webhook <xid>? requires confirmation; pass --yes. On production, a command that changes data stops under the rule above.