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

1. Verify env vars are set (OPENLIST_URL + auth).
2. Clarify the target path(s), operation, and any dry-run requirement.
3. 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

4. For task scripts: lint with uvx ruff check --fix, run with uv run --script.
5. 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