commandcar - curl on steroids

commandcar is a CLI tool that can easily communicate with any API. It simplifies unreadable and complicated curl commands, and has some nice features to make automation of API calls much simpler and bash scripts more streamlined.

Here's an example of what it can look like

commandcar facebook.like --post_id 123456789 --access_token abcdefghijklmnopqrstuvwxyz 

Installing

use npm to install commandcar.

sudo npm install commandcar -g

Using commandcar

A fresh commandcar install is a powerful yet empty skeleton. In order to make commandcar usable you need to install API definitions, and that's how you extend its power.

API Definitions are swagger2.0 files. You can create them yourself -- for example if you're developing an API and want to use commandcar to run automated tests against it -- or you can use existing public files. commandcar accepts either json or yaml swagger files.

Installing an API

There are three methods to install an API definition:

Installing a local file

commandcar install --name my_api --file ~/dev/commandcar/apis/my_api.json

Installing from a URL

commandcar install --name my_api --url http://some.domain.com/my/api/swagger.yaml

Installing from api-models

api-models is a GitHub repository of public available swagger files for many public APIs.

commandcar install --name instagram --api_model instagram.com/1.0.0

You can browse through the available APIs here and use the relative path to the directory containing the swagger file from this path onward. For example, the instagram API v1 resides here: https://github.com/APIs-guru/api-models/tree/master/APIs/instagram.com/1.0.0. Use "instagram.com/1.0.0" as the value for the --api_model argument. No trailing slashes please.

Upgrading/modifying an installed API

Simply run install again, it will overwrite the existing installation.

Uninstall

commandcar uninstall --name instagram

Invoking APIs using commandcar

Once you've installed API definitions, you can use commandcar -h to see the new commands and options you can use. Here's an example of the command output after installing the instagram API:

  Commands:

    instagram.get_geographies_media_recent [options] 
    instagram.get_locations_search [options]         
    instagram.get_locations [options]                
    instagram.get_locations_media_recent [options]   
    instagram.get_media_popular [options]            
    instagram.get_media_search [options]             
    instagram.get_media_shortcode [options]          
    instagram.get_media [options]                    
    instagram.get_media_comments [options]           
    instagram.post_media_comments [options]          
    instagram.delete_media_comments [options]        
    instagram.delete_media_likes [options]           
    instagram.get_media_likes [options]              
    instagram.post_media_likes [options]             
    instagram.get_tags_search [options]              
    instagram.get_tags [options]                     
    instagram.get_tags_media_recent [options]        
    instagram.get_users_search [options]             
    instagram.get_users_self_feed [options]          
    instagram.get_users_self_media_liked [options]   
    instagram.get_users_self_requested_by [options]  
    instagram.get_users [options]                    
    instagram.get_users_followed_by [options]        
    instagram.get_users_follows [options]            
    instagram.get_users_media_recent [options]       
    instagram.get_users_relationship [options]       
    instagram.post_users_relationship [options]      
    instagram.use [options]                          
    instagram.unuse                                  
    install [options]                                   
    uninstall [options]                                   

  Options:

    -h, --help  output usage information

You can then run help for any given command and see what your options are. For example, commandcar instagram.get_media_search -h will result in:

  Usage: instagram.get_media_search [options]

  Options:

    -h, --help                           output usage information
    -a, --access_token <access_token>    access_token
    -r, --ret [return value]             specify return value
    -l, --lat <lat>                      Latitude of the center search coordinate. If used, `lng` is required.
    -L, --lng <lng>                      Longitude of the center search coordinate. If used, `lat` is required.
    -m, --min_timestamp [min_timestamp]  A unix timestamp. All media returned will be taken later than this timestamp.
    -M, --max_timestamp [max_timestamp]  A unix timestamp. All media returned will be taken earlier than this timestamp.
    -d, --distance [distance]            Default is 1km (distance=1000), max distance is 5km.

use command

use is a special command that is added to any API that has securityDefinitions. If you're doing a lot of API calls with identical authorization parameters, for instance an Oauth2 access_token, then you can use them instead, and then they will be included in any following call to the API, until you unuse it or until you use another parameter value.

for example:

commandcar facebook.use --access_token abcdefghijklmnopqrstuvwxyz
commandcar facebook.like --post_id 1234567
commandcar facebook.comment --post_id 1234567 --text "what a cool post"
commandcar facebook.add_friend --uid 987654321

Note: Facebook is used as an example API throughout this doc, though we didn't practically implement it as a swagger file.

-r --ret

This is an option that is attached automatically to any command and enables you to specify exactly what you wish to receive as output.

So for example let's assume you make this call:

commandcar facebook.get_user --accees_token 123456 --ret first_name

Now let's assume that the API response is:

{
   "uid": "123456789",
   "first_name": "John",
   "last_name": "Doe"
}

Then the output would be simply John instead of the entire json.

Known issues

• --ret can only work on json responses
• command line functionality itself, i.e. required arguments are not enforced etc.
• program can be heavy with lots of APIs installed. Needs to imporve caching for consecutive invokations

Gitter

We're on gitter if you want to talk with us.