SePay CLI conventions

Look up SePay CLI command syntax, command groups and global flags, and check which commands ask for confirmation or cannot be undone before you run them.

||

General syntax

Every SePay CLI command has the same shape:

$ sepay <group> <command> [arguments] [flags]
  • <group>: The feature group (for example transaction, 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 select

Once 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

TypeWhenHow to use it
Select oneYou omit the xid of a record (<bank-account-xid>, <webhook-xid>, <profile>), for example bank-account get, webhook delete, auth switchUse 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 severalwebhook update with no edit flags: it asks "What do you want to edit?", then asks for a value for each field you selectedPress Space to toggle an item, the right or left arrow to select all or none, and Enter to confirm
Enter a valueYou omit a required flag, for example --amount of sandbox simulate, --forward of webhook listen, --name of bankhub company createType the value, then press Enter
Masked inputYou 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 offThe characters you type aren't displayed
Multi-stepwebhook create or sandbox init with no flagsAnswer 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 --json or -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.

GroupAliasDescriptionEnvironment
transactiontx, txnManage transactionsSandbox & production
bank-accountbaManage bank accountsSandbox & production*
va-Manage virtual accounts (VA)Sandbox & production*
paycodepcView, set and add payment code prefixesSandbox & production
webhookwhManage webhooks and listen for themSandbox & production*
quota-Check quotaSandbox & production
login / logout / auth-Manage sign-in sessionsSandbox & production
api-Call any API endpointSandbox & production
sandboxsbxCreate and delete sandbox dataSandbox only
pg-Payment GatewaySandbox
bankhubbhBank HubSandbox
einvoiceinveInvoiceSandbox
apikeyakManage API tokensSandbox
configcfgConfigure the CLINo server call
help-Show help for a command, or a topic with sepay help <topic>: environment, errors, exit-codes, glossaryNo server call
completion-Generate shell completion scriptsNo server call
version-Show the CLI versionNo 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

AliasCommandExample
lslistsepay tx ls
st, lsauth status: the profiles stored on this machinesepay auth ls
swauth switchsepay auth sw agent
showget (under pg ipn, pg merchant, bankhub ipn) and 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>

Global flags

FlagShortTypeDefaultDescription
--env-stringdefault_env (sandbox if unset)Select the environment (sandbox | production).
--profile-pstring-Use a different sign-in profile.
--output-ostringtableOutput format: table | json | yaml.
--json-boolfalsePrint the result as JSON (same as -o json).
--yes-yboolfalseSkip 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-boolfalseNever prompt; a missing argument is an error.
--idempotency-key-stringAuto-generatedReuse a key to avoid creating duplicates when a command is interrupted. Only applies to commands that send a key (list).
--quiet-qboolfalseHide extra information.
--verbose-vboolfalsePrint debug logs (tokens are always redacted).
--no-color-boolfalseTurn off colors in the output.
--config-stringconfig.yml in the configuration directoryUse 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-boolfalsePrint 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 replay
  • bank-account update
  • paycode create, paycode update
  • api with a method other than GET, 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:

  1. --env production is on the command line. default_env: production in the configuration does not count.
  2. With --yes, the command must name the id of exactly one resource it changes (table below).
  3. Without --yes, there must be a terminal to prompt on (not run through a pipe, no --no-input, --json, -o yaml, --quiet).
  4. Without --yes, the prompt <action> on production? [y/N] must be answered y. Enter or n cancels (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.

CommandResource idWithout an id
webhook update, webhook delete<webhook-xid>Terminal only: the CLI lets you pick a webhook
webhook replay<transaction-id> or --transactionTerminal 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 createNone (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 resourceTerminal 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:

CaseMessage 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 --yes needed. The reads before the write still run, so on production the read scope is still required. sepay api --dry-run sends 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: stderr prints Dry run: nothing was sent.; stdout prints a FIELD BEFORE AFTER table of the fields that would change (create: FIELD VALUE; delete: the resource as the get command 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"]}
FieldMeaning
requestThe request the real run would send: method, path, body (secrets shown as ***); sepay api adds query, headers
beforeThe current resource, as get -o json prints it; null on create
afterbefore plus the fields the command sends; null on delete, replay. Not the value the server will store
not_checkedAlways one line: the server may normalise or refuse; after the real run, check with get
would_refuseThe 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 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

Commands that ask in some invocations

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

Irreversible commands

These commands can't be undone (destructive: "irreversible" in 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 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.