From 1261c2a9ec7f0471bcd50d297c3c4ee5f40555e4 Mon Sep 17 00:00:00 2001
From: Tom Clegg <tom@clinicalfuture.com>
Date: Fri, 14 Jun 2013 16:37:13 -0400
Subject: [PATCH] update cli sdk doc, tweak json output options

---
 doc/user/sdk-cli.md      | 24 --------------
 doc/user/sdk-cli.textile | 69 ++++++++++++++++++++++++++++++++++++++++
 sdk/cli/arv              | 19 +++++++----
 3 files changed, 81 insertions(+), 31 deletions(-)
 delete mode 100644 doc/user/sdk-cli.md
 create mode 100644 doc/user/sdk-cli.textile

diff --git a/doc/user/sdk-cli.md b/doc/user/sdk-cli.md
deleted file mode 100644
index 0cf2766e98..0000000000
--- a/doc/user/sdk-cli.md
+++ /dev/null
@@ -1,24 +0,0 @@
----
-layout: default
-navsection: userguide
-title: Command line SDK
-navorder: 10
----
-
-{% include alert-stub.html %}
-
-# Command line SDK
-
-If you are logged in to an Arvados VM, the command line SDK is
-probably already installed. Try:
-
-    arv --help
-
-To install:
-
-    echo "deb http://apt.arvados.org/apt precise main contrib non-free" \
-      | sudo tee -a /etc/apt/sources.list.d/arvados.list
-    wget -q http://apt.arvados.org/53212765.key -O- \
-      | sudo apt-key add -
-    sudo apt-get update
-    sudo apt-get install arvados-cli
diff --git a/doc/user/sdk-cli.textile b/doc/user/sdk-cli.textile
new file mode 100644
index 0000000000..ffc8bc24cc
--- /dev/null
+++ b/doc/user/sdk-cli.textile
@@ -0,0 +1,69 @@
+---
+layout: default
+navsection: userguide
+title: Command line SDK
+navorder: 10
+---
+
+{% include alert-stub.html %}
+
+h1. Command line SDK
+
+If you are logged in to an Arvados VM, the command line SDK should be
+installed. Try:
+
+  arv --help
+
+h3. First...
+
+Set the @ARVADOS_API_HOST@ environment variable.
+
+<pre>
+export ARVADOS_API_HOST=xyzzy.arvadosapi.com
+</pre>
+
+Log in to Workbench and get an API token for your account. Set the @ARVADOS_API_TOKEN@ environment variable.
+
+<code>
+export ARVADOS_API_TOKEN=c0vdbi8wp7f703lbthyadlvmaivgldxssy3l32isslmax93k9
+</code>
+
+h3. Usage
+
+@arv [global_options] resource_type resource_method [method_parameters]@
+
+h3. Basic examples
+
+Get UUID of the current user
+@arv user current@
+
+Get entire record (json) for current user
+@arv -h user current@
+
+Get entire record for identified user
+@arv -h user get --uuid 6dnxa-tpzed-iimd25zhzh84gbk@
+
+Update user record
+@arv user update --uuid 6dnxa-tpzed-iimd25zhzh84gbk --first_name "Bob"@
+
+Get list of groups (showing just UUIDs)
+@arv group list@
+
+Get list of groups (showing entire records)
+@arv -h group list@
+
+h3. Global options
+
+- @--json@, @-j@ := Output entire response as compact JSON.
+
+- @--pretty@, @--human@, @-h@ := Output entire response as JSON with whitespace for better human-readability.
+
+- @--uuid@ := Output only the UUIDs of object(s) in the API response, one per line.
+
+h3. Resource types and methods
+
+Get list of resource types
+@arv --help@
+
+Get list of resource methods for the "user" resource type
+@arv user --help@
diff --git a/sdk/cli/arv b/sdk/cli/arv
index f15a1078d7..08ff8d0244 100755
--- a/sdk/cli/arv
+++ b/sdk/cli/arv
@@ -25,6 +25,7 @@ begin
   require 'pp'
   require 'trollop'
   require 'andand'
+  require 'oj'
 rescue LoadError
   abort <<-EOS
 
@@ -34,6 +35,7 @@ Please install all required gems:
   json
   trollop
   andand
+  oj
 
   EOS
 end
@@ -49,7 +51,9 @@ module Kernel
 end
 
 # do this if you're testing with a dev server and you don't care about SSL certificate checks:
-suppress_warnings { OpenSSL::SSL::VERIFY_PEER = OpenSSL::SSL::VERIFY_NONE }
+if ENV['ARVADOS_API_HOST_INSECURE']
+  suppress_warnings { OpenSSL::SSL::VERIFY_PEER = OpenSSL::SSL::VERIFY_NONE }
+end
 
 class Google::APIClient
  def discovery_document(api, version)
@@ -84,8 +88,9 @@ def parse_arguments(discovery_document)
     opt :dry_run, "Don't actually do anything", :short => "-n"
     opt :verbose, "Print some things on stderr", :short => "-v"
     opt :uuid, "Return the UUIDs of the objects in the response, one per line (default)", :short => nil
-    opt :json, "Return the raw json received from the API server", :short => "-j"
-    opt :jsonhuman, "Return the raw json received from the API server, formatted for human consumption", :short => "-h"
+    opt :json, "Return the entire response received from the API server, as a JSON object", :short => "-j"
+    opt :human, "Return the response received from the API server, as a JSON object with whitespace added for human consumption", :short => "-h"
+    opt :pretty, "Synonym of --human", :short => nil
     stop_on resource_types
   end
   
@@ -180,10 +185,10 @@ if results["errors"] then
   abort "Error: #{results["errors"][0]}"
 end
 
-if global_opts[:json] then
-  puts results.to_s
-elsif global_opts[:jsonhuman] then
-  puts results.pretty_inspect()
+if global_opts[:human] or global_opts[:pretty] then
+  puts Oj.dump(results, :indent => 1)
+elsif global_opts[:json] then
+  puts Oj.dump(results)
 elsif results["items"] and results["kind"].match /list$/i
   results['items'].each do |i| puts i['uuid'] end
 else
-- 
2.30.2