MaxCompute:MaxCompute CLI

Installation and verification

maxc is distributed through the Alibaba Cloud CLI. To use maxc, you must install or update the Alibaba Cloud CLI.

• Supported operating systems

  Operating system	Supported versions	Supported architectures
  Linux	CentOS 8+, RHEL 8+, Ubuntu 16.04+, Debian 9+, and other major distributions. CentOS 7 has reached EOL and is not recommended.	x86_64 (64-bit), ARM64
  macOS	macOS 11 (Big Sur) or later	Intel and Apple silicon (Universal binary)
  Windows	Windows 10 and later (64-bit)	x86_64 only. 32-bit and ARM64 are not supported.

• Select the tab for your operating system and follow the installation steps. Multiple methods are available — choose one.

  Linux

  Install using a Bash script (Recommended)

  The following options are supported:

  • Install the latest version

    If you do not specify a version, the script automatically installs the latest version.

    /bin/bash -c "$(curl -fsSL https://aliyuncli.alicdn.com/install.sh)"

  • Install a previous version

    Use the -V option to specify the version to install. To view available previous versions, go to the GitHub Releases page.

    /bin/bash -c "$(curl -fsSL https://aliyuncli.alicdn.com/install.sh)" -- -V 3.3.18

  Install from a TGZ package (.tar.gz)

  1. Download the installation package.

     • Download the latest version:

       Note

       Run uname -m to check your Linux system architecture. If the terminal output is arm64 or aarch64, your system has an ARM64 architecture. Other outputs indicate an AMD64 architecture.

       • For AMD64 systems:

         curl https://aliyuncli.alicdn.com/aliyun-cli-linux-latest-amd64.tgz -o aliyun-cli-linux-latest.tgz

       • For ARM64 systems:

         curl https://aliyuncli.alicdn.com/aliyun-cli-linux-latest-arm64.tgz -o aliyun-cli-linux-latest.tgz

     • Download a previous version: Go to the GitHub Releases page to download installation packages for previous versions.

       The file name format for Linux installation packages is aliyun-cli-linux-<version>-<architecture>.tgz. Replace <version> with the target version number, such as 3.3.18, and <architecture> with `amd64` or `arm64`.

  2. Decompress the installation package to obtain the aliyun executable file.

     tar xzvf aliyun-cli-linux-latest.tgz

  3. Move the executable file to the /usr/local/bin directory. This lets you run the aliyun command from any path.

     sudo mv ./aliyun /usr/local/bin/

  macOS

  Install using Homebrew (Recommended)

  Note

  Before you continue, make sure that you have installed and configured Homebrew.

  Install the latest version of the Alibaba Cloud CLI:

  brew install aliyun-cli

  Install using the graphical interface (PKG)

  Double-click the package to install — no command-line tool required.

  1. Download the installation package.

     • Download the latest version: Open the download link https://aliyuncli.alicdn.com/aliyun-cli-latest.pkg in your browser to download the latest installation package.

     • Download a previous version: Go to the GitHub Releases page to view and download installation packages for previous versions.

       The file name format for macOS PKG (macOS Installer Package, .pkg) installation packages is aliyun-cli-<version>.pkg.

  2. Double-click the downloaded installation package and follow the instructions to complete the installation.

  Install using a Bash script

  The installation commands are the same as those for Linux. For more information about parameter descriptions, see the "Install using a Bash script" section for Linux.

  • Install the latest version

    /bin/bash -c "$(curl -fsSL https://aliyuncli.alicdn.com/install.sh)"

  • Installing previous versions

    /bin/bash -c "$(curl -fsSL https://aliyuncli.alicdn.com/install.sh)" -- -V 3.3.5

  Install from a TGZ package (.tar.gz)

  1. Download the installation package.

     • Download the latest version:

       curl https://aliyuncli.alicdn.com/aliyun-cli-macosx-latest-universal.tgz -o aliyun-cli-macosx-latest-universal.tgz

     • Download a previous version: Go to the GitHub Releases page to download installation packages for previous versions.

       The file name format for macOS installation packages is aliyun-cli-macosx-<version>-universal.tgz.

  2. Decompress the installation package to obtain the aliyun executable file.

     tar xzvf aliyun-cli-macosx-latest-universal.tgz

  3. Move the executable file to the /usr/local/bin directory. This lets you run the aliyun command from any path.

     sudo mv ./aliyun /usr/local/bin/

  Windows

  Important

  The Alibaba Cloud CLI is available only for Windows AMD64 systems. It does not support 32-bit or ARM64 architectures.

  Install using the graphical user interface (GUI)

  Download and decompress the installation package

  1. Download the installation package.

     • Download the latest version: Open the download link https://aliyuncli.alicdn.com/aliyun-cli-windows-latest-amd64.zip in your browser to download the latest installation package.

     • Download a previous version: Go to the GitHub Releases page to download installation packages for previous versions.

       The file name format for Windows installation packages is aliyun-cli-windows-<version>-amd64.zip.

  2. Extract aliyun.exe from the installation package to a directory such as C:\AliyunCLI.

     Note

     • This file must be run from a command-line terminal. Double-clicking the file does not work.

     • Remember this installation path. You will need it when you configure the PATH environment variable.

  Configure the PATH environment variable

  1. Press the Windows + S keys to open the search interface, and then enter the keyword "environment variables".

  2. In the search results, click Edit the environment variables for your account to open the Environment Variables settings.

  3. In the User variables section, select the environment variable with the key Path and click Edit.

     

  4. In the edit window, click New and enter the installation directory path for the Alibaba Cloud CLI. For example, C:\ExampleDir. Replace this with your actual installation directory path.

     

  5. Click OK in all open dialog boxes to save the changes.

  6. Restart your terminal session for the changes to take effect.

  Install using a PowerShell script

  1. Create a new script file named Install-CLI-Windows.ps1. You can run New-Item Install-CLI-Windows.ps1 in PowerShell to create the file, or create a new text document in File Explorer and rename it.

  2. Copy the following code and save it to the script file.

     Script example

     # Install-CLI-Windows.ps1
     # Purpose: Install Alibaba Cloud CLI on Windows AMD64 systems.
     # Supports custom version and install directory. Only modifies User-level and Process-level PATH.
     
     [CmdletBinding()]
     param (
         [string]$Version = "latest",
         [string]$InstallDir = "$env:LOCALAPPDATA",
         [switch]$Help
     )
     
     function Show-Usage {
         Write-Output @"
     
           Alibaba Cloud Command Line Interface Installer
     
         -Help                 Display this help and exit
     
         -Version VERSION      Custom CLI version. Default is 'latest'
     
         -InstallDir PATH      Custom installation directory. Default is:
                               $InstallDir\AliyunCLI
     
     "@
     }
     
     function Write-ErrorExit {
         param([string]$Message)
         Write-Error $Message
         exit 1
     }
     
     if ($PSBoundParameters['Help']) {
         Show-Usage
         exit 0
     }
     
     Write-Output @"
     ..............888888888888888888888 ........=8888888888888888888D=..............
     ...........88888888888888888888888 ..........D8888888888888888888888I...........
     .........,8888888888888ZI: ...........................=Z88D8888888888D..........
     .........+88888888 ..........................................88888888D..........
     .........+88888888 .......Welcome to use Alibaba Cloud.......O8888888D..........
     .........+88888888 ............. ************* ..............O8888888D..........
     .........+88888888 .... Command Line Interface(Reloaded) ....O8888888D..........
     .........+88888888...........................................88888888D..........
     ..........D888888888888DO+. ..........................?ND888888888888D..........
     ...........O8888888888888888888888...........D8888888888888888888888=...........
     ............ .:D8888888888888888888.........78888888888888888888O ..............
     "@
     
     $OSArchitecture = (Get-WmiObject -Class Win32_OperatingSystem).OSArchitecture
     
     $ProcessorArchitecture = [int](Get-WmiObject -Class Win32_Processor).Architecture
     
     if (-not ($OSArchitecture -match "64") -or $ProcessorArchitecture -ne 9) {
         Write-ErrorExit "Alibaba Cloud CLI only supports Windows AMD64 systems. Please run on a compatible system."
     }
     
     $DownloadUrl = "https://aliyuncli.alicdn.com/aliyun-cli-windows-$Version-amd64.zip"
     
     $tempPath = $env:TEMP
     $randomName = -join ((65..90) + (97..122) + (48..57) | Get-Random -Count 8)
     $DownloadDir = Join-Path -Path $tempPath -ChildPath $randomName
     New-Item -ItemType Directory -Path $DownloadDir | Out-Null
     
     try {
         $InstallDir = Join-Path $InstallDir "AliyunCLI"
         if (-not (Test-Path $InstallDir)) {
             New-Item -ItemType Directory -Path $InstallDir -Force | Out-Null
         }
     
         $ZipPath = Join-Path $DownloadDir "aliyun-cli.zip"
         Start-BitsTransfer -Source $DownloadUrl -Destination $ZipPath
     
         Expand-Archive -Path $ZipPath -DestinationPath $DownloadDir -Force
     
         Move-Item -Path "$DownloadDir\aliyun.exe" -Destination "$InstallDir\" -Force
     
         $Key = 'HKCU:\Environment'
         $CurrentPath = (Get-ItemProperty -Path $Key -Name PATH).PATH
     
         if ([string]::IsNullOrEmpty($CurrentPath)) {
             $NewPath = $InstallDir
         } else {
             if ($CurrentPath -notlike "*$InstallDir*") {
                 $NewPath = "$CurrentPath;$InstallDir"
             } else {
                 $NewPath = $CurrentPath
             }
         }
     
         if ($NewPath -ne $CurrentPath) {
             Set-ItemProperty -Path $Key -Name PATH -Value $NewPath
             $env:PATH += ";$InstallDir"
         }
     } catch {
         Write-ErrorExit "Failed to install Alibaba Cloud CLI: $_"
     } finally {
         Remove-Item -Path $DownloadDir -Recurse -Force | Out-Null
     }

  3. Run the script file to install the Alibaba Cloud CLI as shown in the following examples.

     Note

     The example script path is C:\Example\Install-CLI-Windows.ps1. Before you run the command, replace the script path with the actual location.

     • If you do not specify a version, the script automatically installs the latest version. The default installation path is C:\Users\<USERNAME>\AppData\Local\AliyunCLI.

       powershell.exe -ExecutionPolicy Bypass -File C:\Example\Install-CLI-Windows.ps1

     • Use the -Version and -InstallDir options to specify the installation version and directory. To view available previous versions, go to the GitHub Releases page.

       powershell.exe -ExecutionPolicy Bypass -File C:\Example\Install-CLI-Windows.ps1 -Version 3.3.15 -InstallDir "C:\ExampleDir\AliyunCLI"

• Verify the installation

  Run the following command to verify the installation.

  aliyun maxc --version

  If the version number appears, the installation succeeded. If an error occurs, check the CLI version. For more information, see Install or update the Alibaba Cloud CLI.

Authentication

aliyun maxc reuses the Alibaba Cloud CLI credential system. All authentication methods configured with aliyun configure (except OAuth) work directly — maxc inherits the current profile's credentials.

# Configure authentication using the Alibaba Cloud CLI (if you have not already done so)
aliyun configure --mode AK

# Verify that maxc can access MaxCompute
aliyun maxc auth whoami --json

For more information about authentication methods, see Configure and manage identity credentials.

Configure a MaxCompute project

When you use maxc for the first time, you must specify the MaxCompute project and endpoint:

aliyun maxc auth login \
  --endpoint http://service.cn-hangzhou.maxcompute.aliyun.com/api

If you omit --project, an interactive project selector appears. For continuous integration (CI) scenarios, you must explicitly specify the project:

aliyun maxc auth login \
  --project my_project_dev \
  --endpoint http://service.cn-hangzhou.maxcompute.aliyun.com/api \
  --no-picker

The MaxCompute project configuration is saved in ~/.maxc/config.yaml.

View and verify

# View the current identity and project
aliyun maxc auth whoami --json

# Check permissions for a specific table
aliyun maxc auth can-i --table my_table --operation SELECT --json

Quick Start

# 1. Configure the project (authentication is already completed with aliyun configure)
aliyun maxc auth login \
  --endpoint http://service.cn-hangzhou.maxcompute.aliyun.com/api

# 2. Browse tables
aliyun maxc meta list-tables --json
aliyun maxc meta describe my_table --json

# 3. Run a query
aliyun maxc query "SELECT * FROM my_table LIMIT 10" --json

# 4. Estimate the cost
aliyun maxc query cost "SELECT * FROM my_table" --json

# 5. Sample data
aliyun maxc data sample my_table --rows 5 --json

Global options

The following options can be placed anywhere in the command line and apply to all commands:

Use --project and --schema to temporarily access other projects or schemas without changing the session configuration. Table names also support the schema.table format.

Command reference

aliyun maxc job submit "SELECT * FROM large_table" --json

aliyun maxc job status <job_id> --json       # Query the status
aliyun maxc job wait <job_id> --json         # Wait for completion and return the result
aliyun maxc job result <job_id> --json       # Get the result of a completed job
aliyun maxc job cancel <job_id> --json       # Cancel a running job
aliyun maxc job diagnose <job_id> --json     # Diagnose the cause of a failure

aliyun maxc job list --json                  # Lists recent jobs (20 by default)
aliyun maxc job list --limit 50 --json       # Specify the number of jobs

# 1. Submit
JOB_ID=$(aliyun maxc query "SELECT * FROM large_table" --wait 0 --json \
  | jq -r '.metadata.job_id')

# 2. Wait
aliyun maxc job wait "$JOB_ID" --timeout 600 --json

# 3. Get the result (supports paging)
aliyun maxc job result "$JOB_ID" --max-rows 1000 --json

# List tables
aliyun maxc meta list-tables --json

# View the table schema (--full displays the complete column list; summary mode is the default)
aliyun maxc meta describe my_table --json
aliyun maxc meta describe my_table --full --json

# Search for tables
aliyun maxc meta search "order" --json

# Search for columns
aliyun maxc meta search-columns "user_id" --json

# List partitions (up to 100 by default)
aliyun maxc meta partitions my_table --json
aliyun maxc meta partitions my_table --limit 500 --json

# View the latest partition
aliyun maxc meta latest-partition my_table --json

# View data freshness
aliyun maxc meta freshness my_table --json

# List accessible projects
aliyun maxc meta list-projects --json

# List schemas in a project
aliyun maxc meta list-schemas --json

# Set semantic information
aliyun maxc meta semantic set my_table \
  --desc "Order details table" \
  --use-cases "Analyze daily order volume" "Calculate user repurchase rate" \
  --json

# Get semantic information
aliyun maxc meta semantic get my_table --json

# List tables that are missing semantic information
aliyun maxc meta semantic list-missing --json

aliyun maxc data sample my_table --json
aliyun maxc data sample my_table --rows 20 --partition "ds=20260601" --columns "user_id,amount" --json

aliyun maxc data profile my_table --json
aliyun maxc data profile my_table --partition "ds=20260601" --json

aliyun maxc data profile <table_name> --json

aliyun maxc data upload my_table --file data.csv --json
aliyun maxc data upload my_table --file data.csv --partition "ds=20260601" --overwrite --json

aliyun maxc data download my_table --output data.csv --json
aliyun maxc data download my_table --output data.csv --partition "ds=20260601" --limit 100000 --json

# Set the default project (specify at least --project or --schema)
aliyun maxc session set --project my_project_dev --json

# Set the default schema
aliyun maxc session set --schema my_schema --json

# View the current session
aliyun maxc session show --json

# Clear session settings
aliyun maxc session unset --json

aliyun maxc meta list-tables --project other_project --json
aliyun maxc query "SELECT * FROM t LIMIT 5" --project other_project --json

Output format

{
  "version": "2.0",
  "command": "query",
  "status": "success",
  "data": { ... },
  "metadata": { ... },
  "error": null,
  "agent_hints": null
}

{
  "code": "TABLE_NOT_FOUND",
  "message": "Table 'orders' does not exist in project 'my_project'",
  "suggestion": "Use 'aliyun maxc meta search orders --json' to find similar tables",
  "recoverable": false
}

AI Agent integration

maxc is purpose-built for AI Agent integration. The following sections cover its core design and usage patterns.

# Estimate the cost
aliyun maxc query cost "SELECT * FROM large_table" --json

# Set a cost threshold
aliyun maxc query "SELECT * FROM large_table" --cost-check 100 --json

# One-click installation to Claude Code
aliyun maxc agent skill install --json

# Install on other platforms
aliyun maxc agent skill install cursor --json
aliyun maxc agent skill install windsurf --json

# View the installation status on all platforms
aliyun maxc agent skill list --json

# Update installed SKILLs (after a new version is released)
aliyun maxc agent skill update --all --json

# View the differences between the installed version and the latest version
aliyun maxc agent skill diff claude-code --json

# Uninstall
aliyun maxc agent skill uninstall cursor --json

User question
  ↓
1. meta search / meta list-tables     → Find relevant tables
  ↓
2. meta describe                      → Understand table schema and column meanings
  ↓
3. data sample                        → View actual data to confirm column value formats
  ↓
4. meta partitions / latest-partition → Determine the partition range
  ↓
5. query cost                         → Estimate the cost
  ↓
6. query                              → Run the query and return the result

aliyun maxc meta semantic set my_table \
  --description "User behavior log table, recording click and view events within the app" \
  --usage-scenario "User behavior analysis, funnel conversion statistics" \
  --sample-questions '["What was the DAU for the last 7 days?", "What is the registration conversion rate trend?"]' \
  --json

aliyun maxc agent context --json