olares-files

Original：🇺🇸 English

Translated

Olares Files via olares-cli files — browse known paths; upload or download file bytes; edit, share, mount SMB/NFS, compress/extract archives, and manage Seafile sync across Drive/cache/external/cloud. Use for Olares Files and LarePass Files operations, not URL/yt-dlp/torrent download tasks (olares-knowledge).

2installs

Sourcebeclab/olares

Added on2026-08-13

NPX Install

npx skill4agent add beclab/olares olares-files

SKILL.md Content

View Translation Comparison →

files (per-user files-backend)

Shared front door: load
../olares-shared/SKILL.md
for suite routing, active-profile selection, platform entry points, and the auth proceed/stop gate. Load its auth reference only when login, profile switching, token storage, or auth recovery is actually needed.

Load the shared platform model when the task depends on userspace backends, durability, uid 1000, or system-managed Home directories. Use

olares-cli files <verb> --help

for syntax.

When to use

Address, read, write, move, delete, share, or transfer known Olares file paths.
Compress/extract or manage their asynchronous task queue.
Mount SMB/NFS servers or manage Seafile repositories.

Finding files by name/content (and what the index covers — filenames everywhere vs. full-text only in
/Documents/
) lives in
olares-search
; configure which directories get full-text indexing via
settings search dirs
in
olares-settings
.

Paths and namespace support

Every resource uses

fileType/extend[/subPath]

. Before invoking a verb, confirm its namespace support and whether the target is a file or directory. Load path grammar and namespace rules whenever constructing or interpreting a path.

Backend quirks that change decisions

Directory creation may auto-rename on collision instead of returning conflict. Upload does not pre-create destination directories. If exact naming matters, inspect the parent and create it deliberately.
Direct raw GET of a file resource may return HTTP 500. Use
```
files cat
```
or
```
files download
```
; do not retry the raw resource URL.
```
external/<node>/
```
is a virtual volume picker, not a write destination. Writes need
```
external/<node>/<volume>/...
```
.
Eleven reserved names are system-managed at the first level under
```
drive/Home/
```
.
```
rename
```
,
```
rm
```
, and
```
mv
```
as a source are refused before any request goes out;
```
cp
```
and everything nested stay editable. The refusal enumerates all eleven and is a platform invariant, not a permission error to retry — act on a child instead. The names are matched exactly, so a name that merely looks similar is not protected.
```
cache/<node>/
```
is valid storage but not a concrete dataset for share creation; share
```
cache/<node>/<sub>/
```
.

Async task queue (compress / extract)

```
compress
```
and
```
extract
```
enqueue server-side work and return a task id unless waiting.
Ctrl-C stops only the local poll. Cancel the server task explicitly if that is the user's intent.
Tasks are per-node; retain the node printed when the task was queued.
```
task cancel --all
```
affects every task on the node, including work started elsewhere.

Version gate (Olares >= 1.12.6)

Archives, NFS, and

drive/Common

require Olares 1.12.6+. Treat daily builds by their

major.minor.patch

base. Follow the shared auth/version gate when the backend version cannot be established.

Verb index

Verb	Read when triggered
`ls`	listing and cloud shapes
`cat`	`files cat --help`
`download`	resume, overwrite, directory downloads
`upload`	collision decisions and cloud transfer
`edit`	text/size guards and writeback
`mkdir`	parents, auto-rename, external depth
`rm`	existence, directory intent, protected paths
`rename`	in-place rename and protected paths
`cp` , `mv`	destination and overwrite semantics
`chown`	UID and namespace decisions
`compress`	formats, conflicts, passwords, async task
`extract`	destination, conflicts, passwords, async task
`archive`	read-only archive inspection
`task`	per-node cancel/pause/resume
`share`	internal/public/SMB sharing
`smb`	discovery, mount, history
`nfs`	export discovery and mount
`repos`	`files repos --help`

Safety contract

Treat the user's requested file operation and named paths as task-scope authorisation. Ask again only when a target is ambiguous, bytes may be overwritten without explicit intent, deletion expands beyond the named target, or the action leaves that scope.
For upload, first decide whether collision should overwrite, fail, or create a distinct name; backend auto-renaming is not an acceptable implicit decision.
Do not retry a missing-path preflight by weakening safety flags.
Confirm
```
task cancel --all
```
separately because it affects unrelated work on that node.
Never expose tokens or passwords. Use stdin-based secret input where available.
Stop on ambiguous frontend paths, node/volume identity, overwrite intent, or concurrent deletion; re-list the parent and ask the user.