Skip to content

Instantly share code, notes, and snippets.

Forked from btoone/
Last active January 21, 2024 21:51
Show Gist options
  • Save joyrexus/85bf6b02979d8a7b0308 to your computer and use it in GitHub Desktop.
Save joyrexus/85bf6b02979d8a7b0308 to your computer and use it in GitHub Desktop.
curl tutorial

An introduction to curl using GitHub's API.


Makes a basic GET request to the specifed URI


Includes HTTP-Header information in the output

curl --include

Pass user credential to basic auth to access protected resources like a users starred gists, or private info associated with their profile

curl --user "caspyin:PASSWD"
curl --user "caspyin:PASSWD"

Passing just the username without the colon (:) will cause you to be prompted for your account password. This avoids having your password in your command line history

curl --user "caspyin"


Use the --request (-X) flag along with --data (-d) to POST data

curl --user "caspyin" --request POST --data '{"description":"Created via API","public":"true","files":{"file1.txt":{"content":"Demo"}}'

curl --user "caspyin" -X POST --data '{"description":"Created via API","public":"true","files":{"file1.txt":{"content":"Demo"}}'

Of course --data implies POST so you don't have to also specify the --request flag

curl --user "caspyin" --data '{"description":"Created via API","public":"true","files":{"file1.txt":{"content":"Demo"}}'

Here is an example that uses the old GitHub API (v2). You can use multiple --data flags

curl --data "login=caspyin" --data "token=TOKEN"

The post data gets combined into one so you can also just combine them yourself into a single --data flag

curl --data "login=caspyin&token=TOKEN"

You can tell curl to read from a file (@) to POST data

curl --user "caspyin" --data @data.txt 

Or it can read from STDIN (@-)

curl --user "caspyin" --data @-
  "files": {
    "file1.txt": {
end with ctrl+d

More POST examples here, including examples of file uploading. For guidance on when to POST with --data vs --form, see this gist.


Often when POSTing data you'll need to add headers for things like auth tokens or setting the content type. You can set a header using -H.

curl -H "Content-Type: application/json" -H "authToken: 349ab29a-xtab-423b-a5hc-5623bc39b8c8" --data '{}'

Dealing with HTTPS

If an API doens't have an SSL cert but is using HTTPS you can tell curl to ignore the security by using --insecure. Be warned this is a very "insecure" thing to do and is only listed here for "educational purposes".

curl --insecure

For my own reference mostly, here is where I first learned about using --insecure rvm/rvm#1684


The first thing to know is that your API Token (found in is not the same token used by OAuth. They are different tokens and you will need to generate an OAuth token to be authorized.

Follow the API's instructions at under the sections "Non-Web Application Flow" and "Create a new authorization" to become authorized.

Note: Use Basic Auth once to create an OAuth2 token

curl \
--user "caspyin" \
--data '{"scopes":["gist"],"note":"Demo"}'

This will prompt you for your GitHub password and return your OAuth token in the response. It will also create a new Authorized application in your account settings

Now that you have the OAuth token there are two ways to use the token to make requests that require authentication (replace "OAUTH-TOKEN" with your actual token)

curl -H "Authorization: token OAUTH-TOKEN"

List the authorizations you already have

curl --user "caspyin"


  • curl tutorial - the official tutorial
  • httpbin - web service to throw http requests at (e.g., with curl) for testing
  • httpie - a python-based utility that's intended to be a more user-friendly replacement for curl
  • postman - web app for building and testing http requests
Copy link

This is very nice. I've been doing a lot of API scripting lately. I'll link to this in my project, as I have instructed my team to start here. Thank you for /(sh|c)aring/.

Copy link

please suggest how i can use this curl on my github

Copy link

The new links to the github docs for oauth are

  1. Authorizing-oauth-apps
  2. Basics-of-authentication

Copy link

Couldn't curl the site admin :'(

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment