The dl command
One command for Rays: download links, sort folders, and connect AI assistants over MCP.
Install
The Homebrew install puts dl on your PATH:
brew install --cask a6n-ai/tap/raysIf you installed from the DMG, the command is inside the app. Link it once:
ln -s /Applications/Rays.app/Contents/MacOS/dl /opt/homebrew/bin/dlDownload files
dl URL...Give one or more links. Each one is added to Rays and starts when a slot is free.
dl https://example.com/file.zip https://example.com/talk.mp4For each link, dl prints one line:
added 12 https://example.com/file.zip
rejected ftp://example.com/x: only http and https URLsOnly http and https links are accepted.
List downloads
dl listOne line per download: id, state, bytes done / total, file name. Fields are separated by tabs (shown as spaces here).
12 running 52428800/104857600 file.zip
11 done 7340032/7340032 report.pdfThe state is one of queued, running, paused, retrying, done or failed. The total shows ? when the server does not say how big the file is.
Sort a folder
dl sort [FOLDER] [--all] [--dry-run] [--projects]Moves files into category folders such as Work, Images, Installers and Archives, inside FOLDER. Without a folder it sorts ~/Downloads; . is the current folder.
--dry-run | Print what would move and change nothing. |
--all | Also sort files that were there before the first run. |
--projects | Move code-project folders whole into Code/Projects. |
Files changed in the last 10 seconds are skipped, so nothing moves while it is still being written.
dl sort ~/Desktop --dry-run
[dry] setup.dmg -> ~/Desktop/Installers/Apps/Setup.dmg (Installers/Apps rule)Watch a folder
dl watch ~/Downloads
dl unwatch ~/DownloadsRays sorts the folder by itself whenever a new file lands in it, even when the app is closed.
Sorter status and settings
dl status
dl status --jsonShows the wait time, whether renaming is on, the folders Rays sorts, and the last moves.
dl config set-wait 30
dl config set-rename off
dl config set-dest ~/Downloads Work ~/Documents/Work
dl config clear-dest ~/Downloads Workset-wait is in seconds. set-dest sends one category somewhere else instead of a folder inside the sorted folder.
AI assistants (MCP)
dl mcpRuns a Model Context Protocol server on stdin and stdout, so assistants like Claude can use Rays. Add it to Claude Code:
claude mcp add rays -- dl mcpOr to any MCP client config:
{"mcpServers": {"rays": {"command": "dl", "args": ["mcp"]}}}| Tool | What it does |
|---|---|
add_downloads | Download one or more http or https links. |
list_downloads | Downloads with state, progress and file name. |
sorter_status | Watched folders, categories, settings and recent moves. |
sort_folder | Sort a folder. A dry run unless the assistant sets dry_run to false. |
When Rays is not open
dl opens Rays for you and waits up to 5 seconds for it to start. SetDL_NO_LAUNCH=1 to stop it opening the app.
Exit codes
| Code | Meaning |
|---|---|
0 | The command worked: every link was added, or the list, status or sort finished. |
1 | At least one link was rejected, or Rays returned an error. |
2 | Wrong usage, or Rays or the sorter could not be reached. |
Environment
| Variable | Effect |
|---|---|
DL_NO_LAUNCH | If set, dl does not open Rays when it is not running. |
DL_SORTER | Path of the sorter to run, instead of the one inside Rays.app. |
DL_SOCKET | Path of the socket to talk to, instead of~/Library/Application Support/Rays/dl.sock. Never opens the app. |
Scripts
Download every link in a file, one per line:
xargs dl < links.txtStop a script when a link is rejected:
dl "$URL" || echo "Rays did not take $URL"