Raysby a6n

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/rays

If 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/dl

Download 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.mp4

For each link, dl prints one line:

added 12 https://example.com/file.zip
rejected ftp://example.com/x: only http and https URLs

Only http and https links are accepted.

List downloads

dl list

One 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.pdf

The 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-runPrint what would move and change nothing.
--allAlso sort files that were there before the first run.
--projectsMove 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 ~/Downloads

Rays 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 --json

Shows 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 Work

set-wait is in seconds. set-dest sends one category somewhere else instead of a folder inside the sorted folder.

AI assistants (MCP)

dl mcp

Runs 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 mcp

Or to any MCP client config:

{"mcpServers": {"rays": {"command": "dl", "args": ["mcp"]}}}
ToolWhat it does
add_downloadsDownload one or more http or https links.
list_downloadsDownloads with state, progress and file name.
sorter_statusWatched folders, categories, settings and recent moves.
sort_folderSort 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

CodeMeaning
0The command worked: every link was added, or the list, status or sort finished.
1At least one link was rejected, or Rays returned an error.
2Wrong usage, or Rays or the sorter could not be reached.

Environment

VariableEffect
DL_NO_LAUNCHIf set, dl does not open Rays when it is not running.
DL_SORTERPath of the sorter to run, instead of the one inside Rays.app.
DL_SOCKETPath 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.txt

Stop a script when a link is rejected:

dl "$URL" || echo "Rays did not take $URL"