Antom, leading provider of tailored payment solutions

Antom CLI user guide

Antom CLI is an API validation and debugging tool for Antom integration development. After connecting your merchant account, you can validate API requests and responses in the sandbox environment, with the CLI automatically handling authentication and request signing. You can also use the CLI to receive sandbox notifications, simulate callback scenarios, and diagnose sandbox payment requests. Business workflows should be implemented by integrating Antom APIs or SDKs into your application. It also supports transaction inquiries and reconciliation file retrieval. By default, the output is optimized for readability in the terminal, and JSON output is also supported for scripts and agents to process validation and query results.

Antom CLI use cases

Scenario

Goal

Feature entry

Getting started

Install or update Antom CLI

Installation and upgrade

Log in to your account and complete merchant configuration

Login and merchant configuration

Development and integration testing

Test in the sandbox environment

Query and troubleshoot failed or uncertain payment

Receive sandbox notifications locally and test different callback branches

Daily operations

Use report to verify transactions and retrieve reconciliation files

Reference

View command usage and configure autocomplete

Command help and auto-completion

Configure the CLI and choose the output format as needed

Output and configuration

Troubleshoot common questions

FAQs

Installation and update

Antom CLI now supports Windows, Linux, and macOS. Please select the corresponding terminal environment based on your operating system.

It is recommended to install via script. Run the following command in your terminal:

text
curl -fsSL https://mdn.alipayobjects.com/portal_4vwbay/uri/file/as/release/antom-cli-install.sh | bash

It is recommended to install via script. Run the following command in PowerShell:

powershell
irm https://mdn.alipayobjects.com/portal_4vwbay/uri/file/as/release/install.ps1 | iex

After installation, run the following commands to verify the installation. If the version number or help information is displayed correctly, the installation is successful.

text
antom version
antom --help

To update, rerun the installation command for your platform.

Login and merchant configuration

Before performing sandbox API validation, notification debugging, payment diagnostics, or reconciliation queries, connect your merchant account first. Run the following command in your terminal:

bash
antom login

Follow the prompts to log in to your Antom merchant account in the browser and complete authorization. The CLI saves the merchant configuration as a profile, and subsequent commands use the current profile by default.

Note: The current login process requires an administrator account. Accounts created by an administrator through the team management feature are not supported by the CLI for now.

After completion, you can view the current merchant identity and credential configuration status:

bash
antom whoami

Other login methods

  • In a remote terminal or automation tool, if browser authorization cannot be completed directly, you can split the authorization initiation and login completion into two steps.
  1. Run the following command to initiate authorization:
bash
antom login --non-interactive

This command outputs the browser authorization information. After the user completes confirmation in the browser, continue on the same machine with the same configuration and run the following command to complete login:

  1. Run the following command to log in:
bash
antom login --complete
  • If browser authorization is not available in the current environment, you can use interactive login instead:
bash
antom login --interactive

Follow the prompts to enter the Client ID, the file path of the merchant RSA private key, and the gateway URL.

To manually configure production credentials, use:

bash
antom login --interactive --live

Switch and manage merchant

Run antom login again to connect another merchant. Use the following commands to view and select saved profiles:

Action

Command

View all profiles

antom login list

Switch the default profile

antom login switch <profile>

View identity information for a specified profile

antom whoami --profile <profile>

Open Antom Dashboard

antom open

Clear the local configuration and credentials of the current profile

antom logout

Clear the local configuration and credentials of all profiles

antom logout --all

Replace <profile> with a name from the list. Business commands also support --profile, which allows you to specify a merchant for a single call without changing the default selection.

Sandbox API Validation

The following commands are used to validate payment and authorization, subscription and billing, and usage-based billing APIs in the sandbox environment. Use test orders, test customers, and test usage data to check request parameters, response results, and changes in test data status. This provides validation evidence for API or SDK integration in your application.

Payment and authorization

During sandbox integration testing, you can use the CLI to validate API requests for payment access, as well as subsequent capture, void, and refund processes. For existing transactions, you can query the results directly. After logging in, pass the request through command parameters or --data based on the integrated product and payment method.

Validate payment, capture, and refund APIs

Use pay to initiate a payment request directly. Use create-payment-session to prepare a payment session for Checkout Page or Payment Element. For subsequent operations, select the capture, void, or refund command according to the transaction status.

Feature

Command

Purpose

Consult payment methods

antom payments consult

Query available payment method information for a payment scenario

Create a payment

antom payments pay

Initiate a wallet, card, or other payment request

Create a payment session

antom payments create-payment-session

Prepare a payment session for Checkout Page or Payment Element

Capture

antom payments capture

Capture a payment that requires manual capture

Cancel

antom payments cancel

Cancel a payment

Refund

antom payments refund

Initiate a full or partial refund

Creating a payment or payment session requires preparing the request based on the integration product and payment method. Use antom help payments pay or antom help payments create-payment-session to view the full list of parameters.

Validate payment and refund query APIs

When a payment or refund request times out or no notification has been received yet, you can validate the query API by using the test request ID or the business ID returned by Antom, and verify the returned status. The sandbox test request to be queried can be initiated by either your application or the CLI. You do not need to create a new test transaction.

Feature

Command

Purpose

Inquire a payment

antom payments inquiry-payment

Query the status and information of a submitted payment request

Inquire a refund

antom payments inquiry-refund

Check the refund progress

For example, to query a sandbox payment that has already been initiated, replace YOUR_PAYMENT_REQUEST_ID with the merchant payment request ID:

bash
antom payments inquiry-payment --payment-request-id YOUR_PAYMENT_REQUEST_ID

Validate authorization and payment method saving APIs

Use authorizations when you need to obtain user authorization and manage authorization tokens. Use vaults when you need to save a payment method for future payments.

Feature

Command

Get the user authorization entry

antom authorizations consult

Apply for an authorization token

antom authorizations apply-token

Revoke authorization

antom authorizations revoke

Create a payment method saving session

antom vaults create-vaulting-session

Get the nonce required for saving a payment method

antom vaults fetch-nonce

Save a payment method

antom vaults vault-payment-method

Query the payment method saving result

antom vaults inquire-vaulting

Subscription and billing

During sandbox integration testing, use antom billing to manage customers, product prices, subscriptions, invoices, discounts, taxes, and customer credit balances. When developing a subscription business, you can first prepare customers, products, and prices, then create a subscription and initiate payment. For operations related to usage-based billing, see Usage-based billing.

In the tables below, the “Operation” is appended after the “Command group.” For example, combining antom billing subscriptions with retrieve gives:

Customer, product, price, and subscription

Resource

Command group

Operation

Purpose

Customer

antom billing customers

create · list · retrieve · update · delete · create-portal-link

Maintain customer profiles and generate customer self-service portal links

Product

antom billing products

create · list · retrieve · update · upload-image

Manage product information and images

Price

antom billing prices

create · list · retrieve · update

Configure one-time, recurring, or usage-based pricing rules

Subscription

antom billing subscriptions

create · list · retrieve · update · resume · cancel

Create subscriptions, adjust subscription items or pause settings, and resume or cancel subscriptions

Subscription payments can be initiated through antom billing pay, or by creating a payment session via antom billing payment-sessions create. The customer self-service portal allows customers to manage subscriptions, view bills, and manage payment methods.

Invoice, receipt, discount, and tax

Resource

Command group

Operation

Purpose

Invoice

antom billing invoices

create · list · retrieve · update · finalize · send · create-view-link · confirm-payment · revise · void · mark-uncollectible · export

Issue, send, and adjust invoices; record payments; export invoices

Receipt

antom billing receipts

list · retrieve · send · export

Query, send, and export receipts

Credit note

antom billing credit-notes

create · list · retrieve · void

Create, query, or void credit notes

Coupon

antom billing coupons

create · list · retrieve · update

Manage discount rules

Promotion code

antom billing promotion-codes

create · list · retrieve · update

Manage promotion codes that users can redeem

Tax settings

antom billing tax-settings

initialize · retrieve · update

Initialize and maintain tax configurations

Tax registration

antom billing tax-registrations

create · list · update-period · cancel

Maintain tax registrations and their validity periods

Tax calculation

antom billing tax-calculations

create · retrieve

Calculate tax and query calculation results

Tax transaction

antom billing tax-transactions

list

Query tax transaction records

After a draft invoice is finalized with finalize, you can send it to the customer with send, or obtain a view link with create-view-link. confirm-payment is used to record offline payments that have already been received. It does not initiate a charge.

Customer credit

Customer credits can be used for invoice deduction scenarios such as trial credits or customer compensation.

Resource

Command group

Operation

Purpose

Customer credit

antom billing credit-grants

create · list · retrieve · update-expiry · void

Grant credits, adjust expiration dates, or void credits

Usage-based billing

During sandbox integration testing, when charging based on the number of API calls, service usage, or other usage metrics, you can create a Meter to record and aggregate customer usage, and use it together with product prices to configure usage-based billing rules.

In the table below, the “Operation” is appended after the “Command group.” For example: antom billing meters create.

Resource

Command group

Operation

Purpose

Meter

antom billing meters

create · list · retrieve · update

Create, query, modify, or deactivate meters

Usage upload session

antom billing meter-event-sessions

create

Create a session for batch usage upload

Usage event

antom billing meter-events

create

Upload customer usage such as API call counts or service usage

For usage upload, create an upload session first, then use that session to upload events.

Transaction and reconciliation query

To verify a single transaction, use the transaction detail query. To obtain reconciliation materials for a billing period, use the reconciliation file query. Both types of queries require logging in to the merchant account first.

Query a single transaction

Replace YOUR_TRANSACTION_ID with the transaction ID to be checked, and view the transaction details:

bash
antom report transaction-detail --transaction-id YOUR_TRANSACTION_ID

When querying production transactions, add --live to the end of the command.

Retrieve reconciliation files

Replace the date with the billing date you want to query, and retrieve the download URLs for available reconciliation files:

bash
antom report download-list --date 20261001 --bill-type SETTLEMENT_DETAIL

--date supports a single day or a date range, such as 20260901-20260930.

  • To display all returned records in the terminal, add --all.
  • To save the query results, use --json.

Diagnose payment requests

During sandbox integration testing, when a payment request fails or the returned result is not as expected, use integration diagnose to obtain diagnostic results and handling suggestions. If the test request times out and you need to confirm the test order status, call the inquiryPayment API first.

After logging in, replace the example ID with the sandbox payment request ID to be diagnosed:

bash
antom integration diagnose --request-id YOUR_PAYMENT_REQUEST_ID

The diagnostic results can help identify issues related to parameters, merchant configuration, and payment capabilities.

If you need to troubleshoot the CLI’s own request process, add --debug to the corresponding command. For example:

bash
antom integration diagnose --request-id YOUR_PAYMENT_REQUEST_ID --debug

--debug outputs diagnostic logs to standard error, while the business result is still output to standard output. You can save the logs separately, or use --json to pass the diagnostic results to other tools.

Listen for sandbox notifications

During local development, you can use antom notification listen to receive sandbox notifications and forward them to your local Webhook endpoint, even if you do not have a public IP address.

First, log in to your merchant account and start your local receiving service. Replace the following URL with your actual receiving endpoint, then run:

bash
antom notification listen --forward-to http://localhost:8080/webhook

After submitting a sandbox test request through the test application or another terminal, the CLI displays the received notification and forwards it to that address. Combined with application logs, you can verify notification receiving, signature verification, and test order status update logic.

If you only care about payment and refund results, you can filter notification types:

bash
antom notification listen --events PAYMENT_RESULT,REFUND_RESULT --forward-to http://localhost:8080/webhook

Remove --forward-to if you only want to observe notifications in the terminal. Press Ctrl+C to stop listening. Your application should verify signatures using the corresponding Antom sandbox public key.

--events uses the notification type names listed in the table below. Separate multiple types with commas. If this parameter is not passed, all supported types are listened to. The dispute-related entries in the table are notification events provided for applications to verify callback handling.

Notification

Notification type (--events)

Payment result

PAYMENT_RESULT

Payment pending

PAYMENT_PENDING

Capture result

CAPTURE_RESULT

Refund result

REFUND_RESULT

Authorization code created

AUTHORIZATION_AUTHCODE_CREATED

Authorization token created

AUTHORIZATION_TOKEN_CREATED

Authorization token canceled

AUTHORIZATION_TOKEN_CANCELED

Dispute created notification

DISPUTE_CREATED

Dispute judged notification

DISPUTE_JUDGED

Dispute canceled notification

DISPUTE_CANCELLED

Defense material submitted notification

DISPUTE_DEFENSE_SUPPLIED

Subscription created

SUBSCRIPTION_CREATE

Subscription changed

SUBSCRIPTION_CHANGE

Subscription canceled

SUBSCRIPTION_CANCEL

Subscription terminated

SUBSCRIPTION_TERMINATE

You can also use antom notification listen --list to view the notification types supported by the current version.

Simulate notifications

When you need to verify callback handling branches such as payment failure, refund, or dispute events, you can use antom notification simulate to send simulated notifications for specified scenarios to a local test endpoint. Dispute-related scenarios are used to verify the application’s logic after receiving notifications, without performing the corresponding business operations.

After logging in and starting your local Webhook endpoint, replace the URL with your actual receiving endpoint. For example, to verify payment failure handling:

bash
antom notification simulate payment.failed --forward-to http://localhost:8080/webhook

By default, the command uses the logged-in sandbox profile to obtain the notification signature, then sends the notification to the specified URL. Your application can use the same sandbox signature verification flow to check whether the failure branch works as expected.

Simulated notifications do not create transactions or change Antom order status.

Scenario

Scenario name

Payment succeeded notification

payment.succeeded

Payment failed notification

payment.failed

Payment pending notification

payment.pending

Capture succeeded or failed notification

payment.capture.succeeded · payment.capture.failed

Refund succeeded notification

payment.refund.succeeded

Dispute created, judged, or canceled notification

payment.dispute.created · payment.dispute.judged · payment.dispute.cancelled

Dispute defense material submitted notification

payment.dispute.defense.supplied

Replace payment.failed in the example with another scenario name to switch the test case. Use --data to override business fields in the template, such as associating the notification with a local test order. Use antom notification simulate --list to view supported simulation scenarios.

Command help and auto-completion

Use antom --map to view the complete command tree. When looking for a specific feature, you can view help for command groups, resources, and operations step by step:

bash
antom billing --help
antom billing subscriptions --help
antom billing subscriptions create --help

For API commands, --help shows commonly used parameters, while antom help <command path> shows the complete request parameters. For example:

bash
antom help payments pay

The CLI supports shell completion for terminals such as Bash, Zsh, and PowerShell. Run antom completion --help and follow the instructions for your terminal to enable completion. After completion is enabled, you can use Tab to complete commands and parameters.

Output and configuration

Antom CLI supports controlling the output format, colors, layout, and runtime configuration through command-line arguments, environment variables, and configuration files.

Note: When the same setting is provided from multiple sources, the following precedence applies: command-line arguments > environment variables > configuration file > default values. Only sources that support the corresponding setting participate in overriding. For example, --color can override the color settings in environment variables and configuration files. Command-line arguments only affect the current invocation and are not written back to the configuration file.

Output format, color, and formattin

--json selects the output format, --color controls color, and --pretty controls JSON formatting. These three settings are configured separately.

Parameter

Default behavior

Optional settings and relationship

--json

Uses output suitable for terminal reading

Outputs JSON when added; business APIs retain the complete fields returned by the server.

--color

auto: colored in terminals, no color in pipes and files

on forces color, off disables color; applies to both default output and JSON.

--pretty

on: formats JSON

off outputs raw JSON; does not change color or non-JSON output.

Therefore, using --json directly in the terminal returns formatted JSON with colors. When redirecting the output to a file, formatting is kept by default and colors are removed. For example, to save the sandbox payment inquiry result as a JSON file:

bash
antom payments inquiry-payment --payment-request-id YOUR_PAYMENT_REQUEST_ID --json > payment-result.json

The above describes the behavior under the default configuration. The notification stream notification listen --json always outputs one notification per line, making it easy to process notifications one by one.

Configuration file

After login, the CLI saves merchant configurations in config.toml. The default locations are as follows:

SystemDefault path

macOS / Linux

~/.config/antom/config.toml

Windows

%LOCALAPPDATA%/antom/config.toml

When XDG_CONFIG_HOME is set, the default location is antom/config.toml under that directory. You can also specify the file through --config or ANTOM_CONFIG.

To persist color and JSON formatting preferences, set the following at the top level of the existing configuration file:

text
color = "auto"
pretty = "on"

color can be auto, on, or off; pretty can be on or off. Merchant configurations are managed through the login command series.

Environment variables

Environment variables are suitable for setting default values for terminal sessions or scripts without modifying the configuration file.

Variable

Purpose

Example value

ANTOM_PROFILE

Selects a saved profile

my-merchant

ANTOM_CONFIG

Specifies the configuration file path

/path/to/config.toml

ANTOM_DEBUG

Enables diagnostic logs

true

NO_COLOR

Disables output color

Set this variable

FORCE_COLOR

Forces output color

Set this variable

For example, select a merchant for the current session in a macOS / Linux terminal:

bash
export ANTOM_PROFILE=my-merchant
antom whoami

When both NO_COLOR and FORCE_COLOR are set, NO_COLOR takes precedence. Explicitly specifying --color can override both. --json, --pretty, and --live do not have corresponding environment variables.

Other global parameters

Parameter

Purpose

--debug

Outputs diagnostic logs to standard error, while business results are still output to standard output.

--profile <profile>

Selects the merchant configuration used for the current invocation.

--config <path>

Specifies the configuration file read for the current invocation.

--live

Use the production environment for this invocation. If not specified, the test sandbox environment is used by default.

FAQs

After installation, the command antom is not found. What should I do?

Reopen the terminal. If it still says the command cannot be found, check whether the installation directory has been added to PATH. When using the default installation directory, you can first set it in the current terminal:

bash
# Linux/MacOS (only effective for the current shell session)
export PATH="/usr/local/bin:$PATH"

# Windows PowerShell (only effective for the current PowerShell session)
$env:Path += ";$env:LOCALAPPDATA\Antom\bin"

If you specified another directory during installation, replace it with the actual directory. The above settings only take effect for the current terminal session. For long-term use, add the directory to your Shell configuration or the system PATH. Then run antom version to confirm that the command is available.

Why is authorization not completed after running non-interactive login?

antom login --non-interactive only initiates authorization and outputs authorization information. You need to first confirm authorization in the browser as prompted, then return to the same machine and use the same configuration to complete login:

bash
antom login --complete

What should I do if the profile does not exist?

First run antom login list to view the merchant configurations saved on this machine, then select a name from the list:

bash
antom login switch <profile>

Replace <profile> with the actual name. If the merchant has not been saved yet, run antom login first. If the command uses --profile or the terminal has ANTOM_PROFILE set, you also need to confirm that the name is correct.

How can I make commands output JSON for easier script analysis?

Add --json after the command. For example:

bash
antom whoami --json

JSON is formatted by default. To output compact JSON, add --pretty off. For color and formatting settings, see Output format, color, and formatting.