Shared front door: load
../olares-shared/SKILL.mdfor 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). Notfiles download(pull a Drive/Sync file) — that lives inolares-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 oncreate --wait, which is there for scripts that want one call. Either way the status is the only terminality input:waiting_to_move/movingare still in progress, anderroris a failure even whenwill_auto_retrysays a server sweep may pick the row up again. - Create names the task itself, from the URL's inspect title. Leave
--nameoff 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,--torrentuploads 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 sendsIdempotency-Keyonly to collapse transport retries of one attempt — not URL dedup. - Pause only applies while
waitingordownloading(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.
inspectis 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/infoto check; the CLI does not detect or block duplicates. file removetakes 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-settingsundersettings integration cookie. The hand-off does need the user, though — thecookies.txtis 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.