gocurl

The source code for this utility is here https://github.com/glynnbird/gocurl

If you use CouchDB/Cloudant, then you can access everything using curl. The trouble is that it if you are using an authenticated, hosted service such as Cloudant’s, then your credentials appear on your command-line history and there is a lot of typing. e.g.

  curl 'https://mypassword:MyPAssw0rd@myhost.cloudant.com/database/12345678'

With gocurl, this becomes:

  gocurl /database/12345678

Or adding a document with curl:

  curl -X POST \
       -H 'Content-type:application/json' \
       -d'{"a":1,"b":2}' \
       'https://mypassword:MyPAssw0rd@myhost.cloudant.com/database'

With gocurl, this becomes:

  gocurl -X POST -d'{"a":1,"b":2}' /database

Installation

You will need to download and install the Go compiler. Clone this repo then:

go build ./cmd/gocurl

The copy the resultant binary gocurl (or gocurl.exe in Windows systems) into your path.

Storing your credentials

Basic Authentication (Legacy)

Your CouchDB credentials are taken from an environment variable “COUCH_URL”. This can be set in your console with

  export COUCH_URL="https://mypassword:MyPAssw0rd@myhost.cloudant.com"

or this line can be added to your ~/.bashrc/~/.bash_profile/~/.zshrc file.

If you don’t want credentials stored in your command-line history, you can set an environment variable by extracting the credentials from a file e.g.

export COUCH_URL=`cat ~/.ibm/cloudant.json | jq -r .url`

where ~/.ibm/cloudant.json is a JSON file that is readable only by my user containing the Cloudant service credentials. Even better store your your credentials in a password manager and extract them using CLI tools when needed:

# extract credentials from 1Password password manager
export COUCH_URL=`op read op://Private/CloudantBasic/website`

IAM Authentication (IBM Cloud)

For IBM Cloud Cloudant instances using IAM authentication, you can use an API key instead of basic authentication. Set two environment variables:

export IAM_API_KEY="your-iam-api-key-here"
export COUCH_URL="https://your-instance.cloudantnosqldb.appdomain.cloud"

Note: When using IAM authentication, the COUCH_URL should NOT contain username/password credentials.

The IAM API key will be exchanged for a bearer token automatically. The bearer token is cached in ~/.gocurl.json with restricted permissions (readable only by you) and will be reused for subsequent requests until it expires. This reduces the number of token requests and improves performance.

Token Caching

  • Tokens are cached in ~/.gocurl.json in your home directory
  • The cache file is created with 0600 permissions (owner read/write only)
  • Tokens are automatically refreshed when they expire (with a 5-minute buffer)
  • Each API key has its own cached token
  • If you change API keys, a new token will be fetched and cached

Security Notes

  • Keep your IAM API key secure - treat it like a password
  • The cache file contains valid bearer tokens, so protect it appropriately
  • Tokens typically expire after 1 hour
  • You can delete ~/.gocurl.json at any time to clear the cache

Using gocurl

  • All command-line switches are passed through to curl.
  • Instead of passing through a full url, pass through a relative url.
  • If the url is omitted, then a relative url of “/” is assumed.
  • The content-type of application-json is added for you if you don’t already provide a content type.

Examples

Add a database

  > gocurl -X PUT /newdatabase
  {"ok":true}

Add a document

  > gocurl -X POST -d'{"a":1,"b":2}' /newdatabase
  {"ok":true,"id":"005fa466b4f690ccad7b4d194f071bbe","rev":"1-25f9b97d75a648d1fcd23f0a73d2776e"}

Get a document

  > gocurl /newdatabase/005fa466b4f690ccad7b4d194f071bbe
  {"_id":"005fa466b4f690ccad7b4d194f071bbe","_rev":"1-25f9b97d75a648d1fcd23f0a73d2776e","a":1,"b":2}

Get ten documents

  > gocurl '/newdatabase/_all_docs?limit=10&include_docs=true'
  {"total_rows":1,"offset":0,"rows":[{"id":"005fa466b4f690ccad7b4d194f071bbe","key":"005fa466b4f690ccad7b4d194f071bbe","value":{"rev":"1-25f9b97d75a648d1fcd23f0a73d2776e"},"doc":{"_id":"005fa466b4f690ccad7b4d194f071bbe","_rev":"1-25f9b97d75a648d1fcd23f0a73d2776e","a":1,"b":2}}]}

Remove a database

  > gocurl -X DELETE /newdatabase
  {"ok":true}

Other curl command-line parameters work too

  gocurl -h
  gocurl -v
  etc.

Using gocurl with jq

If jq is installed, gocurl automatically pipes the curl output to jq ., when stdout is a terminal. You may also do the piping yourself to extract a subset of the data e.g

 gocurl '/newdatabase/_all_docs?limit=10&include_docs=true' | jq '.total_rows'

or

 gocurl '/newdatabase/_all_docs?limit=10&include_docs=true' | jq '.rows[0].doc.name | length'