olares-knowledge

knowledge

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.

Use olares-cli knowledge download <verb> --help for syntax.

When to use

• Create and manage URL, yt-dlp, aria2, torrent, HuggingFace, or Wise download-server tasks.
• Inspect providers/qualities, synchronize task changes, manage torrent state, or probe/remove downloaded resources.
• Read or change download preferences and download-server settings.

Not top-level download (installer packages: download component / wizard / check). Not files download (pull a Drive/Sync file) — that lives in olares-files.

Version gate

All verbs require Olares 1.12.7+ because the Settings download edge and provider are both required. If the version cannot be established, follow the shared profile/auth gate before deciding that an upgrade is needed.

Fast paths

Task	Read	First command
Download a URL and know when it lands	creating a task	olares-cli knowledge download create <url> -o json, then download wait <id>
See what is downloading now	this file	olares-cli knowledge download list -o json
Find out which qualities a link offers before taking one	provider/quality inspection	olares-cli knowledge download inspect <url> -o json
Check whether something is already on disk	URL vs resource-path decisions	olares-cli knowledge download file exists <path> -o json

Verb index

Family	Verbs	Read when triggered
start one	create, info, wait	create and follow a task
manage the ones that exist	list, pause, resume, cancel, remove	listing, pausing and retiring tasks
probe + prefs	inspect, prefs get, prefs set	provider/quality inspection
sync	unfinished, sync	cursor and drain semantics
torrent	torrent inspect, stats, peers, files, seed stop/resume; torrent create	torrent selection and seeding
file tools	file exists, file remove	URL vs resource-path decisions
settings	settings get, settings set	global download-server settings

Task and asynchronous semantics

• Create returns a server-side task id; command success does not mean bytes have finished downloading or moving. Take the id and poll info <id> every few seconds rather than blocking a turn on create --wait, which is there for scripts that want one call. Either way the status is the only terminality input: waiting_to_move / moving are still in progress, and error is a failure even when will_auto_retry says a server sweep may pick the row up again.
• Create names the task itself, from the URL's inspect title. Leave --name off unless the user asked for a specific filename, and never build one out of a URL path — a name sent on create is pinned to the row for good. Magnet links, --torrent uploads and HuggingFace repos reject the flag outright: those names come from torrent metadata or the repo id.
• Re-submitting the same URL always creates a new task (no identity dedup). Landing-name collisions are resolved with a (n) suffix; they do not reuse or block an existing row. Create sends Idempotency-Key only to collapse transport retries of one attempt — not URL dedup.
• Pause only applies while waiting or downloading (otherwise 400). Resume, cancel, and remove return 409 while the task is in the yt-dlp mover phase (waiting_to_move / moving) — wait and retry; do not treat pause the same way.
• Task ownership follows the active profile. Do not infer another user's task from an id or try alternate identities.
• inspect is advisory: provider/quality probing may fail while a create still works. Report that uncertainty instead of declaring the URL undownloadable.
• Sync cursors describe change observation, not task completion. Preserve the cursor when continuing an incremental sync.

Safety and escalation

• Confirm create, cancel, remove, seed stop/resume, file remove, preference writes, and global setting writes.
• Before create, confirm destination/app, provider intent, torrent file selection, and whether an existing equivalent task should be reused. Use list / info to check; the CLI does not detect or block duplicates.
• file remove takes a download-server resource path, not an arbitrary local filesystem path.
• A URL that fails for a missing login is not a dead end: cookies live in olares-settings under settings integration cookie. The hand-off does need the user, though — the cookies.txt is their own browser export, so ask for it rather than hunting for a file. See provider/quality inspection for the signals and the full flow.
• Stop on ambiguous URL/resource path, task owner, duplicate-task intent, torrent selection, or any credential request the cookie hand-off does not cover.