| name | openlist |
| description | Manage files on an OpenList (AList-compatible) cloud storage server. Use when the user wants to list, search, copy, move, rename, delete, upload, or download files on cloud storage managed by OpenList/AList. Triggers on phrases like "openlist", "alist", "manage cloud storage", "network drive", or file operations against a self-hosted file server. Also use when the user mentions Emby, Jellyfin, or media library organization on cloud storage. |
OpenList File Manager
Manage files on an OpenList server via its REST API. OpenList is an AList-compatible multi-storage file listing program.
Setup
{project} is the git repo name (if in a git repo) or the basename of the current working directory.
Copy both SDK and CLI to ~/.agents/sessions/{project}/scripts/, then load env vars:
cp skills/openlist/scripts/openlist_client.py skills/openlist/scripts/openlist.py ~/.agents/sessions/{project}/scripts/
source ~/.zshenv
Environment variables
| Variable | Required | Notes |
|---|
OPENLIST_URL | Yes | Base URL e.g. http://localhost:5244 |
OPENLIST_TOKEN | One of these | Pre-issued JWT token (preferred) |
OPENLIST_USERNAME | One of these | Username for login |
OPENLIST_PASSWORD | If USERNAME set | Password for login |
Workflow
- Verify env vars are set (
OPENLIST_URL + auth).
- Clarify the target path(s), operation, and any dry-run requirement.
- Pick the right approach:
| Scenario | Approach |
|---|
| Single operation (ls, rename, mv, mkdir, rm, regex-rename) | Bundled CLI directly |
| Multi-step workflow (mkdir → move → rename → cleanup) | Task script importing SDK |
| Needs dry-run preview of a complex plan | Task script |
| Needs retry logic (e.g. Quark async moves) | Task script |
- For task scripts: lint with
uvx ruff check --fix, run with uv run --script.
- Report results.
Bundled CLI & SDK
scripts/openlist_client.py — OpenListClient class + size_fmt helper. Import in custom scripts:
import sys
from pathlib import Path
sys.path.insert(0, str(Path(__file__).parent))
from openlist_client import OpenListClient
scripts/openlist.py — CLI wrapper covering all endpoints. Run as:
SCRIPT="uv run --script ~/.agents/sessions/{project}/scripts/openlist.py"
$SCRIPT ls "/quark/来自：分享/TVs"
$SCRIPT rename "/path/to/old" "new-name"
References
| File | When to read |
|---|
references/use-cases.md | Emby/Jellyfin naming, common CLI recipes |
references/client-template.md | Writing custom task scripts with SDK |
references/api.md | Full API endpoint details |
When the user mentions Emby, Jellyfin, or media library organization, read references/use-cases.md first.
Script conventions
- Save task scripts to
~/.agents/sessions/{project}/scripts/{script_name}.py
- Always offer
--dry-run for destructive operations
- Print a summary table (via
rich.table) before executing
- Quark storage moves are async — add retry/delay between move and rename steps
