Alibabacloud Sls Cli Guidance

Aliyun SLS CLI

Command-line interface for managing Alibaba Cloud Simple Log Service (SLS) resources including projects, logstores, and log queries.

Prerequisites

Before starting, verify that aliyun-cli and sls plugin are installed:

aliyun version
aliyun sls version

Expected output: aliyun-cli-sls 0.1.0 (5e6288421) or similar

Installation (if not installed)

If the check fails, install aliyun-cli using one of these methods:

Option 1: Homebrew (macOS only)

brew install aliyun-cli
aliyun plugin install --names sls

Option 2: Official installer (Linux and macOS)

# This method requires sudo permission to install to `/usr/local/bin/aliyun`.
sudo /bin/bash -c "$(curl -fsSL https://aliyuncli.alicdn.com/install.sh)"
aliyun plugin install --names sls

Configuration

Configure access credentials (using AccessKey example) and region:

aliyun configure set \
  --access-key-id <access-key-id> \
  --access-key-secret <access-key-secret> \
  --region <region>

Region examples: cn-hangzhou, cn-shanghai, cn-beijing, us-west-1

IMPORTANT: If credentials or region are not provided by the user, request them explicitly before proceeding with any operations.

For other authentication methods(StsToken|RamRoleArn|EcsRamRole|...), check: aliyun configure set --help

Common Operations

Below lists frequently used SLS operations. Read the corresponding reference file first before executing any of them.

CLI Usage

Discover APIs

aliyun help sls
aliyun help sls <apiName>

Validate command syntax (dry-run)

Add --cli-dry-run to validate parameters without executing:

aliyun sls list-project --offset 0 --size 50 --cli-dry-run

Output format

All commands return JSON by default. Use --cli-query with JMESPath expressions to filter output:

aliyun sls list-project --cli-query "projects[*].name"

Global parameters

• --cli-dry-run: Validate command without execution
• --cli-query <jmespath>: Filter output with JMESPath
• --region <region>: Override region
• --help: Show command help

Rules

1. Do not use deprecated APIs — use the current replacement so behavior stays supported and predictable.

2. Obtain explicit user approval before any delete — delete operations are irreversible. 3. Use `--cli-dry-run` first for destructive operations (delete, update). 4. Update APIs require full parameters — first call the corresponding Get API to retrieve current parameters, then include all meaningful parameters in the update call (including unchanged ones). Omitting parameters may reset them to defaults. 5. If a command fails: check required parameters with --cli-dry-run, verify credentials via aliyun configure list, read the error message, and compare your command with the corresponding reference file. If the sub-command is not recognized, upgrade the plugin via aliyun plugin update sls.

Index Configuration

Index configuration enables query and SQL analytics on a Logstore. You must create an index before using query syntax or SQL on logs.

Index types

• line: Full-text index. Enables searching log content by keyword (e.g. "someWord" in query).
• keys: Field index. Index specific log fields for filtering (e.g. key: "value") and SQL analytics.

At least one of line or keys must be specified when calling create-index or update-index.

Field index types & options

Options for all types:

• doc_value: Enable analytics so the field can be used in SQL (GROUP BY, WHERE). Recommended: true.
• alias: Alias name for the field (optional).

Additional options for text and json:

• caseSensitive: Case-sensitive matching (boolean).
• chn: Whether the content contains Chinese (boolean). Recommended: false if not needed.
• token: List of token delimiters for full-text split (e.g. [","," ",";","=",...]).

Rules

1. Overwrite update: update-index replaces the entire index configuration — it does not merge or patch. Always call get-index first, then send the complete desired config with update-index. 2. Index changes (create or update) take effect within 1 minute.

Examples

Get current index configuration

aliyun sls get-index --project my-project --logstore my-logstore

Create index: full-text only

aliyun sls create-index --project my-project --logstore my-logstore \
  --line '{"chn":false,"caseSensitive":false,"token":[","," ",";","=","(",")","[","]","{","}",":","\n","\t","\r"]}'

Create index: full-text + field indexes

For complex JSON, write the config to a file to avoid shell quoting issues:

cat > /tmp/keys.json << 'EOF'
{
  "region": {
    "doc_value": true,
    "alias": "",
    "type": "text",
    "caseSensitive": false,
    "chn": false,
    "token": [",", " ", ";", "=", "(", ")", "[", "]", "{", "}", ":", "\n", "\t", "\r"]
  },
  "end_time": {
    "doc_value": true,
    "alias": "",
    "type": "long"
  },
  "request_time": {
    "doc_value": true,
    "alias": "",
    "type": "double"
  }
}
EOF

aliyun sls create-index --project my-project --logstore my-logstore \
  --line '{"caseSensitive":false,"chn":false}' \
  --keys "$(cat /tmp/keys.json)"

Update index workflow

Always get-then-update to avoid losing existing configuration:

aliyun sls get-index --project my-project --logstore my-logstore

# Modify the returned JSON as needed, then pass the full config back:
aliyun sls update-index --project my-project --logstore my-logstore \
  --line '{"caseSensitive":false,"chn":false}' \
  --keys "$(cat /tmp/keys.json)"

Delete index

aliyun sls delete-index --project my-project --logstore my-logstore

Logstore Operations

Manage logstores within an SLS project. A logstore is the unit for log collection, storage, query, and analytics.

Naming requirements

• Unique within the same project
• Lowercase letters, numbers, hyphens (-), and underscores (_) only
• Must start and end with a lowercase letter or number
• Length: 2–63 characters

Key parameters

Rules

1. Overwrite update: update-log-store does not merge — omitted parameters may reset to defaults. Always call get-log-store first, then pass all parameters back (only changing what you need).

Examples

List logstores

aliyun sls list-log-stores --project my-project

Pagination: --offset (default 0) and --size (default 200, max 500).

Optional filters (can be combined):

• --logstore-name "name" — fuzzy match on logstore name
• --mode standard|query — filter by mode
• --telemetry-type None|Metrics — None for logs only, Metrics for time-series only

aliyun sls list-log-stores --project my-project \
  --logstore-name "app-metrics" --mode standard --telemetry-type Metrics \
  --offset 0 --size 200

Create logstore

aliyun sls create-log-store \
  --project my-project \
  --logstore-name my-logstore \
  --ttl 30 \
  --shard-count 2 \
  --auto-split true \
  --max-split-shard 256

With encryption:

aliyun sls create-log-store \
  --project my-project \
  --logstore-name encrypted-logs \
  --ttl 30 \
  --shard-count 2 \
  --encrypt-conf '{"enable":true,"encrypt_type":"default"}'

Get logstore

aliyun sls get-log-store --project my-project --logstore my-logstore

Update logstore (get-then-update)

Step 1 — get current config:

aliyun sls get-log-store --project my-project --logstore test

Example response:

{
  "appendMeta": false,
  "autoSplit": true,
  "enable_tracking": true,
  "hot_ttl": 60,
  "infrequentAccessTTL": 0,
  "logstoreName": "test",
  "maxSplitShard": 256,
  "mode": "standard",
  "shardCount": 8,
  "ttl": 60
}

Step 2 — update with all parameters, only changing what you need (e.g. appendMeta → true):

aliyun sls update-log-store \
  --project my-project \
  --logstore test \
  --logstore-name test \
  --ttl 60 \
  --append-meta true \
  --auto-split true \
  --enable-tracking true \
  --hot-ttl 60 \
  --infrequent-access-ttl 0 \
  --max-split-shard 256 \
  --mode standard

Delete logstore

aliyun sls delete-log-store --project my-project --logstore my-logstore

Logtail Pipeline Config

Manage Logtail pipeline configs for log collection. A pipeline config defines what to collect (inputs), how to parse (processors), and where to send (flushers). After creation, you must create a machine group and apply the config to it for collection to take effect.

Key parameters

Examples

Create: JSON log parsing

aliyun sls create-logtail-pipeline-config --project my-project \
  --config-name json-log-config \
  --inputs '{"Type":"input_file","FilePaths":["/app/**/output.json"],"EnableContainerDiscovery":false,"MaxDirSearchDepth":1,"FileEncoding":"utf8"}' \
  --processors '{"Type":"processor_parse_json_native","SourceKey":"content"}' \
  --flushers '{"Type":"flusher_sls","Logstore":"my-logstore","TelemetryType":"logs","Region":"cn-hangzhou","Endpoint":"cn-hangzhou-intranet.log.aliyuncs.com"}' \
  --log-sample '{"status": 200, "latency": 4152, "method": "GetUserConfig", "user": "Alice"}'

Create: Delimiter log parsing

aliyun sls create-logtail-pipeline-config --project my-project \
  --config-name delimiter-log-config \
  --inputs '{"Type":"input_file","FilePaths":["/app/**/access.log"],"EnableContainerDiscovery":false,"MaxDirSearchDepth":1,"FileEncoding":"utf8"}' \
  --processors '{"Type":"processor_parse_delimiter_native","SourceKey":"content","Separator":"|","Quote":"\u0000","KeepingSourceWhenParseFail":true,"Keys":["remote_addr","time_iso8601","method","uri","protocol","status","sent_bytes","user_agent","latency"]}' \
  --flushers '{"Type":"flusher_sls","Logstore":"my-logstore","TelemetryType":"logs","Region":"cn-hangzhou","Endpoint":"cn-hangzhou-intranet.log.aliyuncs.com"}' \
  --log-sample '192.168.1.10 | 2026-03-24T10:52:01+08:00 | GET | /api/v1/products | HTTP/1.1 | 200 | 1240  | Mozilla/5.0 | 0.045'

Create: Regex parsing + time parsing

For complex regex, write each processor to a separate file to avoid quoting issues:

cat > /tmp/processor_regex.json << 'ENDOFFILE'
{
  "Type": "processor_parse_regex_native",
  "SourceKey": "content",
  "Regex": "(\\d+-\\d+-\\d+\\s\\S+)\\s\\S+\\s\\[(\\w+)]\\s\\S+\\s(\\w+)\\s\\S+\\s(\\S+)\\s\\S+\\s(.*)",
  "Keys": ["time", "level", "func", "class", "content"]
}
ENDOFFILE

cat > /tmp/processor_time.json << 'ENDOFFILE'
{
  "Type": "processor_parse_timestamp_native",
  "SourceKey": "time",
  "SourceFormat": "%Y-%m-%d %H:%M:%S,%f"
}
ENDOFFILE

aliyun sls create-logtail-pipeline-config --project my-project \
  --config-name regex-time-config \
  --inputs '{"Type":"input_file","FilePaths":["/app/**/app.log"],"EnableContainerDiscovery":false,"MaxDirSearchDepth":1,"FileEncoding":"utf8"}' \
  --processors "$(cat /tmp/processor_regex.json)" \
  --processors "$(cat /tmp/processor_time.json)" \
  --flushers '{"Type":"flusher_sls","Logstore":"my-logstore","TelemetryType":"logs","Region":"cn-hangzhou","Endpoint":"cn-hangzhou-intranet.log.aliyuncs.com"}' \
  --log-sample '2026-03-24 11:15:02,456 | [INFO] | main | com.app.OrderService | User [1001] placed an order.'

Create: Regex + multiline + time parsing + timezone

cat > /tmp/input.json << 'ENDOFFILE'
{
  "Type": "input_file",
  "FilePaths": ["/app/**/app.log"],
  "EnableContainerDiscovery": false,
  "MaxDirSearchDepth": 1,
  "FileEncoding": "utf8",
  "Multiline": {
    "Mode": "custom",
    "StartPattern": "\\d{4}-\\d{2}-\\d{2}\\s\\d{2}:\\d{2}:\\d{2},\\d{3}\\s\\|\\s\\[[A-Z]+\\]\\s\\|.*",
    "UnmatchedContentTreatment": "single_line"
  }
}
ENDOFFILE

cat > /tmp/processor_regex.json << 'ENDOFFILE'
{
  "Type": "processor_parse_regex_native",
  "SourceKey": "content",
  "KeepingSourceWhenParseFail": true,
  "Regex": "(\\d+-\\d+-\\d+\\s\\S+)\\s\\S+\\s\\[(\\w+)]\\s\\S+\\s(\\w+)\\s\\S+\\s(\\S+)\\s\\S+\\s(.*)",
  "Keys": ["time", "level", "func", "class", "content"]
}
ENDOFFILE

cat > /tmp/processor_time.json << 'ENDOFFILE'
{
  "Type": "processor_parse_timestamp_native",
  "SourceKey": "time",
  "SourceFormat": "%Y-%m-%d %H:%M:%S,%f",
  "SourceTimezone": "GMT+08:00"
}
ENDOFFILE

aliyun sls create-logtail-pipeline-config --project my-project \
  --config-name regex-multiline-config \
  --inputs "$(cat /tmp/input.json)" \
  --processors "$(cat /tmp/processor_regex.json)" \
  --processors "$(cat /tmp/processor_time.json)" \
  --flushers '{"Type":"flusher_sls","Logstore":"my-logstore","TelemetryType":"logs","Region":"cn-hangzhou","Endpoint":"cn-hangzhou-intranet.log.aliyuncs.com"}' \
  --log-sample '2026-03-24 11:15:02,456 | [INFO] | main | com.app.OrderService | User [1001] placed an order.'

Config structure

Input: input_file

Flusher: flusher_sls

Processors

First processor must be a parsing plugin. After that, optionally add 1 time-parsing plugin, 1 filter plugin, and multiple desensitization plugins.

Multiline logs

When logs span multiple lines, configure Multiline in the input plugin to combine them. Set StartPattern to a regex matching the first line of each log entry.

Time parsing

Use processor_parse_timestamp_native to extract log time from a parsed field. Without it, log time defaults to collection time.

Common time formats:

Rules

1. Overwrite update: update-logtail-pipeline-config replaces the entire config. Always call get-logtail-pipeline-config first, then send the complete config with update-logtail-pipeline-config. 2. Apply to machine group: A config alone does not collect logs. You must create a machine group and apply the config to it (see Apply Logtail config to machine group). 3. Processor ordering: The first processor must be a parsing plugin (JSON / delimiter / regex). Time-parsing must come after the parsing plugin. 4. For complex JSON parameters with special characters (regex, etc.), write to a temp file to avoid shell quoting issues. 5. For more Logtail pipeline config types (container stdout, syslog, MySQL, etc.), see CreateLogtailPipelineConfig API reference.

Machine Group

Manage machine groups within an SLS project. A machine group defines a set of machines for log collection. After creating a Logtail pipeline config, you must create a machine group and apply the config to it for collection to take effect.

Key parameters

Rules

1. Overwrite update: update-machine-group replaces the entire machine list. Always call get-machine-group first, then pass all parameters back. 2. Deleting a machine group automatically unbinds all applied Logtail configs.

Examples

List machine groups

aliyun sls list-machine-group --project my-project

Pagination: --offset (default 0) and --size (max 500).

Filter by name (partial match):

aliyun sls list-machine-group --project my-project --group-name "container"

Create machine group (IP-based)

aliyun sls create-machine-group --project my-project \
  --group-name container \
  --machine-identify-type ip \
  --machine-list 192.168.5.2

Multiple machines:

aliyun sls create-machine-group --project my-project \
  --group-name my-app-group \
  --machine-identify-type ip \
  --machine-list 192.168.5.2 192.168.5.3 192.168.5.4

Create machine group (custom identifier)

aliyun sls create-machine-group --project my-project \
  --group-name my-custom-group \
  --machine-identify-type userdefined \
  --machine-list my-app-identifier

Apply Logtail config to machine group

aliyun sls apply-config-to-machine-group --project my-project \
  --config-name my-config \
  --machine-group container

List applied configs on a machine group

aliyun sls get-applied-configs --project my-project --machine-group container

Remove Logtail config from machine group

aliyun sls remove-config-from-machine-group --project my-project \
  --config-name my-config \
  --machine-group container

Project Operations

Manage SLS projects. A project is the top-level resource that contains logstores, alerts, dashboards, and other SLS configurations.

Naming requirements

• Globally unique across all Alibaba Cloud regions
• Lowercase letters, numbers, and hyphens (-) only
• Must start and end with a lowercase letter or number
• Length: 3–63 characters
• Cannot be modified after creation

Key parameters

Examples

List projects

aliyun sls list-project

Pagination: --offset (default 0) and --size (default 100, max 500).

Fuzzy filter by name:

aliyun sls list-project --project-name "my-project" --offset 0 --size 50

Create project

aliyun sls create-project \
  --project-name my-new-project \
  --description "Project with recycle bin" \
  --recycle-bin-enabled true

Get project

aliyun sls get-project --project my-project

Update project

aliyun sls update-project --project my-project --description "Updated description"

Delete project

aliyun sls delete-project --project my-project

Put Logs

Write logs to a logstore using put-json-logs. Each --logs flag takes a JSON object representing one log entry.

Key parameters

Rules

1. __time__ is a reserved field — its value must be a string of Unix timestamp in seconds (e.g. "1715769600", not 1715769600). If omitted, the server uses the receive time. 2. The target logstore must already exist. If you need to query or analyze these logs, an index must also be configured (see index.md).

Examples

Single log

aliyun sls put-json-logs --project my-project --logstore my-logstore \
  --logs '{"__time__":"1715769600", "region":"cn-hangzhou", "content":"hello aliyun cli"}'

Multiple logs in one call

Repeat --logs for each log entry:

aliyun sls put-json-logs --project my-project --logstore my-logstore \
  --logs '{"__time__":"1715769600", "region":"cn-hangzhou", "content":"log entry 1"}' \
  --logs '{"__time__":"1715769601", "region":"cn-hangzhou", "content":"log entry 2"}'

With topic and source

aliyun sls put-json-logs --project my-project --logstore my-logstore \
  --logs '{"level":"info","msg":"started"}' \
  --topic "app-server" \
  --source "192.168.1.10"

Log Query

Use get-logs-v2 to query logs. Two modes: query (search) and SQL analytics.

Key parameters

Rules

1. Time range is left-closed right-open [from, to). 2. The logstore must have an index configured before querying (see index.md). 3. Result completeness: check meta.progress in the response — Complete means precise; otherwise retry for accurate results. 4. Pagination: only paginate when the result set is large (many rows or large log entries). For small result sets, fetch all at once to avoid unnecessary round-trips.

Query mode vs SQL mode

Query syntax

* and "someWord" and key1: "value1" and (key2: "value2" or key3: "value3") not key4: "value4"

• * — match all
• "someWord" — full-text search (requires full-text index)
• key: "value" — field filter, contains match (requires field index)
• and / or / not — logic operators; use parentheses for grouping

SQL syntax

Format: <query_syntax> | SELECT ... FROM log WHERE ... ORDER BY ... LIMIT ...

• Left of |: query syntax (e.g. * or status: "500") to pre-filter logs.
• Right of |: standard SQL; table is always log (can be omitted when no join log).
• LIMIT offset, count for pagination; LIMIT all to return everything (use only for small result sets).

Before writing complex SQL, or when a SQL query has failed, try text-to-sql to generate SQL from natural language. See text-to-sql.md.

Examples

Query mode: search all logs

aliyun sls get-logs-v2 --project my-project --logstore my-logstore \
  --accept-encoding lz4 --from 1740000000 --to 1740003600 --line 100

Query mode: filter by field and keyword

aliyun sls get-logs-v2 --project my-project --logstore my-logstore \
  --accept-encoding lz4 --from 1740000000 --to 1740003600 --line 100 \
  --query '* and "flowers" and season: "winter"'

Query mode: pagination (page 2)

aliyun sls get-logs-v2 --project my-project --logstore my-logstore \
  --accept-encoding lz4 --from 1740000000 --to 1740003600 \
  --query 'error' --offset 50 --line 50

Query mode: get total count for pagination

aliyun sls get-histograms --project my-project --logstore my-logstore \
  --from 1740000000 --to 1740003600 --query 'error'

SQL mode: count

aliyun sls get-logs-v2 --project my-project --logstore my-logstore \
  --accept-encoding lz4 --from 1740000000 --to 1740003600 \
  --query '* | select count(*) as total from log'

SQL mode: filter + sort + pagination

# Page 1: first 100 rows, newest first
aliyun sls get-logs-v2 --project my-project --logstore my-logstore \
  --accept-encoding lz4 --from 1740000000 --to 1740003600 \
  --query '* | select * from log where status = 500 order by __time__ desc limit 0, 100'

# Page 2
aliyun sls get-logs-v2 --project my-project --logstore my-logstore \
  --accept-encoding lz4 --from 1740000000 --to 1740003600 \
  --query '* | select * from log order by __time__ desc limit 100, 100'

SQL mode: aggregation

aliyun sls get-logs-v2 --project my-project --logstore my-logstore \
  --accept-encoding lz4 --from 1740000000 --to 1740003600 \
  --query 'status: "500" | select request_uri, count(*) as cnt from log group by request_uri order by cnt desc limit 20'

Text-to-SQL

Use call-ai-tools with tool text_to_sql to generate SQL from natural language via SLS Copilot. Use it when:

• You need complex SQL and want the service to produce a high-quality statement from a natural-language question.
• A SQL query has failed (syntax error, wrong schema, or poor results) — retry by describing the intent in natural language.

Key parameters

Params (JSON body):

• `<current_time>`: human-readable time + Unix timestamp, e.g. 2026-03-18 14:04:11 1773813851
• `<question_text>`: the user's question in natural language

Example

aliyun sls call-ai-tools --tool-name text_to_sql --region cn-shanghai \
  --biz-region-id cn-hangzhou \
  --params '{
    "project": "my-project",
    "logstore": "my-logstore",
    "sys.query": "当前时间: 2026-03-18 14:04:11 1773813851,问题:最近1小时status为500的请求数量是多少"
  }'

Next step

Pass the returned SQL into get-logs-v2 as --query (e.g. * | <returned_sql>). See query-logs.md for usage.