Skill: andrewreid/seafile (version 1.0.1)

--- name: seafile-skill description: Search, download, and upload files in a single Seafile library using a repo token. Use when an agent needs library-scoped filename or path search, exact-path downloads, or uploads into a Seafile library via the repo-token API. homepage: https://github.com/andrewreid/seafile-skill metadata: {"clawdbot":{"emoji":"🗂️","requires":{"bins":["curl","jq"],"env":["SEAFILE_BASE_URL","SEAFILE_REPO_TOKEN"]},"primaryEnv":"SEAFILE_REPO_TOKEN"}} compatibility: Requires curl, jq, a valid Seafile repo token, and network access to the target Seafile server. --- # Seafile Skill ## Overview Use this skill to interact with one Seafile library through the repo-token API. It is designed for three tasks only: - Search for files or folders by filename or path fragment inside the token's library scope - Download a file by exact Seafile path - Upload a local file into an existing Seafile directory This skill does not cover full-text content search, cross-library discovery, deletes, renames, moves, or share-link management. For endpoint details, see [references/seafile-api.md](references/seafile-api.md). For reusable shell patterns, see [references/command-patterns.md](references/command-patterns.md). ## Prerequisites Required: - `curl` - `jq` - Network access to the Seafile server - `SEAFILE_BASE_URL` - `SEAFILE_REPO_TOKEN` with access to the target library Optional with defaults: - `SEAFILE_LIBRARY_ROOT`, which defaults to `/` - `SEAFILE_OUTPUT_DIR`, which is only needed when saving downloaded files locally Export the required variables before running commands. The optional variables below are shown with their recommended defaults: ```bash export SEAFILE_BASE_URL="https://seafile.example.com" export SEAFILE_REPO_TOKEN="<repo-token>" export SEAFILE_LIBRARY_ROOT="/" # optional export SEAFILE_OUTPUT_DIR="$PWD/downloads" # optional, used for downloads mkdir -p "$SEAFILE_OUTPUT_DIR" ``` Defaults and expectations: - `SEAFILE_BASE_URL` should be the server origin without a trailing slash - `SEAFILE_LIBRARY_ROOT` defaults to `/` if you do not override it - `SEAFILE_OUTPUT_DIR` is only needed for downloads - All Seafile paths in this skill are absolute library paths such as `/`, `/docs`, or `/docs/report.pdf` ## Authentication The repo-token endpoints use the repo token in the `Authorization` header. Use this default form unless your deployment documents a different token scheme: ```bash AUTH_HEADER="Authorization: Token $SEAFILE_REPO_TOKEN" API_BASE="${SEAFILE_BASE_URL%/}/api/v2.1/via-repo-token" ``` Before doing search, download, or upload, verify the token and library scope: ```bash curl --fail --silent --show-error \ -H "$AUTH_HEADER" \ "$API_BASE/repo-info/" | jq ``` If this fails with `401` or `403`, stop and fix the token, permissions, or server URL before continuing. ## Search Workflow Use repo-token directory listing and filter locally with `jq`. This is filename and path search, not full-text search. ### 1. List items from a starting path ```bash START_PATH="${SEAFILE_LIBRARY_ROOT:-/}" curl --fail --silent --show-error \ -G \ -H "$AUTH_HEADER" \ --data-urlencode "path=$START_PATH" \ --data-urlencode "recursive=1" \ "$API_BASE/dir/" ``` Useful query parameters: - `path`: directory to inspect, default `/` - `recursive=1`: walk the subtree recursively - `type=f`: files only - `type=d`: directories only ### 2. Filter by filename fragment ```bash NEEDLE="report" START_PATH="${SEAFILE_LIBRARY_ROOT:-/}" curl --fail --silent --show-error \ -G \ -H "$AUTH_HEADER" \ --data-urlencode "path=$START_PATH" \ --data-urlencode "recursive=1" \ "$API_BASE/dir/" | jq -r --arg needle "$NEEDLE" ' .dirent_list[] | select((.name // "") | ascii_downcase | contains($needle | ascii_downcase)) | [.type, .parent_dir, .name] | @tsv ' ``` ### 3. Filter by full path fragment ```bash PATH_FRAGMENT="2026/q2" START_PATH="${SEAFILE_LIBRARY_ROOT:-/}" curl --fail --silent --show-error \ -G \ -H "$AUTH_HEADER" \ --data-urlencode "path=$START_PATH" \ --data-urlencode "recursive=1" \ "$API_BASE/dir/" | jq -r --arg needle "$PATH_FRAGMENT" ' .dirent_list[] | (.parent_dir + "/" + .name | gsub("//+"; "/")) as $full_path | select($full_path | ascii_downcase | contains($needle | ascii_downcase)) | [$full_path, .type] | @tsv ' ``` When you need exact metadata for one known file path, consult the repo-token file-info section in [references/seafile-api.md](references/seafile-api.md) and confirm the route shape against the target deployment if needed. ## Download Workflow Downloads are exact-path only. `SEAFILE_OUTPUT_DIR` is optional overall and only matters if you want this skill to save the downloaded file to a local directory. ### 1. Request a one-time download link ```bash REMOTE_FILE="/docs/report.pdf" DOWNLOAD_LINK=$(curl --fail --silent --show-error \ -G \ -H "$AUTH_HEADER" \ --data-urlencode "path=$REMOTE_FILE" \ "$API_BASE/download-link/" | jq -r '.') ``` ### 2. Download the file to a local path ```bash LOCAL_FILE="$SEAFILE_OUTPUT_DIR/$(basename "$REMOTE_FILE")" curl --fail --silent --show-error --location \ "$DOWNLOAD_LINK" \ -o "$LOCAL_FILE" ``` Notes: - `download-link/` returns a URL string, not a JSON object - Use `--location` because the returned URL may redirect - Keep the remote path exact, including spaces, case, and file extension ## Upload Workflow Uploads send a local file into an existing Seafile directory. ### 1. Request an upload link ```bash UPLOAD_LINK=$(curl --fail --silent --show-error \ -H "$AUTH_HEADER" \ "$API_BASE/upload-link/" | jq -r '.') ``` ### 2. Upload one local file ```bash LOCAL_FILE="./artifact.zip" TARGET_DIR="/incoming" curl --fail --silent --show-error \ -F "file=@${LOCAL_FILE}" \ -F "parent_dir=${TARGET_DIR}" \ -F "replace=0" \ "${UPLOAD_LINK}?ret-json=1" | jq ``` Upload behavior: - `parent_dir` must be an absolute library path like `/incoming` - `replace=1` overwrites an existing file with the same name - `replace=0` preserves the existing file and lets Seafile rename the new upload if needed - `?ret-json=1` returns structured JSON and should be used by default If you need Seafile to create nested folders beneath an existing parent, add `-F "relative_path=subdir1/subdir2/"` to the upload request. ## Error Handling Check failures in this order: - `401` or `403` The token is missing, expired, malformed, or does not allow the requested action. - `404` The base URL or endpoint is wrong, or the server is not exposing that API path. - `440` or similar upload validation errors The filename is invalid for the target server. - `442` or `443` The file is too large or the library is out of quota. - Directory listing or download returns no match Re-check the starting directory, exact remote path, and case sensitivity. - Upload succeeds but lands in the wrong place Re-check `parent_dir` and any `relative_path` value. When a request is failing and the server output is unclear, remove `--silent` temporarily and inspect headers with `curl -i`. ## Examples ### Find files matching a name fragment ```bash NEEDLE="invoice" START_PATH="/finance" curl --fail --silent --show-error \ -G \ -H "Authorization: Token $SEAFILE_REPO_TOKEN" \ --data-urlencode "path=$START_PATH" \ --data-urlencode "recursive=1" \ --data-urlencode "type=f" \ "${SEAFILE_BASE_URL%/}/api/v2.1/via-repo-token/dir/" | jq -r --arg needle "$NEEDLE" ' .dirent_list[] | select((.name // "") | ascii_downcase | contains($needle | ascii_downcase)) | (.parent_dir + "/" + .name | gsub("//+"; "/")) ' ``` ### Download one file by exact path ```bash REMOTE_FILE="/finance/invoices/april-2026.pdf" DOWNLOAD_LINK=$(curl --fail --silent --show-error \ -G \ -H "Authorization: Token $SEAFILE_REPO_TOKEN" \ --data-urlencode "path=$REMOTE_FILE" \ "${SEAFILE_BASE_URL%/}/api/v2.1/via-repo-token/download-link/" | jq -r '.') curl --fail --silent --show-error --location \ "$DOWNLOAD_LINK" \ -o "$SEAFILE_OUTPUT_DIR/april-2026.pdf" ``` ### Upload one local file into a target folder ```bash TARGET_DIR="/incoming/reports" LOCAL_FILE="./build/report.csv" UPLOAD_LINK=$(curl --fail --silent --show-error \ -H "Authorization: Token $SEAFILE_REPO_TOKEN" \ "${SEAFILE_BASE_URL%/}/api/v2.1/via-repo-token/upload-link/" | jq -r '.') curl --fail --silent --show-error \ -F "file=@${LOCAL_FILE}" \ -F "parent_dir=${TARGET_DIR}" \ -F "replace=1" \ "${UPLOAD_LINK}?ret-json=1" | jq ```


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)