README

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.

Dependencies
------------

OpenSSL is used for HMAC-SHA1 signing and nonce generation.

Thanks
------

To Alex Payne for suggesting the name.

Legal
-----

Copyright © 2010 Decklin Foster <decklin@red-bean.com>. This program is
distributed under the MIT license; see LICENSE for details.