ton pull - Receive a file from someone running ton push


ton pull [options] [destinationdir]


Receive a file or set of files from a corresponding ton push process on the same network, and write the received files to destinationdir.

If no passphrase is specified on the command line with (--passphrase), ton pull will prompt for one. This must be the same passphrase as used by the ton push process and both endpoints must be on the same network. Specifically, a UDP multicast packet must be able to find its way from here to the pushing process, and it must be able to make a TCP connection to us.

The received file or files will be saved in destinationdir. If no destination directory is given, they will be saved in the current working directory. If a directory is received, the directory structure of its contents is preserved.


-4, --ipv4

Use IPv4 only, not IPv6.

-6, --ipv6

Use IPv6 only, not IPv4.

--announcement-interval sec

Send a round of announcement packets over UDP every sec seconds in an attempt to find our corresponding ton push process. In each round, a multicast and broadcast announcement packet is sent from every non-public IPv4 and IPv6 network interface address we have. The default is 1 second.


Only send broadcast announcement packets, not multicast. By default we send both.


Show the file count and total size of the files the pusher wants to send, and ask the user to confirm or cancel the transfer before proceeding.

--discover-port port

Specify the discovery port number. This is the UDP port number on which we send our announcement packets. ton push must be expecting them on the same port number. The default is 51205.

-f, --force

Overwrite existing files without asking.

-h, --help

Show help and exit.


If we prompt for a passphrase, don’t echo the passphrase as it is typed.


Send announcements from global as well as private IP addresses.

--listen-port port

The TCP port we invite the pusher to connect to in our announcement. To choose an arbitrary unused port, specify 0. The default is 51205.

--max-announcements n

If no connection has been established after we’ve sent n rounds of announcements, give up and fail. The default is 0, which means there is no maximum and we continue until we succeed or get interrupted.


Only send multicast announcement packets, not broadcast. By default we send both.

--multicast-address-ipv4 address

Specify the IPv4 multicast group address to which to send announcement packets. The ton push process must use the same address. The default is, which is for use on private networks.

--multicast-address-ipv6 address

Specify the IPv6 multicast group address to which to send announcement packets. The ton push process must use the same address. The default is The default is ff08:5206:dd93:4290:0891:d264:1444:bd21, which is a private multicast address with organization-local scope.

--multicast-ttl n

Set the TTL or hop-limit value on multicast packets. The default is the OS default, which on Linux is is 1 for IPv4 multicast and the route’s default for IPv6 multicast.

-o dir

Specify the destination (or "output") directory for received files. The -o isn’t strictly required - supplying dir as a positional argument is equivalent. dir will be created if it does not exist. If we receive a directory, it will be created inside this directory. The default is the current directory ("."). As a special case, if dir is - we write all received files to stdandard output, so -o - is equivalent to --output-file -.

--output-file file

Do not save files to any destination directory, but concatenate the contents of all received files and write them to file. Any received directories are ignored and directory structure is not preserved. If file is -, the contents of all received files are written to standard output. This is intended for when you’re only receiving one file, or you want all the files to be concatenated in an arbitrary order. If the pushing side sends more than one file, separating them out into the original files is your problem.

--passphrase string

Use this specific passphrase rather than prompting for one. Conventionally a passphrase is multiple words, but it may be any arbitrary byte string.

-q, --quiet

Don’t show the progress indicator or non-essential commentary.

-v, --verbose

Show extra diagnostic output, including details of announcement packets sent and any incoming connections received as a result.


All these examples assume there’s someone on the network running ton push with the same passphrase as us.
Receive files into the current directory:

$ ton pull

Receive files into a named directory:

$ ton pull /home/joe/junkfromfred/

Specify a passphrase on the command line rather than a prompt:

$ ton pull --passphrase "hovercraft full of eels"

Write received files to stdout, without progress updates:

$ ton pull -q -


ton(1), ton-push(1)