MaxCompute CLI

安装及验证

maxc 通过阿里云 CLI 分发。安装/更新 阿里云CLI 后即可使用。

• 支持操作系统

  操作系统	支持版本	支持架构
  Linux	主流发行版，如 CentOS 8+/RHEL 8+、Ubuntu 16.04+、Debian 9+ 等（CentOS 7 已 EOL，不建议使用）	AMD64、ARM64
  macOS	macOS 11（Big Sur）及以上	Intel 和 Apple Silicon（Universal）
  Windows	Windows 10 及以上（64 位）	AMD64（不支持 32 位及 ARM64）

• 根据操作系统选择对应 Tab，按步骤完成安装。每种操作系统均提供多种安装途径，选择其中一种即可。

  Linux

  通过 Bash 脚本安装（推荐）

  支持以下选项：

  • 安装最新版本

    若未指定版本，脚本将自动安装最新版本。

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

  • 安装历史版本

    使用 -V 选项可指定安装版本。访问 GitHub Releases 页面可查看历史可用版本。

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

  通过 TGZ 安装包（.tar.gz）安装

  1. 下载安装包。

     • 下载最新版本：

       说明

       执行 uname -m 可查看 Linux 系统架构。终端输出 arm64 或 aarch64 表示 ARM64 架构，其他输出表示 AMD64 架构。

       • AMD64 系统：

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

       • ARM64 系统：

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

     • 下载历史版本：访问 GitHub Releases 页面可下载历史版本安装包。

       Linux 适用安装包包名格式为 aliyun-cli-linux-<version>-<architecture>.tgz（其中 <version> 替换为目标版本号，如 3.3.18；<architecture> 替换为 amd64 或 arm64）。

  2. 解压安装包以获取可执行文件 aliyun。

     tar xzvf aliyun-cli-linux-latest.tgz

  3. 将可执行文件移动至 /usr/local/bin 目录，使 aliyun 命令可在任意路径下运行。

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

  macOS

  通过 Homebrew 安装（推荐）

  说明

  继续操作前，请确保已安装并配置 Homebrew。

  1. 修改安装源。（可选）

     中国内地用户可能由于网络问题无法安装，可尝试修改 Homebrew 安装源以解决此问题。以使用中科大开源镜像站为例：

     设置 Homebrew 安装源为科大源

     说明

     Homebrew 支持通过修改环境变量设置安装源，首次安装 Homebrew 时也可以通过此方式加速下载过程。

     export HOMEBREW_INSTALL_FROM_API=1
     export HOMEBREW_BREW_GIT_REMOTE="https://mirrors.ustc.edu.cn/brew.git"
     export HOMEBREW_CORE_GIT_REMOTE="https://mirrors.ustc.edu.cn/homebrew-core.git"
     export HOMEBREW_BOTTLE_DOMAIN="https://mirrors.ustc.edu.cn/homebrew-bottles"
     export HOMEBREW_API_DOMAIN="https://mirrors.ustc.edu.cn/homebrew-bottles/api"
     brew update

  2. 安装最新版本的阿里云 CLI。

     brew install aliyun-cli

  通过图形界面（PKG）安装

  双击安装，无需命令行工具。

  1. 下载安装包。

     • 下载最新版本：在浏览器中打开下载链接 https://aliyuncli.alicdn.com/aliyun-cli-latest.pkg，下载最新版本安装包。

     • 下载历史版本：访问 GitHub Releases 页面可查看并下载历史版本安装包。

       macOS 适用的 PKG（macOS Installer Package，.pkg）安装包包名格式为 aliyun-cli-<version>.pkg。

  2. 双击下载好的安装包，按照说明指引完成安装。

  通过 Bash 脚本安装

  安装命令与 Linux 相同，参数说明请参见 Linux 的「通过 Bash 脚本安装」方式。

  • 安装最新版本

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

  • 安装历史版本

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

  通过 TGZ 安装包（.tar.gz）安装

  1. 下载安装包。

     • 下载最新版本：

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

     • 下载历史版本：访问 GitHub Releases 页面可下载历史版本安装包。

       macOS 适用安装包包名格式为 aliyun-cli-macosx-<version>-universal.tgz。

  2. 解压安装包以获取可执行文件 aliyun。

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

  3. 将可执行文件移动至 /usr/local/bin 目录，使 aliyun 命令可在任意路径下运行。

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

  Windows

  重要

  阿里云 CLI 当前仅适用于 Windows AMD64 架构系统，暂不支持 32 位及其他非 AMD64 架构（如 ARM64）的 Windows 系统。

  通过图形界面（GUI）安装

  下载并解压安装包

  1. 下载安装包。

     • 下载最新版本：在浏览器中打开下载链接 https://aliyuncli.alicdn.com/aliyun-cli-windows-latest-amd64.zip，下载最新版本安装包。

     • 下载历史版本：访问 GitHub Releases 页面可下载历史版本安装包。

       Windows 适用安装包包名格式为 aliyun-cli-windows-<version>-amd64.zip。

  2. 将安装包中的可执行文件 aliyun.exe 解压至目标目录（建议 C:\AliyunCLI），该目录将作为阿里云 CLI 的安装目录。

     说明

     • 该文件需要通过命令行终端运行，双击文件无法正常工作。

     • 请记住此安装路径，后续配置 PATH 时需要使用。

  配置 PATH 环境变量

  1. 按下 Windows 键 + S 键打开搜索界面，输入搜索关键词"环境变量"。

  2. 在搜索结果中单击 编辑账户的环境变量，打开 环境变量 设置界面。

  3. 在 用户变量 中选择键为 Path 的环境变量，单击 编辑。

     

  4. 在编辑界面中单击 新建，输入阿里云 CLI 安装目录路径。示例目录：C:\ExampleDir（请替换为实际安装目录路径）。

     

  5. 在所有打开的对话框中依次单击 确定 以保存更改。

  6. 重新启动终端会话以使更改生效。

  通过 PowerShell 脚本安装

  1. 新建脚本文件 Install-CLI-Windows.ps1。可在 PowerShell 中执行 New-Item Install-CLI-Windows.ps1 创建，或在文件资源管理器中新建文本文档后重命名。

  2. 将以下代码复制并保存到脚本文件中。

     脚本示例

     # 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. 参考以下示例，运行脚本文件安装阿里云 CLI。

     说明

     示例脚本路径为 C:\Example\Install-CLI-Windows.ps1，请将脚本路径替换为实际位置后运行命令。

     • 若未指定版本，脚本将自动安装最新版本。默认安装路径为：C:\Users\<USERNAME>\AppData\Local\AliyunCLI。

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

     • 使用 -Version 和 -InstallDir 选项可指定安装版本和安装目录。访问 GitHub Releases 页面可查看历史可用版本。

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

• 验证安装结果

  安装完成后，在终端中执行以下命令确认阿里云 CLI 已安装成功。

  aliyun maxc --version

  如显示版本号，则安装成功。如提示错误，建议检查 CLI 版本，详情参考安装/更新 阿里云CLI 。

认证

aliyun maxc 直接复用阿里云 CLI 的凭证体系。通过 aliyun configure 配置的认证方式（除 OAuth 认证）均可直接使用，maxc 会自动继承当前 Profile 的凭证。

# 使用阿里云 CLI 配置认证（如果尚未配置）
aliyun configure --mode AK

# 验证 maxc 可以访问 MaxCompute
aliyun maxc auth whoami --json

认证方式详情参考配置与管理身份凭证。

配置 MaxCompute 项目

首次使用时需要指定 MaxCompute 项目和端点：

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

省略 --project 时会弹出交互式项目选择器。CI 场景需显式指定：

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

MaxCompute 项目配置保存在 ~/.maxc/config.yaml。

查看与验证

# 查看当前身份和项目
aliyun maxc auth whoami --json

# 检查对特定表的权限
aliyun maxc auth can-i --table my_table --operation SELECT --json

快速入门

# 1. 配置项目（认证已通过 aliyun configure 完成）
aliyun maxc auth login \
  --endpoint http://service.cn-hangzhou.maxcompute.aliyun.com/api

# 2. 浏览表
aliyun maxc meta list-tables --json
aliyun maxc meta describe my_table --json

# 3. 执行查询
aliyun maxc query "SELECT * FROM my_table LIMIT 10" --json

# 4. 预估成本
aliyun maxc query cost "SELECT * FROM my_table" --json

# 5. 采样数据
aliyun maxc data sample my_table --rows 5 --json

全局选项

以下选项可放在命令行任意位置，对所有命令生效：

--project 和 --schema 用于临时访问其他项目或 Schema，不影响当前会话配置。表名也支持 schema.table 格式。

命令参考

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

aliyun maxc job status <job_id> --json       # 查询状态
aliyun maxc job wait <job_id> --json         # 等待完成并返回结果
aliyun maxc job result <job_id> --json       # 获取已完成作业的结果
aliyun maxc job cancel <job_id> --json       # 取消运行中的作业
aliyun maxc job diagnose <job_id> --json     # 诊断失败原因

aliyun maxc job list --json                  # 列出最近作业（默认 20 条）
aliyun maxc job list --limit 50 --json       # 指定数量

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

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

# 3. 获取结果（可分页）
aliyun maxc job result "$JOB_ID" --max-rows 1000 --json

# 列出表
aliyun maxc meta list-tables --json

# 查看表结构（--full 显示完整列列表，默认摘要模式）
aliyun maxc meta describe my_table --json
aliyun maxc meta describe my_table --full --json

# 搜索表
aliyun maxc meta search "order" --json

# 搜索列
aliyun maxc meta search-columns "user_id" --json

# 列出分区（默认最多 100 个）
aliyun maxc meta partitions my_table --json
aliyun maxc meta partitions my_table --limit 500 --json

# 查看最新分区
aliyun maxc meta latest-partition my_table --json

# 查看数据新鲜度
aliyun maxc meta freshness my_table --json

# 列出可访问的项目
aliyun maxc meta list-projects --json

# 列出项目下的 Schema
aliyun maxc meta list-schemas --json

# 设置语义信息
aliyun maxc meta semantic set my_table \
  --desc "订单明细表" \
  --use-cases "分析每日订单量" "计算用户复购率" \
  --json

# 获取语义信息
aliyun maxc meta semantic get my_table --json

# 列出缺少语义信息的表
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

# 设置默认项目（至少指定 --project 或 --schema 之一）
aliyun maxc session set --project my_project_dev --json

# 设置默认 Schema
aliyun maxc session set --schema my_schema --json

# 查看当前会话
aliyun maxc session show --json

# 清除会话设置
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

输出格式

{
  "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 集成

maxc 是面向 AI Agent 构建的工具层。以下是核心设计理念和使用方式。

# 预估成本
aliyun maxc query cost "SELECT * FROM large_table" --json

# 设置成本阈值
aliyun maxc query "SELECT * FROM large_table" --cost-check 100 --json

# 一键安装到 Claude Code
aliyun maxc agent skill install --json

# 安装到其他平台
aliyun maxc agent skill install cursor --json
aliyun maxc agent skill install windsurf --json

# 查看所有平台的安装状态
aliyun maxc agent skill list --json

# 更新已安装的 SKILL（新版本发布后）
aliyun maxc agent skill update --all --json

# 查看已安装版本与最新版本的差异
aliyun maxc agent skill diff claude-code --json

# 卸载
aliyun maxc agent skill uninstall cursor --json

用户提问
  ↓
1. meta search / meta list-tables     → 找到相关表
  ↓
2. meta describe                      → 了解表结构和列含义
  ↓
3. data sample                        → 查看实际数据，确认列值格式
  ↓
4. meta partitions / latest-partition → 确定分区范围
  ↓
5. query cost                         → 预估成本
  ↓
6. query                              → 执行查询并返回结果

aliyun maxc meta semantic set my_table \
  --description "用户行为日志表，记录 App 内的点击和浏览事件" \
  --usage-scenario "用户行为分析、漏斗转化统计" \
  --sample-questions '["过去7天的DAU是多少", "注册转化率趋势"]' \
  --json

aliyun maxc agent context --json