Antom, leading provider of tailored payment solutionsAntom, leading provider of tailored payment solutions

Antom CLI user guide

Antom CLI is a command-line tool provided by Antom. It helps merchant developers complete operations such as login authorization, merchant profile management, report queries, and payment integration diagnostics directly from the terminal.

Features

  • Browser-based authorization login: Supports login through the default browser, as well as non-interactive login suitable for Agent/CI scenarios.
  • Multiple profile management: Supports saving multiple merchant profiles on the same machine and switching the current active profile.
  • Test/Live environment switching: Uses the test environment by default. Use --live to switch to the live environment.
  • Report queries: Supports querying bill file download URLs for a specified date or date range, as well as querying details of a single transaction.
  • Integration diagnostics: Supports diagnosing the cause of failed payment requests based on the paymentRequestId in the payment request.
  • Dual output modes: Outputs human-readable text by default, and also supports structured JSON output with --json.

Before you begin

Before using Antom CLI, make sure you meet the following requirements:

Installation

Currently, the Antom CLI installation script only supports macOS.

Install via script Recommended

Run the following command in your terminal:

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

After installation, run the following commands to verify the installation:

copy
antom version
antom --help

If the version number or help information is displayed correctly, the installation is successful. If your terminal reports that the antom command does not exist, run the following command to ensure that the installation directory has been added to PATH:

copy
export PATH="$HOME/.local/bin:$PATH"

Quick start

Step 1: Login authorization

Antom CLI provides multiple login methods for different scenarios:

Recommended for local development environments. After the command is executed, the CLI opens your default browser and guides you through Antom authorization.

copy
antom login

Step 2: View current identity

Use the following command to view the current merchant identity and login environment:

copy
antom whoami

Step 3: Query report download URLs

Antom CLI supports querying report download URLs within a specified date range. The returned links can be used directly to download reconciliation reports.

copy
# Query bills for a specified date
antom report download-list --date 20260601 --bill-type SETTLEMENT_DETAIL

# Query bills for a date range
antom report download-list --date 20260601-20260630 --bill-type SETTLEMENT_DETAIL

Step 4: Diagnose failed payment requests

When a payment request fails, you can use the following command to quickly diagnose the cause. This is useful during development and debugging.

copy
antom integration diagnose --request-id PAY_202606151234

Command reference

Global parameters

The following parameters apply to all Antom CLI commands for controlling general behavior and environment settings:

Parameter

Description

--profile <name>

Specify the profile to use for the current command. If not provided, the active profile is used.

--live

Use the live environment. The test environment is used by default.

--json

Output JSON that can be parsed by programs.

--debug

Outputs diagnostic logs to stderr. You can also enable this by setting ANTOM_DEBUG=1.

--color <auto|on|off>

Control color output. The default value is auto.

--help

Display command help.

Login commands

login (Login Authorization

Used to complete login authorization for the Antom CLI. Command format:

copy
antom login [flags]

Include the following parameters:

Parameter

Description

--non-interactive

Initiate a non-interactive browser authorization, output the authorization information, and then exit.

--complete

Complete a pending authorization initiated via --non-interactive. 

--interactive

Log in using manual credentials.

The login process is as follows:

  1. The CLI starts browser authorization or reads the manual credentials entered by the user.
  2. The user completes authorization in the browser, or enters the client ID and the merchant RSA private key.
  3. The CLI verifies the authorization or credentials.
  4. After authorization succeeds, the CLI saves the profile and credentials locally.
  5. The newly logged-in profile becomes the active profile.

logout (Logout)

Used to delete the local profile and clear local credentials.

copy
antom logout
antom logout --all

Note:

  • If --all is not specified, the current active profile is deleted.
  • If --all is specified, all local profiles are deleted.

whoami (Current identity)

Used to display the current local Antom CLI identity.

copy
antom whoami
antom whoami --json

login list (Profile list)

Used to list all local profiles.

copy
antom login list
antom login list --json

login switch (Switch profile)

Used to switch the active profile. Subsequent commands that do not explicitly specify --profile will use this profile.

copy
antom login switch my-merchant

Report commands

report download-list (Report download URLs)

Used to query the downloadable billing file URLs for a specified date or date range. The bill type must be specified using --bill-type.

copy
antom report download-list --date 20260601 --bill-type SETTLEMENT_DETAIL
antom report download-list --date 20260601-20260630 --bill-type SETTLEMENT_DETAIL
antom report download-list --date 20260601 --bill-type SETTLEMENT_SUMMARY --json

Include the following parameters:

Parameter

Description

--date/-d

Billing date, in the format YYYYMMDD or YYYYMMDD-YYYYMMDD.

--bill-type

Bill type, such as SETTLEMENT_DETAIL, SETTLEMENT_SUMMARY or TRANSACTION_DETAIL.

--all

Displays the complete results in user-facing output.

report transaction-detail (Transaction details)

Used to query the details of a single Antom transaction.

copy
antom report transaction-detail --transaction-id 20260518993030096600502796446525944
antom report transaction-detail -t 20260518993030096600502796446525944 --json

Include the following parameters:

Parameter

Description

--transaction-id / -t

The transaction ID to query.

Integration commands

integration diagnose (Integration diagnosis)

Diagnose the cause of an error in a payment request. The input parameter is the paymentRequestId from the payment request, passed using --request-id.

copy
antom integration diagnose --request-id PAY_202606151234
antom integration diagnose --live --request-id PAY_202606151234
antom integration diagnose --request-id PAY_202606151234 --json

Include the following parameters:

Parameter

Description

--request-id

The paymentRequestId from the payment request.

Other commands

open (Open Antom Dashboard)

Quickly open the Antom Dashboard in the default browser, making it easy to view business data and manage configurations online.

copy
antom open

version (Version information)

Used to view the currently installed Antom CLI version information, which helps troubleshoot compatibility issues or confirm tool updates.

copy
antom version
antom version --json

Troubleshooting

Common troubleshooting methods for Antom CLI include adjusting CLI behavior through environment variables, viewing command help, and enabling debug logs to locate issues.

Environment variables

The following environment variables can be used to control the default profile, debug logs, and color output of Antom CLI.

Variable

Description

ANTOM_PROFILE

Specify the default profile name.

ANTOM_DEBUG

Enable debug logs.

NO_COLOR

Disable color output.

FORCE_COLOR

Force color output to be enabled.

View command help

If you are unsure about the usage of a command, the meaning of a parameter, or the supported options, you can use --help to view the help information.

copy
antom --help
antom login --help
antom report download-list --help
antom integration diagnose --help

Enable debug mode

When you need to troubleshoot command execution errors or view more detailed diagnostic information, you can enable debug mode using the --debug parameter.

copy
antom report download-list --date 20260601 --bill-type SETTLEMENT_DETAIL --debug

You can also enable debug logs by setting the ANTOM_DEBUG=1 environment variable:

copy
ANTOM_DEBUG=1 antom whoami

FAQs

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

Verify that Antom CLI's installation directory has been added to your PATH.

copy
export PATH="$HOME/.local/bin:$PATH"
antom version

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

Non-interactive login requires you to first initiate authorization and then complete it.

copy
# Step 1: Initiate non-interactive authorization
antom login --non-interactive

# Step 2: Complete the pending authorization
antom login --complete

What should I do if the profile does not exist?

First check the list of merchant profiles saved locally, and then switch to an existing profile.

copy
# View local profiles
antom login list

# Switch to an existing profile
antom login switch my-merchant

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

Commands that support structured output can use --json, which makes them easier to parse in scripts.

copy
antom whoami --json
antom report download-list --date 20260601 --bill-type SETTLEMENT_DETAIL --json
antom integration diagnose --request-id PAY_202606151234 --json