Skip to content
Get packs

Guide · Open source

How to use transfer.sh: upload files from the terminal

Updated · written with AI from the project's own documentation and checked against our catalogue data

transfer.sh is an open-source server for sharing files from the command line. You upload a file with curl and get back a link you can share. This guide shows the basic upload, download and delete commands, the optional limits and encryption headers, and the server settings you need before running your own instance. The README says the project is meant for hosting your own installation, so read the security note before you begin.

transfer.shdutchcoders/transfer.sh · ★ 15.9k · MIT

Quick start

  1. 1Read the security warning. Review the README's security warning about X-Forwarded-For spoofing before deploying anything.
  2. 2Clone the repository. Run git clone on the dutchcoders/transfer.sh repository to get the source code.
  3. 3Prepare the prerequisites. Install Go, and Docker if you plan to use the Docker image. The README excerpt does not state a required Go version.
  4. 4Choose a storage provider. Select local, s3, gdrive or storj and set the matching options from the README table.
  5. 5Upload a file. Run curl --upload-file with your file and the destination URL, then save the X-Url-Delete header.
  6. 6Add limits or encryption. Use Max-Downloads or Max-Days headers, or encrypt with gpg before upload.

Understand what transfer.sh is before you start

transfer.sh is a server, not a website you simply visit. The repository contains the server code needed to create your own instance. It supports the s3 (Amazon S3), gdrive (Google Drive), storj (Storj) and local file system storage providers.

The maintainer's README states that the official position is that you should host your own installation if you want to use the software. The repository does not list or advertise third-party public installations.

  • Good fit: developers comfortable with a terminal who run their own server.
  • Not a fit: people who want a ready-made service with no setup.

Read the security warning first

The README opens with a security warning: an IP filter and HTTP auth bypass via unauthenticated X-Forwarded-For header spoofing. Check the linked issue and make sure your deployment is protected before you expose the service to anyone else.

If you cannot secure a server, do not run this software on one.

Install transfer.sh by cloning and building

The README's install method is to clone the repository. The listed prerequisites are Go (the README excerpt does not state a version) and, optionally, Docker if you use the Docker image.

Clone the repository with the command below. The README excerpt does not give build commands, so follow the project's own documentation for building after you clone it.

git clone https://github.com/dutchcoders/transfer.sh

Upload a file and get a shareable link

Uploading is a single curl command. Point --upload-file at your local file and give the destination URL with the file name at the end. The README example uses hello.txt.

To remove a file later, the response includes an X-Url-Delete header. Save that URL when you upload.

  • Use -v to see the full response, including headers.
  • Use -sD - with grep to print only the delete URL and the share link.
curl -v --upload-file ./hello.txt https://transfer.sh/hello.txt

Set download and expiry limits

You can add request headers to limit how long a file lives. Max-Downloads sets how many times the file can be downloaded. Max-Days sets the number of days before deletion.

Both headers are passed with curl's -H flag. These are useful for operators who want uploaded files to clean up on their own.

  • Max-Downloads: limits the number of downloads.
  • Max-Days: sets the number of days before deletion.
curl --upload-file ./hello.txt https://transfer.sh/hello.txt -H "Max-Downloads: 1" curl --upload-file ./hello.txt https://transfer.sh/hello.txt -H "Max-Days: 1"

Encrypt files before or during upload

You can encrypt on your own machine with gpg before uploading, so the server only sees encrypted data. The README shows a symmetric encryption pipeline into curl, and a matching command to download and decrypt.

The README also offers server-side encryption with the X-Encrypt-Password and X-Decrypt-Password headers using AES256. It warns to use this only on your own self-hosted server, because trusting a third-party service with server-side encryption is at your own risk.

  • Client-side: encrypt with gpg, then upload the output.
  • Server-side: use X-Encrypt-Password on your own instance only.
gpg --armor --symmetric --output - /tmp/hello.txt | curl --upload-file - https://transfer.sh/test.txt curl https://transfer.sh/1lDau/test.txt | gpg --decrypt --output /tmp/hello.txt

Download, delete and use link aliases

To download a file, request its URL with curl. To delete it, send a DELETE request to the URL from the X-Url-Delete response header. The README also lists two link aliases: /get/ creates a direct download link, and /inline/ creates an inline link.

Configuration options such as listener ports, TLS, HTTP basic auth, IP whitelists and blacklists, provider and bucket settings are set by flag or environment variable. Check the README's option table for the full list.

  • Direct download: replace the path prefix with /get/.
  • Inline: replace the path prefix with /inline/.
  • Delete: curl -X DELETE with the X-Url-Delete URL.
curl -X DELETE <X-Url-Delete Response Header URL>

What people use it for

  • Send a log file or build artifact from a server to a colleague with one curl command.
  • Share a file from a terminal session where no browser is available.
  • Host a private file-sharing service for a team on its own servers.
  • Limit a shared file to one download using Max-Downloads.
  • Encrypt a file with gpg before uploading it to your own instance.

Frequently asked questions

Is transfer.sh free to use?

The repository is licensed under MIT. The README does not describe a hosted public service, and it asks users to host their own installation. Any costs depend on the server and storage provider you choose.

Do I need to install anything to use transfer.sh?

To run your own instance, the README lists Go and, optionally, Docker, and says to clone the repository. To upload a file to an existing instance, the README examples only require curl.

Can I use transfer.sh without setting up a server?

The README says the repository is meant for creating your own instance and does not advertise any third-party public installation. If you want a ready-made service with no setup, this project is not designed for that.

How do I delete a file I uploaded?

Save the X-Url-Delete response header when you upload. Send a DELETE request to that URL with curl -X DELETE.

What are the alternatives to transfer.sh?

The source mentions Magic Wormhole, PrivateBin, Nextcloud and Firefox Send, which is archived. Those tools cover different needs, such as direct transfers, paste sharing or a full cloud suite.

Is it safe to run transfer.sh?

The README carries a security warning about IP filter and HTTP auth bypass through X-Forwarded-For spoofing. Review that issue before deploying, and only run it if you can secure your server.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

transfer.sh suits developers and teams who want a self-hosted, command-line file sharing server and are comfortable with setup and security hardening. It is not a good choice for anyone who wants an instant public service, or who cannot secure a server given the open security warning in the README.

Install options & downloads