AList CLI (Cloud Storage CLI for AList)

AList file management CLI for OpenClaw. Supports upload, download, list, mkdir, rm, mv, search, url. Auth via environment variables with auto-refresh. Trigge...

Security Scan

The skill appears to implement an AList CLI that reasonably needs AList credentials, but there are inconsistencies and a few risky instructions (sudo symlink, persistent shell writes, odd 'uv' commands) that merit caution before installing or running it.

Purpose & Capability

Name/description, SKILL.md, README.md and the included Python script all align: this is an AList file-management CLI and legitimately needs ALIST_URL, ALIST_USERNAME, and ALIST_PASSWORD. However the registry metadata claims 'Required env vars: none' and 'Primary credential: none', which contradicts the SKILL.md and code — that's an incoherence that should be resolved before trusting the skill.

Instruction Scope

SKILL.md and ONBOARDING.md direct the agent/user to set credentials in environment variables and even to persist them to shell profiles (~/.bashrc). The onboarding also recommends creating a symlink in /usr/local/bin using sudo (modifying system PATH) and runs various install commands. Those actions go beyond a read-only helper: they persist credentials and modify system paths. ONBOARDING uses an unexplained 'uv' command in install steps (e.g., 'uv pip install', 'uv venv') which is nonstandard and could be a placeholder or invoke unknown tooling — that is a red flag.

Install Mechanism

There is no formal install spec in registry (instruction-only), so nothing will be installed automatically by the platform. The onboarding suggests installing Python dependency 'requests' via pip (including sudo pip & --break-system-packages fallback) and optionally creating a system symlink. Those steps are typical but can be risky if done with sudo or when following untrusted instructions; no remote download/URL/extract behavior is present in the spec or code.

Credentials

The skill legitimately needs ALIST_URL, ALIST_USERNAME, ALIST_PASSWORD and optionally ALIST_AUTH_TOKEN/ALIST_USER_INFO for token caching. But the registry metadata does not declare those env vars — a mismatch. The onboarding encourages persisting credentials to ~/.bashrc (storing plaintext passwords), which increases risk of credential leakage. The script also writes tokens into the process environment (os.environ) but does not securely persist them itself — persistence is left to user instructions that recommend writing to shell config.

Persistence & Privilege

The skill does not request always:true and doesn't change other skills' config. However onboarding explicitly instructs creating a system-wide symlink (/usr/local/bin) and writing exports to shell startup files, which gives the skill a persistent CLI presence and encourages persistent storage of credentials. Those are privileged/lasting changes and should be performed only after review.

What to consider before installing

Key points to consider before installing or running this skill: - The code and documentation match the stated purpose (AList CLI) and the Python script calls only the target AList server APIs, which is expected. But the registry metadata incorrectly lists no required environment variables while SKILL.md and the script clearly require ALIST_URL, ALIST_USERNAME, and ALIST_PASSWORD — ask the publisher to fix this discrepancy. - Do NOT paste your production username/password into a skill without verifying the upstream repository and its maintainer. The README links to a GitHub repo; manually inspect that upstream source on GitHub (check commits, stars, issues) before trusting it. - Prefer using a short-lived or least-privilege account/token on your AList server rather than your primary password. If possible create a service account with limited permissions. - Avoid following onboarding steps that run pip with sudo or write exports into ~/.bashrc unless you understand and accept the risk. Instead: - Use a Python virtual environment (venv) and run the script via .venv/bin/python to avoid system-wide installs. - Use an alias rather than creating a system symlink requiring sudo. - Do not persist plaintext credentials in shell startup files; if you must persist a token, store it in a secure secrets store or a file with restrictive permissions. - The ONBOARDING.md uses a nonstandard 'uv' command in several steps; treat that as suspicious — verify what 'uv' is in your environment before running any 'uv' command. - If you run the tool, monitor outgoing network traffic to ensure it only communicates with your ALIST_URL. The code appears to talk only to the configured ALIST_URL endpoints, but you should validate that at runtime. - If you want to proceed safely: run the skill in an isolated environment/container, use a disposable AList account, do not persist credentials globally, and review the full scripts (especially any truncated parts) to ensure there are no hidden exfiltration paths. If you want, I can: (1) fetch and display the rest of the truncated Python file to review the remaining logic, (2) help you craft safer onboarding steps (venv, alias), or (3) show exact lines where credentials are read/written.

AList CLI

• Author: LeeShunEE
• Organization: KinemaClawWorkspace
• GitHub: https://github.com/KinemaClawWorkspace/alist-cli

AList file management CLI. Auth token managed via environment variables with auto-login and auto-refresh.

⚠️ Before First Use | 首次使用必读

首次使用此 skill 前，必须先读取 ONBOARDING.md 完成环境配置。

• 环境不可用（命令不存在、依赖缺失、连接失败）→ 读取 ONBOARDING.md 按步骤排查修复
• 首次配置 → 读取 ONBOARDING.md 完成 6 步配置
• 配置完成后 → 直接使用下方 Run Commands

Environment Variables

Variable	Required	Description
ALIST_URL	✅	AList server URL (e.g. https://your-alist-server)
ALIST_USERNAME	✅	Login username
ALIST_PASSWORD	✅	Login password
ALIST_AUTH_TOKEN	❌	Auth token (auto-obtained via login, skip manual set)
ALIST_USER_INFO	❌	User info JSON (auto-obtained via login, skip manual set)

Run Commands

python3 scripts/alist_cli.py <command> [args]
# or with venv:
# .venv/bin/python scripts/alist_cli.py <command> [args]

Commands

Command	Description
login [username] [password]	Login (outputs export statements to source)
ls [path]	List files
get <path>	Get file info + all URLs
url <path>	Get preview/download URLs for file or folder
mkdir <path>	Create folder
upload <local> <remote>	Upload file (outputs preview + download URL)
rm <path>	Delete file
mv <src> <dst>	Move file
search <keyword> [path]	Search files
whoami	Current user info

Upload Behavior | 上传行为

上传前必须判断文件用途，选择正确的目标路径：

判断规则

场景	目标路径	说明
外部访问（分享给他人、公开文件）	/public/...	Guest 可见，预览和下载链接无需登录
内部使用（个人文件、工具输出、临时文件）	/private/storage/...	需要登录才能访问

如何判断：

1. 用户明确说"分享给 XX"、"发给别人"、"外部" → /public/
2. 用户说"内部"、"私有"、"自己看"、"备份" → /private/storage/
3. 用户未说明 → 必须询问文件用途
4. 批量上传多个文件到同一个目标 → 可以创建新文件夹整理
5. 单个文件 → 一般直接上传到已有目录，不新建文件夹（除非用户指定或目标目录为空）

文件夹创建规则

• ❌ 不要随意创建新文件夹
• ✅ 用户明确要求时才创建
• ✅ 批量上传且目标目录为空时，可以创建子文件夹
• ✅ 用户指定路径时，自动创建（mkdir -p 行为由 API 保证）

URL Rules

AList 文件有两种链接：

1. 预览链接

{ALIST_URL}{path}

• 从 raw_url 去掉 /p 前缀和 ?sign=xxx 参数
• 内部文件（/private/）：需要 AList 登录态才能预览
• 外部文件（/public/）：无需登录即可预览
• 例: https://cloud.example.com/public/docs/notes.md

2. 下载直链

API 返回的 raw_url 字段（包含 /p/ 前缀和 ?sign 签名）

• 直接下载文件，无需登录，curl/wget 可用
• 签名有时效性，过期后需重新通过 API 获取
• 例: https://cloud.example.com/p/public/docs/notes.md?sign=abc123=:0
• 分享文件时优先使用此链接

Directory Structure | 目录结构

/ (root)
├── public/        ← 外部访问（guest 挂载点）
│   └── ...
└── private/       ← 内部文件（需登录）
    └── storage/   ← 用户存储
        └── ...

Path Mapping

user_path (用户输入)  →  real_path (AList API 使用)
/public/docs/a.md    →  /public/docs/a.md       (外部)
/private/storage/a   →  /private/storage/a       (内部)

• base_path 通过登录自动获取（/api/me 接口），当前为 /
• 预览链接基于 real_path（去掉 /p 和 ?sign）
• 下载直链使用 API 返回的 raw_url

Auth Behavior

• Auto-login: Script checks ALIST_AUTH_TOKEN on startup. If missing, auto-logins with ALIST_USERNAME + ALIST_PASSWORD.
• Auto-refresh: If API returns 401, automatically re-logins and retries.
• Manual login: alist login command outputs export statements. User should eval $(alist login) or manually source them.

References

• references/openapi.json - AList API specification