Curlicue

Curlicue is a small wrapper script that invokes curl with the necessary headers for OAuth. It should run on any POSIX-compatible shell. Keys, tokens, and secrets are stored in text files as form-encoded data.

Usage

A Curlicue command looks like the equivalent curl command, with some extra options at the beginning:

curlicue [-f FILE ...] [-p PARAMS] [-P] [-- CURL_OPTS] URL

OAuth credentials are read from FILE(s). If you don't specify any FILEs with -f, Curlicue will try to read credentials from ~/.curlicue/HOST, where HOST is the hostname component of your URL.

Extra OAuth parameters, if any, are specified with -p; these parameters should be URL-encoded and separated with &.

Either -- or a URL (any argument starting with "http") ends processing of Curlicue parameters and passes all further options along to curl. These options will be checked for the -d/--data or -X/--request, since adding application/x-www-form-urlencoded POST parameters or otherwise changing the HTTP method will change the OAuth signature base string. If you are sending POST data with some other content-type, specify -P (before the options that are passed along to curl) to disable treating POST data as parameters.

Installation

Curlicue is now split up into several scripts, so you will need to install at least curlicue and curl-encode to a directory in your PATH. This can be done with:

install curlicue curl-encode /usr/local/bin

You may also want to include curlicue-setup and the scripts in contrib.

Setup

To perform the initial OAuth "dance", run curlicue-setup with four arguments: the request token URL, the user authorization URL, the access token URL, and a file to output credentials to. Typically, this will look something like:

curlicue-setup \
    'https://oauth.provider/request_token' \
    'https://oauth.provider/authorize?oauth_token=$oauth_token' \
    'https://oauth.provider/access_token' \
    credentials

In the user authorization URL (only), variables from the consumer information or request token can be interpolated using shell syntax. Your provider may need additional URL parameters for one or more of the steps; consult their documentation. You will be prompted for the consumer key and secret.

For examples of how this works with several popular OAuth providers, refer to EXAMPLES.

Included Scripts

The contrib directory contains some scripts that demonstrate what you can do with Curlicue:

twij - get JSON data from a Twitter API endpoint, using jq. Supports using cursors to fetch things that don't fit in a single response.
twilim - display the Twitter API rate limit status resource with twij and jq.

Walkthrough

To demonstrate the authentication process in detail, let's walk through what happens when you setup curlicue with a Twitter application. Before creating any files (which will all contain secrets), we should set our umask so that no one else can read them:

umask 077

The first step in OAuth is obtaining a request token. To make that request, we'll need a file containing the consumer key and secret (make sure that their values are URL-encoded):

cat << EOF > consumer
oauth_consumer_key=KEY&oauth_consumer_secret=SECRET
EOF

With that, let's get the token. We're not a web app, so we use the "out of band" callback method:

curlicue -f consumer -p 'oauth_callback=oob' -- \
    -X POST https://api.twitter.com/oauth/request_token > request_token

The arguments passed along to curl are parsed to get the HTTP method and URL so that the request can be signed.

Now we need to approve the app. We can build URLs with the -e option, which just echoes a string back to us (with parameters from the files read with -f filled in) instead of running curl.

curlicue -f request_token -e \
    'https://api.twitter.com/oauth/authorize?oauth_token=$oauth_token'

Visiting this URL in our browser and selecting "Allow" will give us a PIN, which we can in turn use to obtain an access token:

curlicue -f consumer -f request_token -p 'oauth_verifier=PIN' -- \
    -X POST https://api.twitter.com/oauth/access_token > access_token

Note that we need to read in both the consumer and token information from here on. Now we can actually make an interesting request:

curlicue -f consumer -f access_token \
    https://api.twitter.com/1.1/statuses/home_timeline.json

In this case, we are not passing any options along to curl, so the -- can be omitted.

Finally, to make our command line shorter, we can concatenate the consumer and token into one file:

paste -d '&' consumer access_token > credentials

And remove all the intermediate files (consumer, request_token, and access_token).

Limitations

--data-urlencode, --data-binary, and reading POST data from a file are not yet supported.

decklin / curlicue

readme