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 | |
Log in to your account and complete 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 | |
Reference | View command usage and configure autocomplete | |
Configure the CLI and choose the output format as needed | ||
Troubleshoot common questions |
Installation and update
Antom CLI now supports Windows, Linux, and macOS. Please select the corresponding terminal environment based on your operating system.
Linux/MacOS
It is recommended to install via script. Run the following command in your terminal:
curl -fsSL https://mdn.alipayobjects.com/portal_4vwbay/uri/file/as/release/antom-cli-install.sh | bashWindows PowerShell
It is recommended to install via script. Run the following command in PowerShell:
irm https://mdn.alipayobjects.com/portal_4vwbay/uri/file/as/release/install.ps1 | iexAfter installation, run the following commands to verify the installation. If the version number or help information is displayed correctly, the installation is successful.
antom version
antom --helpTo 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:
antom loginFollow 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:
antom whoamiOther 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.
- Run the following command to initiate authorization:
antom login --non-interactiveThis 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:
- Run the following command to log in:
antom login --complete- If browser authorization is not available in the current environment, you can use interactive login instead:
antom login --interactiveFollow 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:
antom login --interactive --liveSwitch 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 |
|
Switch the default profile |
|
View identity information for a specified profile |
|
Open Antom Dashboard |
|
Clear the local configuration and credentials of the current profile |
|
Clear the local configuration and credentials of all profiles |
|
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 |
| Query available payment method information for a payment scenario |
Create a payment |
| Initiate a wallet, card, or other payment request |
Create a payment session |
| Prepare a payment session for Checkout Page or Payment Element |
Capture |
| Capture a payment that requires manual capture |
Cancel |
| Cancel a payment |
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 |
| Query the status and information of a submitted payment request |
Inquire a 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:
antom payments inquiry-payment --payment-request-id YOUR_PAYMENT_REQUEST_IDValidate 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 |
|
Apply for an authorization token |
|
Revoke authorization |
|
Create a payment method saving session |
|
Get the nonce required for saving a payment method |
|
Save a payment method |
|
Query the payment method saving result |
|
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 |
|
| Maintain customer profiles and generate customer self-service portal links |
Product |
|
| Manage product information and images |
Price |
|
| Configure one-time, recurring, or usage-based pricing rules |
Subscription |
|
| 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 |
|
| Issue, send, and adjust invoices; record payments; export invoices |
Receipt |
|
| Query, send, and export receipts |
Credit note |
|
| Create, query, or void credit notes |
Coupon |
|
| Manage discount rules |
Promotion code |
|
| Manage promotion codes that users can redeem |
Tax settings |
|
| Initialize and maintain tax configurations |
Tax registration |
|
| Maintain tax registrations and their validity periods |
Tax calculation |
|
| Calculate tax and query calculation results |
Tax transaction |
|
| 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 |
|
| 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 |
|
| Create, query, modify, or deactivate meters |
Usage upload session |
|
| Create a session for batch usage upload |
Usage event |
|
| 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:
antom report transaction-detail --transaction-id YOUR_TRANSACTION_IDWhen 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:
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:
antom integration diagnose --request-id YOUR_PAYMENT_REQUEST_IDThe 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:
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:
antom notification listen --forward-to http://localhost:8080/webhookAfter 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:
antom notification listen --events PAYMENT_RESULT,REFUND_RESULT --forward-to http://localhost:8080/webhookRemove --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 ( |
Payment result |
|
Payment pending |
|
Capture result |
|
Refund result |
|
Authorization code created |
|
Authorization token created |
|
Authorization token canceled |
|
Dispute created notification |
|
Dispute judged notification |
|
Dispute canceled notification |
|
Defense material submitted notification |
|
Subscription created |
|
Subscription changed |
|
Subscription canceled |
|
Subscription terminated |
|
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:
antom notification simulate payment.failed --forward-to http://localhost:8080/webhookBy 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 failed notification |
|
Payment pending notification |
|
Capture succeeded or failed notification |
|
Refund succeeded notification |
|
Dispute created, judged, or canceled notification |
|
Dispute defense material submitted notification |
|
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:
antom billing --help
antom billing subscriptions --help
antom billing subscriptions create --helpFor API commands, --help shows commonly used parameters, while antom help <command path> shows the complete request parameters. For example:
antom help payments payThe 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 |
| Uses output suitable for terminal reading | Outputs JSON when added; business APIs retain the complete fields returned by the server. |
|
|
|
|
|
|
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:
antom payments inquiry-payment --payment-request-id YOUR_PAYMENT_REQUEST_ID --json > payment-result.jsonThe 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:
| System | Default path |
macOS / Linux |
|
Windows |
|
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:
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 |
| Selects a saved profile |
|
| Specifies the configuration file path |
|
| Enables diagnostic logs |
|
| Disables output color | Set this variable |
| Forces output color | Set this variable |
For example, select a merchant for the current session in a macOS / Linux terminal:
export ANTOM_PROFILE=my-merchant
antom whoamiWhen 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 |
| Outputs diagnostic logs to standard error, while business results are still output to standard output. |
| Selects the merchant configuration used for the current invocation. |
| Specifies the configuration file read for the current invocation. |
| 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:
# 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:
antom login --completeWhat 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:
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:
antom whoami --jsonJSON is formatted by default. To output compact JSON, add --pretty off. For color and formatting settings, see Output format, color, and formatting.