# 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:

-   You already have an [Antom merchant account](https://docs.antom.com/ac/merchant_service/merchant_onboard.md). If you do not have an account yet, go to the [Contact us](https://www.antom.com/contact-us?secondary=Antom_Docs) to register or contact Antom technical support.
-   You have enabled Antom CLI login authorization permission. This feature is currently available only to selected allowlisted merchants. To request CLI access, contact [pub\_antom\_integration\_service@antom.com](mailto:pub_antom_integration_service@antom.com).

## Installation

Currently, the Antom CLI installation script only supports macOS.

### Install via script Recommended

Run the following command in your terminal:

```bash
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:

```bash
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`:

```bash
export PATH="$HOME/.local/bin:$PATH"
```

## Quick start

### Step 1: Login authorization

Antom CLI provides multiple login methods for different scenarios:

#### Tab: Browser login

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

```bash
antom login
```

#### Tab: Non-interactive login

Suitable for Agent, CI/CD pipelines, and other automation scenarios where no manual interaction is required. This process consists of two steps:

```bash
# Step 1: Initiate authorization and obtain the authorization code
antom login --non-interactive

# Step 2: Complete login using the authorization code
antom login --complete
```

#### Tab: Manual credential login

Suitable for scenarios where a browser is unavailable or the environment is restricted.

```bash
antom login --interactive
```

Antom CLI logs in to the test environment by default. To operate on live environment data, you need to configure live environment credentials separately.

```bash
antom login --live --interactive
```

### Step 2: View current identity

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

```bash
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.

```bash
# 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.

```bash
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:

```bash
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.

```bash
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.

```bash
antom whoami
antom whoami --json
```

#### `login list` (Profile list)

Used to list all local profiles.

```bash
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.

```bash
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`.

```bash
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.

```bash
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`.

```bash
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](https://dashboard.antom.com/) in the default browser, making it easy to view business data and manage configurations online.

```bash
antom open
```

#### `version` (Version information)

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

```bash
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.

```bash
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.

```bash
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:

```bash
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`.

```bash
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.

```bash
# 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.

```bash
# 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.

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