olares-files

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.

Fast paths

Task	Read	First command
Put a local file in the user's Drive	collision decisions and cloud transfer	olares-cli files upload ./report.pdf drive/Home/Documents/
See what is in a directory	this file	olares-cli files ls drive/Home/ -o json
Read one file's bytes	this file	olares-cli files cat drive/Home/Documents/report.pdf
Address anything outside drive/Home	path grammar and namespace rules	olares-cli files ls sync/<repo_id>/

Paths and namespace support

Every resource is fileType/extend[/subPath], where fileType is one of drive, cache, sync, external, awss3, dropbox, google, tencent, share, internal, and extend is the volume, repo or account inside it — drive/Home, drive/Data, drive/Common, a node name, a Seafile repo id, a cloud account key. That much covers an ordinary Drive path.

Load path grammar and namespace rules when the target is outside drive/, or when you need to know whether the verb you are about to run supports that namespace at all — support is per verb, and several verbs refuse namespaces their neighbours accept.

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	Raw bytes to stdout, and the supported way to read one: a direct GET of the file resource answers 500
download	resume, overwrite, directory downloads
upload	collision decisions, resume, concurrency; the second stage a cloud destination adds
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	Sync (Seafile) libraries by id; the repo id is what a sync/ path is built from

Safety and escalation

• 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.