cURL is a staple of any developer's command-line toolkit, offering a quick and easy way to fire off API requests to any URL, or to easily download a file from a location. In this guide, we'll go over what cURL is, how to use it, and even how you can use it to test your Transloadit Templates.

An illustration depicting the use of cURL for file downloads.

What is cURL?

cURL, short for 'client URL', is a powerful command-line tool and library for transferring data using various protocols. It supports a wide range of protocols including HTTP, HTTPS, FTP, and many more, which makes it a popular choice for downloading files, making API requests, and transferring data. cURL can be used for tasks such as downloading files, testing RESTful APIs, and even debugging network issues.

Services like Postman allow you to use cURL from behind a friendly user interface. For quick testing on the command line, however, cURL can still be an invaluable part of your developer toolkit.

How do I run a cURL command?

If you are new to using cURL, you may also be new to using the CLI, but that's ok! To get started, you'll want to open the terminal (on a Mac or Linux machine) or the command prompt (on Windows), and input the commands listed below as we go. A good way to check if you're in the right place is to type:

echo Hello from Transloadit!

If you see the line "Hello from Transloadit!" repeated back to you, you're in the right place.

How do I download a file with cURL?

Now that we're command line cowboys – let's start downloading a file with cURL. Your initial instinct may be to use a simple command like this:

curl URL

However, if you try this with a website in your terminal, you will notice it only displays the binary or source code of the website you're requesting.

This is because, under the hood, cURL is sending an HTTP GET request from your machine to the target URL, and the server is responding with the raw HTML that you requested. However, we haven't told cURL what we want to do with the HTML, so it's simply displayed in the terminal instead.

To actually save the file to your local machine instead of just displaying its contents. To download the file to your local machine, add the -o flag, to specify an output for the resource you're requesting.

curl -o filename.extension URL

Replace URL with the actual URL of the file you want, and watch with satisfaction as the download starts.

How do I pause and resume a download with cURL?

If that wasn't heavy metal enough for you – how about we try and replicate some of the functionality offered by the Tus protocol, using the -c flag.

Start the download the same way as in the section above. Then, terminate the download by simply pressing ctrl+C in the terminal to close the process. To restart the download, type in the command below and watch as your download magically resumes.

curl -c - -o filename.extension URL

Of course, what we're doing here is simply simulating what could happen accidentally in the middle of your download, such as if your internet suddenly cuts out, but it can be a useful command to keep in the back of your mind just in case.

How do I follow redirects with cURL?

HTTP redirects have been a core of the web since 1996. You may notice, however, that cURL by default will not follow a redirect URL to the final destination. No need to worry though! By adding the -l flag to our command, cURL will keep following each redirect request returned by the server until it reaches a final destination. Here's how that would look:

curl -l URL

How can I test a Transloadit Template with cURL?

Before we can start firing off Templates using cURL, we need to make sure that the prerequisites are installed on our system. These are (naturally) cURL, and the command-line JSON processor jq.

brew install curl jq || sudo apt install curl jq

After both are installed, we can create a simple command that sends a multipart form request to the Transloadit API, to run an Assembly using the specified Template.

echo '{
  "template_id": "YOUR_TEMPLATE_ID",
  "auth": {
    "key": "YOUR_TRANSLOADIT_KEY"
  },
  "steps": {}
}' |curl

    --request POST

    --form 'params=<-'

    --form myfile1=@./joe-gardner-149699.jpg

  https://api2.transloadit.com/assemblies

|jq

For more information on the details behind our API, we have extensive documentation that we constantly update and improve. If you're stuck, and would prefer to talk to a human instead, please don't hesitate to reach out to our dedicated team of support specialists.

Conclusion

If you've reached this point of the blog, then hopefully you now feel better equipped to use cURL fundamentals in your day-to-day development life. To stay up to date with our guides, and other interesting updates in the tech world, sign up for our monthly newsletter below.