Use SePay CLI with AI agents

Let AI agents such as Claude Code or Codex run SePay CLI safely: which commands are sandbox-only, which production writes you must run yourself, and where to read JSON results.

||

When an AI agent such as Claude Code or Codex runs SePay CLI on its own, nobody is at the terminal to answer a confirmation prompt. The agent has to know whether it is on sandbox or production, which commands it must leave for you to run yourself, and where to read the result.

Before you hand the terminal to an agent

The environment comes from --env; without that flag it follows default_env in the configuration, and is sandbox when that isn't set. Check active_env in sepay --map=json before running anything. A sandbox-only command run with --env production stops with exit code 2 (for what happens when default_env is production, see Sandbox-only commands).

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.

These commands have confirms: terminal in sepay --map=json --env production: webhook create, webhook update, webhook delete, webhook replay, bank-account update, paycode create, paycode update and sepay api with a method other than GET, HEAD. On production the CLI runs such a command only with --env production on the command line, plus one of two things: a terminal to ask on where the user answers y, or a resource id together with --yes. Otherwise the CLI stops with exit code 2 before sending any request. Without a terminal the message contains ask the user to run this command in their own terminal; with a terminal it says how to fix the command (add --env production to the command…, run it without --yes, --json… and answer the prompt). On any of these the agent stops and hands you the command; it doesn't change the command as the message says. The CLI does not tell an agent from a script: a command with --env production, an id and --yes runs, whoever typed it. So the safeguard is that the agent never adds --yes: on this message the agent stops and hands you the exact command (without --yes) to run in your own terminal and answer y. Agreeing in the chat is not a reason for the agent to add --yes either. The full rule is in Production writes.

On sandbox (no real money), an agent may add --yes itself to a command that asks for confirmation, such as sandbox init --yes.

Scopes are checked on production only. A missing scope gives exit code 5: sign in again and grant that scope together with the ones you already have (Authentication).

Give each agent its own credentials: point SEPAY_CONFIG_DIR at a dedicated profile directory, or pick a profile with --profile <name>.

Add --json (or -o yaml) to get JSON results on stdout. Errors and warnings go to stderr; look exit codes up in the exit code table. Scripts shows how to read all three.

Rules for agents

Put these rules in the agent's instructions (for example CLAUDE.md or AGENTS.md):

  1. Always run with --no-input or --json, so a command fails right away instead of waiting for input.
  2. Always pass the xid and every required flag; don't rely on the terminal pickers.
  3. When rerunning a create command, reuse the same --idempotency-key as the previous run (Idempotency).
  4. Never add --env production or --yes to a command that changes data on production, even after the user agrees in the chat. Hand the command to the user to run. Exception: auth revoke --all and logout --all only end sign-in sessions and take --yes in every environment; ask the user first and add --yes only once they agree.
  5. Before a command that changes data on production, do a dry run with --dry-run and show the user the result (Dry run).
  6. On exit code 4, 5 or 8, or exit code 2 because a command needs confirmation, stop and tell the user.
ExitWhat the agent does
0Reads the result on stdout.
1Reads error_code. Retries only when the error code table says Yes, with a cap on attempts; otherwise tells the user.
2If message contains ask the user to run this command in their own terminal: stops and hands the exact command to the user to run in their own terminal. If message contains targets production or on production (needs confirmation, cannot confirm it): also stops and hands the command to the user; never drops --json or adds --env production or --yes itself. If message contains requires confirmation; pass --yes (on sandbox, and for auth revoke --all, logout --all in every environment): asks the user, and runs again with --yes once they agree. Any other error: fixes the arguments using --help.
3Stops and reports that the command isn't supported yet.
4Stops and asks the user to run sepay login.
5Stops and asks the user to sign in again and grant the missing scope.
6Reports that the handler didn't accept the notification; runs again once the handler is fixed.
8Stops; the user turns on Test mode or asks the company admin for the permission.
130The command was stopped part-way (interrupted): the user pressed Ctrl+C or Esc, or the process got SIGINT or SIGTERM. Doesn't rerun it; asks the user what to do next.

Exit codes and error codes gives the full meaning of each exit code.

A sample run

The agent is asked to delete a webhook on production. A sensible sequence:

The agent checks which environment is active and which profile is signed in:

$ sepay --map=json | jq '{active_env, authenticated, active_profile}'

The agent checks that the profile's session still works:

$ sepay auth status --active --json

The agent reads the command's notes before running it:

$ sepay webhook delete --help

The agent does a dry run so you can see which webhook would be deleted. The command sends nothing, it only reads that webhook:

$ sepay webhook delete <webhook-xid> --env production --dry-run --json

The agent runs the real command. With no terminal, the CLI stops with exit code 2 and deletes nothing:

$ sepay webhook delete <webhook-xid> --env production --json{"status": "error","error_code": "usage_error","message": "delete webhook on production needs confirmation; ask the user to run this command in their own terminal","exit_code": 2}

The agent stops and hands you the command, without adding --yes. You run it in your own terminal, check the xid and type y:

$ sepay webhook delete <webhook-xid> --env production! live: delete webhook <webhook-xid> targets PRODUCTIONenv: productiondelete webhook <webhook-xid> on production? [y/N] y✓ Deleted webhook <webhook-xid>.

See what each command does: sepay --map=json

This prints the whole command tree with details for every command: enough for an agent to tell which commands are sandbox-only, which scope each needs, and which delete something for good. A shortened example:

JSON
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
"name": "sepay",
"version": "x.x.x",
"active_env": "production",
"authenticated": true,
"active_profile": "agent-claude",
"commands": [
{
"path": "sepay webhook delete",
"short": "Delete a webhook",
"aliases": ["rm", "del"],
"args": "<webhook-xid>",
"implemented": true,
"envs": "both",
"destructive": "irreversible",
"confirms": "terminal",
"scope": "webhook:write"
}
]
}
FieldDescription
active_envThe current environment (sandbox or production).
authenticatedWhether the profile this run uses (--profile, then SEPAY_PROFILE, then the default profile) is signed in.
active_profileThe default profile on this machine: the first one you signed in with, or the one picked with sepay auth switch. It doesn't follow --profile or SEPAY_PROFILE; absent when the machine has no default profile.
commandsAn array of command objects, see Command object.

Command object

PropertyTypeMeaning
pathstringThe full command, for example sepay webhook delete.
shortstringA one-line description in English.
aliasesarrayShort names, such as rm, del.
argsstringPositional arguments. <webhook-xid>: in a terminal the CLI prompts when it is omitted; a non-interactive run must pass it (exit code 2 if missing). [webhook-xid]: optional, the command runs without it.
envsstringsandbox if the command refuses production, otherwise both.
scopestringThe OAuth scope required on production.
destructivestringirreversible if the command can't be undone.
confirmsstringComputed for the environment of the --map=json run (active_env). terminal (production only): a command that changes data on production, runs only when the user confirms it (rule). always: asks on sandbox too; without a terminal it needs --yes. conditional: some invocations ask. Field absent: the command doesn't ask.
guidancestringA human-readable note for agents.
flagsarrayFlag definitions (name, shorthand, type, desc, default, required). required: true marks a flag a non-interactive run must always pass; a flag required only with another flag's value states that condition in desc.
implementedboolfalse for a command that isn't supported yet: it is hidden from --help and exits 3.

See the production confirms with sepay --map=json --env production, the sandbox one with --env sandbox. For example, webhook delete is terminal on production and always on sandbox; sepay api is terminal on production and conditional on sandbox (only -X DELETE asks). A command without destructive can be undone but may still ask for confirmation, so an agent reads both fields before running it.

View the details of a single command on production:

$ sepay --map=json --env production | jq '.commands[] | select(.path == "sepay webhook delete")'

List the commands an agent must not run on its own on production:

$ sepay --map=json --env production | jq -r '.commands[] | select(.confirms == "terminal") | .path'

List the commands that delete something for good, so the agent always asks you before running one:

$ sepay --map=json | jq -r '.commands[] | select(.destructive == "irreversible") | .path'

Agent notes in --help

sepay <command> --help adds an Agent guidance block that sums up the environment, sign-in state, scope, confirmation and undo rules for that one command. Here is the block for sepay webhook delete on a machine that isn't logged in:

Code
1
2
3
4
5
6
7
8
9
[Agent guidance]
Active env: sandbox (no real money).
Not logged in: commands that read or write data exit 4 until you run `sepay login`.
More: sepay help glossary | exit-codes | errors; sepay --map=paths lists every command.
On production this needs the "webhook:write" scope: sepay auth refresh --scopes webhook:write
Irreversible: there is no command that undoes this. Confirm the target before running it.
Prompts in sandbox too; there, without a terminal it exits 2 until you pass --yes.
On production a write runs only with --env production on the command line (default_env does not count), and --yes confirms it only when the command names the resource it changes. Otherwise it exits 2: ask the user to run it in their own terminal. Do not add --env production or --yes to a write on the user's behalf.
Writing a handler? The event body, the signature headers and what to return: https://developer.sepay.vn/en/sepay-webhooks/tich-hop-webhook.

The Not logged in line shows only when no session is stored on the machine. The block in sepay --help replaces the More: line with a fuller list: sepay help glossary, sepay --map=paths and --map=json, sepay help exit-codes, sepay help errors, and a link to these docs.

The On production a write runs only… line appears on every command that changes data on production: the agent doesn't add --env production or --yes itself, it hands you the command to run. Read-only commands don't have this line.

Read the docs from the terminal

sepay help <topic> prints one topic as Markdown on stdout. The topics ship with the CLI you installed, so they always match the version you run:

TopicCovers
environmentEnvironment variables and config files the CLI reads
errorsEach error_code and what to do about it
exit-codesExit codes and when a retry makes sense
glossaryWhat pg, bankhub, paycode, va, quota and xid mean

sepay glossary prints the same topic. A wrong topic name exits with exit code 2 and lists the topics:

$ sepay help payloadError: unknown help topic "payload" (topics: environment, errors, exit-codes, glossary)Run 'sepay help --help' for usage.

Platform rules (payload fields, how to respond, the retry schedule, signatures) live on developer.sepay.vn. Append .md to a page URL to get its Markdown; llms.txt lists every page.

See also

To let Claude, ChatGPT or Codex read your SePay data without installing the CLI, connect SePay MCP.