Olares Files
Apps & Automationolares-filesOlares Files is an Agent Skill for apps & automation published in the beclab/Olares repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Olares Files via olares-cli files — ls, upload, download, edit, share, SMB/NFS mount, compress/extract archives, Seafile sync on drive/Home, drive/Data, drive/Common, cache, external, cloud. Use for Olares Files, drive, upload, download, share, SMB, NFS, compress, extract, archive, LarePass Files.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/beclab/Olares/blob/HEAD/cli/skills/olares-files/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/olares-files, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
files (per-user files-backend)
CRITICAL — before running any verb here, load the olares-shared skill first (profile selection, login, 401/403 recovery). Flag reference: olares-cli files --help.
Platform model (read once): the storage areas these paths address — the five userspace areas, their backends/durability, uid-1000 ownership, and the system-managed
drive/Homedirectories — are defined once in../olares-shared/references/olares-platform.md. This skill only adds the addressing view.
Source of truth for flags & wire shapes is always
olares-cli files <verb> --help. This file only carries what--helpcannot give: the cross-cutting frontend-path concept, the trailing-slash convention, the five client-side hard constraints, and the verb index.
When to use
- Olares Files, olares-cli files, LarePass Files, drive, Home, Data, Common, sync, cache, upload, download, list, edit, rename, chown
- Archives: compress / extract; inspect (
archive entries/archive cat); manage the async queue (taskcancel / pause / resume) - Share: internal cross-Olares-ID, public link (password / expiration), SMB / Samba, Connect to Server, Seafile sync repos
- Mount external servers: SMB (
smb) and NFS (nfs) - Namespaces:
drive,cache,sync,external,awss3,dropbox,google,tencent,share
Anything outside this scope -> see the Skill suite map in
../olares-shared/SKILL.md(already loaded as the suite prerequisite).
Finding files by name/content (and what the index covers — filenames everywhere vs. full-text only in
/Documents/) lives inolares-search; configure which directories get full-text indexing viasettings search dirsinolares-settings.
Mental model
files is an addressing layer over the platform storage areas (which the platform model owns): you name a resource with a 3-segment frontend path and call a verb. Almost every surprise traces back to the path namespace, trailing-slash intent, the 5 client-side hard constraints, or the >= 1.12.6 version gate. Everything else is per-verb --help.
Paths and namespace support
Every files resource uses the 3-segment frontend path fileType/extend[/subPath]. Before invoking a verb, confirm the namespace is supported and respect the trailing-slash directory convention. The full path grammar, per-verb namespace allow-list, and trailing-slash rules live in references/olares-files-paths.md.
Client-side hard constraints (5 quirks — never work around)
These five rules are enforced client-side and reflect real backend / GUI invariants. The rest of this skill refers to them by number.
1. POST /api/resources/<dir>/ auto-renames on collision
Hitting the directory-create endpoint against an existing directory does NOT return 409 — it silently creates <dir> (1) instead. So files upload does NOT pre-create the destination directory; use files mkdir [-p] first if the parent doesn't exist yet.
2. GET /api/resources/<file> (no trailing slash) returns HTTP 500
The backend's single-file List handler tries to slurp file bytes into a JSON envelope and chokes on most files. The CLI works around it by Stat-ing the PARENT directory and finding the leaf in the items array. If the user reports HTTP 500 on a direct file resource path, the answer is files cat / files download, never "retry the raw URL".
3. external/<node>/ is a virtual volume-listing layer (read-only)
This level has no backing filesystem — it just enumerates attached volumes (hdd1, usb1, smb-...). mkdir, cp/mv destination, upload, AND share (all flavors) reject external/<node>/ (and one level deeper for mkdir); errors point at the corrected shape external/<node>/<volume>/<sub>/. Pure reads (ls, cat, rm, rename) work — that is how the user discovers attached volumes. Mount new volumes via LarePass.
4. The system-managed drive/Home directories are protected
The eleven LarePass bootstrap directories under drive/Home/ (canonical names in the platform model → System-managed Home directories) are guarded: rename, rm, and mv source REFUSE these names at the first level under drive/Home/ only. cp is NOT gated (duplicating bytes preserves the original). Nested content (drive/Home/Pictures/Trip2024/) is fully editable, and other namespaces are unaffected.
5. cache/<node>/ is a node-picker for share-create only
cache/<node>/ IS a real per-node directory on the wire, so ls / cp / mkdir / upload / rm / rename work. BUT the share-create flavors (share internal / share public / share smb) reject the bare node root because a share record there points at no concrete dataset. Use cache/<node>/<sub>/ for shares.
Async task queue (compress / extract)
Unlike every other verb, compress and extract are asynchronous: the POST returns immediately with a task_id, and the byte-writing runs on the server's per-node task queue. Mental model:
- Without
--wait, the command prints thetask_idand exits — the task is still running server-side. - With
--wait, the command polls and prints progress until the task reaches a terminal status. - Ctrl-C / context cancel only stops the local poll; the server-side task keeps running. To actually stop it, use
files task cancel <task_id> --node <node>. - Tasks are per-node — the
<node>segment must match the node the task was queued on (compress/extractprint it in their "queued ... task" line).files task pause/resume/cancelmanage a queued task;cancel --alldrops every task on the node.
Version gate (Olares >= 1.12.6)
The archive surface (compress / extract / archive), the nfs verbs, and the drive/Common namespace were all introduced in Olares 1.12.6. The CLI fails closed on an older (or undetectable) backend with an actionable upgrade message rather than an opaque server 404/500.
- Before reaching for these, check the backend version: the
VERSIONcolumn ofolares-cli profile list, or liveolares-cli settings me version(see olares-shared and platform.md → version model). - Comparison is on
major.minor.patchonly, so a daily build like1.12.6-20260603still counts as>= 1.12.6. - If detection fails (
/api/olares-infounreachable), pass--olares-version <ver>to set it manually.
Authentication transport
Files uses X-Authorization: <access_token> and auto-refreshes expired tokens where the request can be safely replayed. On *ErrTokenInvalidated / *ErrNotLoggedIn, do not retry; use the recovery table in ../olares-shared/SKILL.md.
Verb index
For flags, examples, and wire shapes, always start with olares-cli files <verb> --help. The references below add only what --help cannot give — agent-facing safety constraints, multi-step orchestrations, and common-error → fix maps.
| Verb | --help first, then... | Notes |
|---|---|---|
ls | references/olares-files-ls.md | Drive vs. cloud envelope shapes; --json semantics |
cat | olares-cli files cat --help | Trivial GET to stdout; binary-safe |
download | references/olares-files-download.md | --resume / --overwrite semantics; directory parallel fetch |
upload | references/olares-files-upload.md | Two-stage cloud upload (stage 1 chunks → stage 2 server-side transfer task); --parallel semantics; tencent rejection |
edit | references/olares-files-edit.md | Editor cascade; three-tier size cap; text-only guard; concurrent-delete detection; cloud writeback gap |
mkdir | references/olares-files-mkdir.md | -p skips existing prefixes; auto-rename quirk on the leaf; external/<node>/<X>/ depth-1 guard |
rm | references/olares-files-rm.md | Preflight existence check before prompt; trailing-slash signals dir; protected-names list |
rename | references/olares-files-rename.md | In-place only (synchronous PATCH); protected-names list; bare basename only |
cp / mv | references/olares-files-cp-mv.md | Drop-into-dir semantics; mv source rejects protected names; preflight Stat of every src + dst dir |
chown | references/olares-files-chown.md | UID 0 / 1000 conventions; namespace allow-list; volume-root refusal |
compress | references/olares-files-compress.md | Async (task_id + --wait); format set; single-file-compressor limits; password / split-volume zip+7z only; --level / --conflict. Needs >= 1.12.6 |
extract | references/olares-files-extract.md | Async; <dst-dir>/ must end with /; interactive password retry; --conflict. Needs >= 1.12.6 |
archive | references/olares-files-archive.md | Read-only inspect: entries (--json / --max-entries), cat (-o); bzip2 / xz not previewable. Needs >= 1.12.6 |
task | references/olares-files-task.md | Control the per-node queue: cancel [--all] / pause / resume; pause_able precheck; --force |
share | references/olares-files-share.md | Three flavors (internal / public / smb); directory-only; per-flavor namespace allow-list; update verbs (set-members / set-password / set-smb) |
smb | references/olares-files-smb.md | Mount → external/<node>/<entry>/; host-only address triggers share discovery; favorites history |
nfs | references/olares-files-nfs.md | Mount → external/<node>/<entry>/; bare host triggers export discovery; no credentials; shares the smb favorites book. Needs >= 1.12.6 |
repos | olares-cli files repos --help | List / create / rename / rm Seafile libraries; repo_id is the <extend> segment |
Common errors
| Symptom | Cause | Fix |
|---|---|---|
is the volume listing layer (read-only); point at a real volume, e.g. external/<node>/<volume>/<sub>/ | Quirk #3 — bare external/<node>/ write attempt | Add the <volume> segment |
refusing to mkdir external/<node>/<X>/: depth-1 entries under external/<node>/ are mounted volumes | Quirk #3 depth-1 — would create a phantom volume | Mount the volume via LarePass; target an existing one |
refusing to {rename|delete|mv source} drive/Home/<name>: this is a system-managed Home folder | Quirk #4 — protected name | Pick a different name, or operate on a nested path |
refusing to share cache/<node>/: this is the node-picker layer (no concrete dataset to share) | Quirk #5 — bare cache node-root share | Use cache/<node>/<sub>/ |
file disappeared between stat and fetch | Concurrent-delete race on edit | Re-pull the parent directory and decide |
tencent upload is not supported (or similar) | Tencent's octet protocol is not implemented | Use the LarePass web app for tencent uploads |
<src> does not exist on the server (from cp/mv/rm) | Preflight Stat failed | files ls the parent and confirm the path |
HTTP 500 from /api/resources/<file> | Quirk #2 — backend tried to embed file bytes | Use files cat / files download instead |
require Olares >= 1.12.6 (from compress/extract/archive/nfs) or drive/Common ... requires Olares >= 1.12.6 | Version gate — backend predates the feature | Upgrade Olares, or pass --olares-version if detection misfired |
files compress does not support the "sync"/"" namespace | Archive allow-list (drive/cache/external only) | Stage into drive/Home first, or use the LarePass web app for cloud |
archive requires a password / archive password is incorrect | Encrypted zip / 7z | Supply it via --password-stdin (or answer the interactive prompt) |
previewing "bzip2"/"xz" archives is not supported | Raw single-stream compressor, no entry table | files extract it instead of archive entries / archive cat |
task ... is already <status> / not controllable: ... pause_able=false | Task is terminal or non-interruptible | Nothing to do, or pass --force to send anyway |
For auth-related errors (server rejected the access token, refresh token for X became invalid, …) see ../olares-shared/SKILL.md.
Safety contract
- Write & delete verbs (
rm,rename,cp,mv,chown --uid,compress,extract,share rm,repos rm,smb unmount,nfs unmount,nfs history rm,task cancel) — confirm intent with the user FIRST. Several verbs preflight against the server before any state change; do not bypass that by retry-on-404. rm -fskips the y/N prompt but NOT the preflight existence check — a missing path still aborts.task cancel --alldrops EVERY task on the node (including ones started elsewhere) — confirm explicitly; it refuses in a non-TTY context without--force.- Never echo
access_token/refresh_tokento the terminal. Use--password-stdin(where supported) for SMB and archive passwords too. - Confirm destination paths before any
upload --overwrite,cpto an existing file,compress/extract --conflict overwrite, or any operation that could clobber bytes.