Alibaba Cloud SLS CLI

aliyun-sls is an API2CLI-style CLI for Alibaba Cloud Simple Log Service. It exposes signed SLS REST APIs as a stable command line interface for humans, scripts, and AI agents.

The CLI is self-contained Python and uses the SLS LOG <AccessKeyId>:<Signature> HMAC-SHA1 request signature, so it does not require Alibaba Cloud SDK packages. The recommended installation path is an npm/npx wrapper that installs the runtime and command shims.

中文介绍

aliyun-sls 是一个面向阿里云日志服务 SLS 的命令行工具。它把 SLS REST API 封装成稳定、可脚本化、适合 AI Agent 调用的 CLI，默认输出 JSON envelope，方便在终端、自动化脚本和 Agent 工作流里组合使用。

这个工具不依赖阿里云 SDK，运行时使用标准库实现 SLS LOG <AccessKeyId>:<Signature> HMAC-SHA1 签名。它提供三层能力：

• Raw API：任意未封装接口都可以通过 api METHOD PATH --params --data 调用。
• 元数据命令：常用 Project、Logstore、Logs、Index、Shard 接口已经整理成稳定命令。
• Shortcut：+query、+stores、+histograms 覆盖日常查日志和排障场景。

配置默认落在 ~/.api2cli/aliyun-sls/config.json，支持 profile、环境变量、私有文件、secret manager 命令和本机 inline 配置。写操作支持 --dry-run，删除等高风险操作需要显式 --yes。

Install

Recommended:

npx @1kb/aliyun-sls@latest install

The installer checks Node.js and Python, copies the CLI runtime to:

~/.api2cli/aliyun-sls/runtime

and creates command shims in:

~/.api2cli/bin

If that bin directory is not already on PATH, add it:

export PATH="$HOME/.api2cli/bin:$PATH"

Local source install:

cd aliyun-sls
node scripts/install.js

Developer mode without installing:

cd aliyun-sls
python -m aliyun_sls --help

Quick Start

SLS uses AccessKey credentials rather than OAuth. Prefer RAM user AccessKeys with the least privileges needed for the SLS project.

# 1. Configure non-sensitive defaults
aliyun-sls config init \
  --region cn-hangzhou \
  --endpoint cn-hangzhou.log.aliyuncs.com \
  --project my-project \
  --logstore app \
  --topic mineadmin

# 2. Provide credentials through environment variables
export ALIYUN_SLS_ACCESS_KEY_ID=...
export ALIYUN_SLS_ACCESS_KEY_SECRET=...

# 3. Store env-var references in the user config
aliyun-sls auth env

# 4. Verify auth and installation
aliyun-sls auth status
aliyun-sls ops --format table

# 5. Run a read-only API command
aliyun-sls project list --format table

The CLI also reads Alibaba Cloud standard env vars directly:

export ALIYUN_ACCESS_KEY_ID=...
export ALIYUN_ACCESS_KEY_SECRET=...
export ALIYUN_SECURITY_TOKEN=...

AI Agent Quick Start

All setup commands support JSON output, so an agent can run them without relying on an interactive UI.

npx @1kb/aliyun-sls@latest install --json

aliyun-sls config init \
  --region cn-hangzhou \
  --endpoint cn-hangzhou.log.aliyuncs.com \
  --project my-project \
  --logstore app \
  --format json

aliyun-sls auth env --format json
aliyun-sls auth status --format json
aliyun-sls ops --format json

If the user prefers private local files or a secret manager, store references instead of plaintext credentials:

aliyun-sls auth file \
  --access-key-id-file ~/.secrets/aliyun-sls/access-key-id \
  --access-key-secret-file ~/.secrets/aliyun-sls/access-key-secret

aliyun-sls auth command \
  --access-key-id-command "security find-generic-password -s aliyun-sls-access-key-id -w" \
  --access-key-secret-command "security find-generic-password -s aliyun-sls-access-key-secret -w"

Configuration

The default user config path is:

~/.api2cli/aliyun-sls/config.json

Override the config root:

API2CLI_CONFIG_DIR=/custom/path aliyun-sls config show

Override the exact config file:

ALIYUN_SLS_CONFIG=/custom/path/config.json aliyun-sls config show

The project config template is api2cli.config.yaml. It describes defaults and environment variables, but it must not contain real AccessKey secrets.

Credentials should be stored as references:

• auth env: read from env vars such as ALIYUN_SLS_ACCESS_KEY_ID.
• auth file: read from private local files.
• auth command: read from a secret manager command.
• auth inline: available for controlled local use, but not recommended for shared machines.

Profiles:

aliyun-sls profile add staging --use
aliyun-sls config set endpoint cn-shenzhen.log.aliyuncs.com
aliyun-sls profile use default

If your Python distribution has no default CA bundle configured, set ALIYUN_SLS_CA_BUNDLE or install certifi. The runtime uses certifi automatically when it is available.

API Layers

Raw API fallback:

aliyun-sls api GET /logstores \
  --project my-project \
  --params '{"offset":0,"size":10}' \
  --format pretty

Generated operations:

aliyun-sls project list --format table
aliyun-sls logstore list --project my-project --format table
aliyun-sls logstore get --project my-project --logstore app --format pretty
aliyun-sls logs get --project my-project --logstore app \
  --from "15m ago" --to now --query "* | select count(1) as c" --format pretty

Shortcuts:

aliyun-sls +stores --project my-project --format table
aliyun-sls +query --project my-project --logstore app \
  --from "15m ago" --query "error" --line 20 --reverse true --format pretty
aliyun-sls +histograms --project my-project --logstore app \
  --from "1h ago" --to now --query "status: 500" --format table

Safety

Dry-run and high-risk confirmations:

aliyun-sls logstore create --project my-project \
  --logstoreName app --shardCount 2 --ttl 30 --dry-run --format pretty
aliyun-sls logstore delete --project my-project --logstore app --dry-run
aliyun-sls logstore delete --project my-project --logstore app --yes

Rules:

• Default output is a JSON envelope: { "ok": true, "data": ..., "meta": ... }.
• config show masks credentials unless --reveal is explicitly used.
• High-risk operations such as delete require --yes, unless --dry-run is used.
• Do not commit AccessKey secrets to this platform directory.

Uninstall

Remove installed command shims and runtime:

rm -f "$HOME/.api2cli/bin/aliyun-sls" "$HOME/.api2cli/bin/sls"
rm -rf "$HOME/.api2cli/aliyun-sls/runtime"

Remove user config only when you no longer need the profiles:

rm -f "$HOME/.api2cli/aliyun-sls/config.json"

Architecture

This platform follows API2CLI_PLAYBOOK.md:

• Raw API layer: api METHOD PATH --params --data --file --output.
• Metadata-driven command layer: operations in metadata/sls-core.json exposed as project, logstore, logs, index, and shard commands.
• Shortcut layer: +query, +stores, and +histograms.
• Shared runtime: config, signing, request execution, output envelopes, pagination, and risk checks are centralized in aliyun_sls/.
• Install layer: package.json, scripts/install.js, scripts/run.js, and dist/manifest.json provide the npm/npx entrypoint.

References

• Alibaba Cloud SLS API overview: https://www.alibabacloud.com/help/en/sls/developer-reference/api-sls-2020-12-30-overview
• SLS request signatures: https://www.alibabacloud.com/help/en/sls/developer-reference/request-signatures
• GetLogs API: https://www.alibabacloud.com/help/en/sls/developer-reference/api-sls-2020-12-30-getlogs