Receive files from the command line

Three ways to receive, and when each applies

Which command you run depends on who's starting the transfer and how the two machines know each other:

• relayium receive <code> [destdir] — someone sends to you across networks using a pairing code they minted (with the CLI, a Relayium app or the web page) and passed to you out of band. End-to-end encrypted, relayed whenever the server issues a relay for the code, with a SAS code you can compare.
• relayium serve [--dir D] [--port N] [--once] [--allow-delete] — this machine listens for daemon-direct relayium:// pushes, on port 9031 by default.
• relayium down <link> [destdir] — fetch and decrypt a stored link; no account is needed to download.

receive: someone sends you a file across networks

This is the receiving half of relayium send. The other person runs relayium send <path> on their end (after relayium login); their CLI mints a 6-digit code, good for 5 minutes, and prints it. They tell you what it is over any channel you both trust — a call, a chat message. You run receive with that code:

relayium receive 483920

# or into a specific directory
relayium receive 483920 ./downloads

1. Agree with the sender on when they will run send. The code starts expiring the moment it is minted, not the moment you get it.

2. Take the six digits over a channel you both trust — a call, a chat window, the room you are both in.

3. Run receive from the directory where the files should land, or name one explicitly.

   relayium receive 483920

   relayium receive 483920 ./downloads

4. When both terminals print a verification code, read yours aloud and check it matches theirs. It is not the pairing code, and it is the only thing that rules out a substituted endpoint.

5. Leave the terminal alone until it returns to the prompt. This is one live session: closing either end stops the transfer.

$ relayium receive 483920
verification code (SAS): 271044 — not the pairing code; compare it on both ends to rule out a substituted endpoint
path: relay (selected pair …)

• The connection is end-to-end encrypted; both ends print the same SAS (short authentication string) once connected. Compare it out of band to confirm that the keys the two ends exchanged were not substituted and the rendezvous service did not impersonate either endpoint. The SAS authenticates the endpoints; it does not prove every network hop.
• No destination given: files land in the current directory.
• Same relay rule as send: whenever the server issues a relay for the code, every byte goes through that encrypted relay and counts toward the monthly traffic allowance of the account that minted the code — the sender's, never yours — when the relay reports it as billable usage: the relay nodes Relayium operates do, while Relayium's coturn TURN servers bill nothing today — their legacy usage ingest is disabled, and their optional accounting ingest is off by default and, if configured in shadow mode, records measurements without writing to the billing ledger, usage periods or any allowance. Only when no relay is issued do the two ends connect peer to peer, and then the transfer fails if no direct path exists.
• The code is the same pairing code the apps and the web page use: a sender on relayium.com or in a Relayium app can read you a code and you receive it here, and a code minted by relayium send can be joined from the web page instead of the CLI.
• The receiver never needs an account, on any network. Only the sender signs in, so their CLI can mint the code.

serve: turn this machine into a listening drop box

serve works the other way around: instead of you reaching out, other machines push straight to you over relayium:// — built for machines you already trust, like your own laptop pushing to a NAS, or a build server dropping artifacts on a box you own — over a pinned TLS 1.3 connection, no SSH, no rendezvous.

relayium serve

# a specific directory, port, and allowing delete requests
relayium serve --dir ~/incoming --port 9031 --allow-delete

1. Start the listener, naming the directory pushes should land in.

   relayium serve --dir ~/incoming

2. When a new machine pushes for the first time, serve shows its address and fingerprint and asks. Approve it once and later pushes from that fingerprint go through silently.

3. If this listener will run without a terminal, do not rely on that prompt — nobody is there to answer it, and an unrecognised pusher is rejected outright. Pre-authorize instead, as the next section describes.

• The first time a new machine pushes to you, serve (running in a terminal) shows its address and fingerprint and asks you to approve it once; after that, pushes from the same fingerprint go through silently.
• Without a terminal — a systemd service, a script with no TTY — there's no one to ask, so an unrecognized pusher is rejected outright. Pre-authorize it instead, using the fingerprint the pusher prints with relayium id:

Pre-authorize for unattended serve

For a serve that runs unattended (systemd, a background script), have the pusher run relayium id to print its fingerprint, then approve it ahead of time from the receiving side:

relayium authorize <fingerprint>

• --dir sets where files land (default the current directory); --once accepts a single transfer and exits; --allow-delete lets an incoming --delete (mirror) request actually remove files here, and is off by default.
• --config-dir (default ~/.config/relayium) is where this host's identity and its authorized-fingerprints list live — override it if you're running serve as a dedicated service.

down: fetch a stored encrypted link

down retrieves ciphertext held by Relayium, decrypts it locally and verifies it before installing the output.

relayium down '<complete-link-with-#k-fragment>' ./local-dest

1. Copy the complete link, including its #k= fragment. That fragment holds the only decryption key and is never sent to Relayium's server.

   relayium down '<complete-link-with-#k-fragment>' ./local-dest

2. Choose an existing writable destination directory, or create it before downloading.

   mkdir -p ./local-dest

3. Run down with the complete link. The recipient does not sign in.

   relayium down '<complete-link-with-#k-fragment>' ./local-dest

• The server receives the URL before # but never the fragment containing the decryption key.
• down reconnects and continues within the same invocation, up to five attempts. If that invocation ultimately fails, it deletes the partial output; a later run starts over.
• SSH destinations, relayium pull, -i and -p are retired in the current CLI.

When it doesn't work

Five failures cover nearly every unsuccessful receive. Which command you were running decides which of them applies, and each has a line to read or a command to run that settles it.