# Airwallex CLI

Work with your Airwallex account from the command line

The Airwallex CLI lets you work with your Airwallex account directly from a command line. It exposes a broad slice of the Airwallex API as terminal commands, so you can read and write your Airwallex resources in sandbox or production, script repeatable tasks, and wire Airwallex into automated systems — without writing an HTTP client. The CLI connects to sandbox by default; pass `--prod` when you are ready to work against your production account.

Use the CLI when you want to:

- **Explore the API interactively** — discover endpoints, preview requests, and inspect schemas before you commit to a full integration.
- **Power AI coding agents** — let agents that can run terminal commands (for example, Claude Code, Cursor, and Codex) operate against your account. This is also the foundation of [Airwallex AgentOS](https://www.airwallex.com/docs/developer-tools/ai/agentos.md).

The CLI is compatible with macOS and Linux.

> **\[WARNING]**
>
> Card and Issuing commands require additional permissions. If you receive a 403 error when accessing these resources, contact [Customer Support](https://help.airwallex.com/hc/en-gb/requests/new) to enable access for your account.

## Who can install

As the Airwallex CLI requires OAuth authorization, only users with the **Owner**, **Admin**, or **Finance Admin** role on the Airwallex account can authorize the CLI. Other roles will not be able to complete the OAuth authorization flow. Refer to [User roles that can grant OAuth consent](https://www.airwallex.com/docs/developer-tools/partner-connections/oauth-permissions#user-roles-that-can-grant-oauth-consent.md) for more details.

## Before you begin

- macOS or Linux.
- `curl` installed and available in your shell.
- Write access to `~/.local/bin`. If you previously ran an installation command with `sudo`, restore ownership before continuing — see [Troubleshooting](#troubleshooting).

## Install

Download and install the CLI. The script auto-detects your OS and architecture and installs to `~/.local/bin/airwallex`:

```shell
curl -fsSL https://static.airwallex.com/developer-tools/airwallex-cli/install.sh | sh
```

### Enable shell completion

Install a shell completion script so your terminal can autocomplete CLI commands and flags.

```shell
# Find instructions to enable autocomplete for ZSH
airwallex completion zsh --help
```

## Authenticate

After installation, sign in to your Airwallex account.

### Log in to sandbox

By default, the CLI connects to the [sandbox environment](https://www.sandbox.airwallex.com/app/login/sandbox?region=global). Complete the authentication and authorization flow in the browser that opens:

```shell
airwallex auth login
```

> **\[INFORMATIONAL]**
>
> `airwallex auth whoami` reports the sandbox base URL as `https://api-demo.airwallex.com`. This is an alias for `https://api.sandbox.airwallex.com`, the hostname used throughout the documentation. Both address the same sandbox environment.

### Log in to production

To connect to your production Airwallex account, pass the `--prod` flag:

```shell
airwallex auth login --prod
```

### Log in with scoped access

You can limit the CLI access to specific API scopes. See [OAuth scopes](https://www.airwallex.com/docs/developer-tools/partner-connections/oauth-scopes.md) for the full list of available scopes.

```shell
airwallex auth login --prod --scope=balance:read
```

### Check authentication status

Verify which environment you are connected to and whether you are signed in:

```shell
airwallex auth whoami
```

### Send feedback

Open your default email client to send feedback to the Airwallex team:

```shell
airwallex feedback "Can you please add support for listing <resource> from my organization?"
```

## Agent usage

### Discover the CLI surface

List every available command and sub-command, including a short description for each:

```shell
airwallex --tree
```

Show only the commands under a specific resource (with descriptions):

```shell
airwallex --tree invoices
```

### Preview API requests

Review the API request corresponding to a resource command before executing it:

```shell
airwallex --dry-run products list
```

### Compact JSON output

Return compact JSON for efficient consumption by scripts or agents:

```shell
airwallex --compact meters list --page-size=1
```

### Write actions with confirmation

Write actions require confirmation in interactive mode by default. Override when you know what you are doing — for example, in a non-interactive script or pipeline:

```shell
echo '{
  "name": "Demo product — ceramic coffee mug (12 oz)",
  "description": "Example catalog item for testing the CLI. Not a real product or offer.",
  "request_id": "ceramic-coffee-mug-245abe6"
}' | airwallex --confirm products create --data-stdin
```

### Discover API schemas

View the schema of the API endpoint invoked by a given resource command:

```shell
airwallex products update --api-schema-only
```

For the full command reference, run `airwallex -h`.

## Use the CLI with AI agents

AI coding agents that can run terminal commands — for example, Claude Code, Cursor, and Codex — can call the CLI on your behalf to read and act on your account. Download Skills from the [Airwallex AgentOS plugin](https://www.airwallex.com/docs/developer-tools/ai/agentos.md) for pre-built workflows on Airwallex.

When agents use the CLI, the safety guardrails still apply: money-out actions (transfers, FX conversions, payouts) are not initiated on your behalf by default, and write actions require confirmation unless `--confirm` is passed.

## Deauthorize and uninstall

### Sign out of the CLI

To sign out of the Airwallex CLI and remove the credentials stored on your machine, run:

```shell
airwallex auth logout
```

This command clears the locally stored OAuth tokens for your current Airwallex CLI session. It does not revoke or invalidate the token itself.

A few things to note:

- The CLI stores only one set of credentials at a time.
- Running `login` again replaces the previous saved credentials.
- Running `logout` only removes credentials from your local environment.

### Revoke the OAuth token

If you want to fully revoke the OAuth token used by the CLI, do that in the Airwallex web app instead:

[Manage your connections in the Airwallex web app](https://airwallex.com/app/integrations/home)

Use the CLI command when you want to sign out locally. Use the web app when you want to revoke the token completely.

### Uninstall the CLI

After logging out, remove the binary:

```shell
rm ~/.local/bin/airwallex
```

## Troubleshooting

### Cannot write to `~/.local/bin`

**Symptom:** The installer fails because `~/.local` is not writable.

**Cause:** This happens when `$HOME` is not set in your shell environment (causing the install path to resolve incorrectly), or when `~/.local` is owned by `root` — usually from a previous `sudo` command.

**Fix:** Restore ownership of the directory, then [reinstall the CLI](#install):

```shell
sudo chown -R $(whoami) ~/.local
```

## Telemetry

Telemetry is enabled by default. You can disable telemetry either globally using the `DISABLE_TELEMETRY` environment variable or for a specific command execution using the `--no-telemetry` global CLI option.

When enabled, the CLI collects basic device information (OS, architecture) and usage metrics related to command execution (command name, error code, latency, exit code).

## See also

- [Airwallex AgentOS](https://www.airwallex.com/docs/developer-tools/ai/agentos.md) — the production-grade agent toolkit built on the CLI, with pre-built skills and one-step plugins.
- [OAuth scopes](https://www.airwallex.com/docs/developer-tools/partner-connections/oauth-scopes.md) — limit CLI access to specific API operations.
- [API reference](/api) — the full Airwallex API the CLI is built on.