MuranoCLI 3.0.1 → 3.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 9e6cce4e91f5060a854bb7994fe2f5692aa6e9a0
-  data.tar.gz: 24c9ea0a2c2f8f2889740e60aa79fedfe4f4e7eb
+  metadata.gz: 0ea22792f25e5418a7687bbffaad2bf0b14f2c28
+  data.tar.gz: cbb94dd03d104a310c3f34c85381f1ce2dd455ff
 SHA512:
-  metadata.gz: 5ef371516ac2ae1a8b308a08b81b0d64f3458d4bb7f2b74ef36b3c4628eba2ba04aa9a3273cbf7ed43e30a77e384c24bb3c1451724576f30c1f6408095c1fb61
-  data.tar.gz: 97c8dfafc76608f74ea8e87ff35f4a5208e74d27766316119c78bb0e4ad5cda0bead9fb23a0155d6b1a725760188aa74d0b258a39da817de5c7a51c694f12baf
+  metadata.gz: 728ee381c09f8e361d368a2971f8a031e17900186f114ddda941085eafa5ed7f921be17d57347a1051eab0348c0a9e8965858bcf1e8aefee2d8796c6b988f103
+  data.tar.gz: c81a425d2122475db3ecccee78389df533ed4f0dd050d086cea6418e65361c2b804f363d3143e6f074176916cbd78b66bcbc99c1fe6a85e7a6f494d47aef5d99

data/.agignore

@@ -10,6 +10,7 @@ Gemfile.lock
 
 # 2017-05-12: Testing!
 *.out
+.rake_build.out
 
 rspec-*.html
 *.rspec.html

data/.rubocop.yml

@@ -1,4 +1,4 @@
-# Last Modified: 2017.08.22 /coding: utf-8
+# Last Modified: 2017.08.31 /coding: utf-8
 # Copyright © 2016-2017 Exosite LLC.
 # License: MIT. See LICENSE.txt.
 #  vim:tw=0:ts=2:sw=2:et:ai
@@ -28,6 +28,8 @@ Layout/TrailingBlankLines:
 Lint/ScriptPermission:
   Exclude:
     - 'bin/murano'
+    # Also the rspec shim-link:
+    - 'lib/MrMurano/spec_commander.rb'
 
 # "Assignment Branch Condition size for XXX is too high."
 # http://wiki.c2.com/?AbcMetric
@@ -122,6 +124,8 @@ Style/FileName:
     - 'lib/MrMurano/Config-Migrate.rb'
     - 'lib/MrMurano/Config.rb'
     - 'lib/MrMurano/Content.rb'
+    - 'lib/MrMurano/Exchange.rb'
+    - 'lib/MrMurano/Exchange-Element.rb'
     - 'lib/MrMurano/Gateway.rb'
     - 'lib/MrMurano/Keystore.rb'
     - 'lib/MrMurano/Mock.rb'
@@ -232,14 +236,72 @@ AllCops:
     # HINT: You can use regexp in this list.
     #- !ruby/regexp /old_and_unused\.rb$/
     #
-    # 2017-07-25: It's probably not worth our time to lint the spec tests.
-    # 2017-07-31: 7735 offenses in the Spec tests -- not worth it to fix!!
-    - 'spec/**/*'
-    #
     # Not sure if the templates are included by default or not, but ignore.
     - 'lib/MrMurano/commands/completion-bash.erb'
     - 'lib/MrMurano/commands/completion-zsh.erb'
     #
     # 2017-08-16: Ug.
     - 'lib/MrMurano/optparse.rb'
+    #
+    # 2017-08-29: A hack for rspec.
+    #- 'lib/Murano/spec_commander.rb'
+    #
+    # 2017-08-30: Ug. Loading orderedhash spits out warning gobbled by rspec fails test.
+    - 'lib/MrMurano/orderedhash.rb'
+    #
+    # The spec_helper is a generated file; don't care.
+    - 'spec/spec_helper.rb'
+    #
+    # 2017-07-25: It's probably not worth our time to lint the spec tests.
+    # 2017-07-31: 7735 offenses in the Spec tests -- not worth it to fix!!
+    #- 'spec/**/*'
+    - 'spec/Account-Passwords_spec.rb'
+    - 'spec/Account_spec.rb'
+    - 'spec/Business_spec.rb'
+    - 'spec/ConfigFile_spec.rb'
+    - 'spec/ConfigMigrate_spec.rb'
+    - 'spec/Config_spec.rb'
+    - 'spec/Content_spec.rb'
+    - 'spec/GatewayBase_spec.rb'
+    - 'spec/GatewayDevice_spec.rb'
+    - 'spec/GatewayResource_spec.rb'
+    - 'spec/GatewaySettings_spec.rb'
+    - 'spec/Http_spec.rb'
+    - 'spec/MakePretties_spec.rb'
+    - 'spec/Mock_spec.rb'
+    - 'spec/ProjectFile_spec.rb'
+    - 'spec/Setting_spec.rb'
+    - 'spec/Solution-ServiceConfig_spec.rb'
+    - 'spec/Solution-ServiceEventHandler_spec.rb'
+    - 'spec/Solution-ServiceModules_spec.rb'
+    - 'spec/Solution-UsersRoles_spec.rb'
+    - 'spec/Solution_spec.rb'
+    - 'spec/SyncRoot_spec.rb'
+    - 'spec/SyncUpDown_spec.rb'
+    - 'spec/Verbosing_spec.rb'
+    - 'spec/Webservice-Cors_spec.rb'
+    - 'spec/Webservice-Endpoint_spec.rb'
+    - 'spec/Webservice-File_spec.rb'
+    - 'spec/Webservice-Setting_spec.rb'
+    #- 'spec/_workspace.rb'
+    - 'spec/cmd_business_spec.rb'
+    #- 'spec/cmd_common.rb'
+    - 'spec/cmd_config_spec.rb'
+    - 'spec/cmd_content_spec.rb'
+    - 'spec/cmd_cors_spec.rb'
+    - 'spec/cmd_device_spec.rb'
+    - 'spec/cmd_domain_spec.rb'
+    #- 'spec/cmd_exchange_spec.rb'
+    #- 'spec/cmd_help_spec.rb'
+    - 'spec/cmd_init_spec.rb'
+    - 'spec/cmd_keystore_spec.rb'
+    - 'spec/cmd_link_spec.rb'
+    - 'spec/cmd_password_spec.rb'
+    - 'spec/cmd_setting_application_spec.rb'
+    - 'spec/cmd_setting_product_spec.rb'
+    - 'spec/cmd_status_spec.rb'
+    - 'spec/cmd_syncdown_spec.rb'
+    - 'spec/cmd_syncup_spec.rb'
+    - 'spec/cmd_usage_spec.rb'
+    #- 'spec/cmd_version_spec.rb'
 

data/Gemfile

@@ -1,4 +1,4 @@
-# Last Modified: 2017.08.17 /coding: utf-8
+# Last Modified: 2017.08.30 /coding: utf-8
 # frozen_string_literal: true
 
 # Copyright © 2016-2017 Exosite LLC.
@@ -21,10 +21,13 @@ gem 'json', '~> 2.1.0'
 gem 'json-schema', '~> 2.7.0'
 gem 'mime-types', '~> 3.1'
 gem 'mime-types-data', '~> 3.2016.0521'
-gem 'orderedhash', '~> 0.0.6'
+#gem 'orderedhash', '~> 0.0.6'
 gem 'paint', '~> 2.0.0'
+# 2017-08-04: public_suffix 3.0.0 is for Ruby >= 2.1.
+#   It's included by json, so make sure it's the old one.
+gem 'public_suffix', '~> 2.0.5'
 gem 'rainbow', '~> 2.2.2'
-gem 'terminal-table', '~> 1.7.3'
+gem 'terminal-table', '~> 1.8.0'
 gem 'vine', '~> 0.4'
 gem 'whirly', '~> 0.2.4'
 

data/MuranoCLI.gemspec

@@ -1,4 +1,4 @@
-# Last Modified: 2017.08.16 /coding: utf-8
+# Last Modified: 2017.08.30 /coding: utf-8
 # frozen_string_literal: true
 
 # Copyright © 2016-2017 Exosite LLC.
@@ -16,16 +16,17 @@ Gem::Specification.new do |s|
   s.license     = 'MIT'
   s.homepage    = 'https://github.com/exosite/MuranoCLI'
   s.summary     = 'Do more from the command line with Murano'
-  s.description = %(Do more from the command line with Murano
+  s.description = %(
+Do more from the command line with Murano.
 
-  Push and pull data from Murano.
-  Get status on what things have changed.
-  See a diff of the changes before you push.
+Push and pull data from Murano.
+Get status on what things have changed.
+See a diff of the changes before you push.
 
-  and so much more.
+And so much more.
 
-  This gem was formerly known as MrMurano.
-)
+(This gem was formerly known as MrMurano.)
+  ).strip
   s.required_ruby_version = '~> 2.0'
 
   # FIXME: 2017-05-25: Remove this message eventually.
@@ -61,10 +62,13 @@ explicitly specifying the version. For instance,
   s.add_runtime_dependency('json-schema', '~> 2.7.0')
   s.add_runtime_dependency('mime-types', '~> 3.1')
   s.add_runtime_dependency('mime-types-data', '~> 3.2016.0521')
-  s.add_runtime_dependency('orderedhash', '~> 0.0.6')
+  #s.add_runtime_dependency('orderedhash', '~> 0.0.6')
   s.add_runtime_dependency('paint', '~> 2.0.0')
+  # 2017-08-04: public_suffix 3.0.0 is for Ruby >= 2.1.
+  #   It's included by json, so make sure it's the old one.
+  s.add_runtime_dependency('public_suffix', '~> 2.0.5')
   s.add_runtime_dependency('rainbow', '~> 2.2.2')
-  s.add_runtime_dependency('terminal-table', '~> 1.7.3')
+  s.add_runtime_dependency('terminal-table', '~> 1.8.0')
   s.add_runtime_dependency('vine', '~> 0.4')
   s.add_runtime_dependency('whirly', '~> 0.2.4')
 

data/README.markdown

@@ -7,163 +7,308 @@ Version](https://badge.fury.io/rb/MuranoCLI.svg)](https://badge.fury.io/rb/Muran
 
 Do more from the command line with [Murano](https://exosite.com/platform/).
 
-MuranoCLI is the command-line tool that interacts with Murano and makes different
-tasks easier. MuranoCLI makes it easy to deploy code to a solution, import many
-product definitions at once, set up endpoints and APIs, and more.
-
-MuranoCLI works around the idea of syncing, much like rsync.  Files from your project
-directory are synced up (or down) from Murano.
-
+MuranoCLI interacts with Murano and makes different tasks easier.
+
+MuranoCLI makes it easy to deploy code to a project, import
+product definitions, set up endpoints and APIs, and more.
+
+MuranoCLI works around the idea of syncing, much like [`rsync`](https://rsync.samba.org/).
+Your project files are synced up (or down) from Murano.
+
+## Contents
+
+* [Contents](#contents)
+* [Usage](#usage)
+   * [Start a new project easily with init](#start-a-new-project-easily-with-init)
+   * [Start a new project manually, step-by-step](#start-a-new-project-manually-step-by-step)
+* [Install](#install)
+   * [Gem Install (Linux and macOS)](#gem-install-linux-and-macos)
+      * [Working With Different Versions of MuranoCLI](#working-with-different-versions-of-muranocli)
+   * [Windows Install](#windows-install)
+* [Features](#features)
+   * [Logs](#logs)
+   * [CORS](#cors)
+   * [Writing Routes (a.k.a. Endpoints)](#writing-routes-aka-endpoints)
+   * [Writing Service Event Handlers](#writing-service-event-handlers)
+   * [MURANO_CONFIGFILE Environment Variable and Dotenv](#murano_configfile-environment-variable-and-dotenv)
+   * [Direct Service Access](#direct-service-access)
+   * [Output Format](#output-format)
+   * [Product Content Area](#product-content-area)
+* [Developing](#developing)
+   * [Testing](#testing)
 
 ## Usage
 
+### Start a new project easily with `init`
+
 ```
 mkdir myproject
 cd myproject
 murano init
 ```
 
-Update `myproject.murano` with the info about your project.
+If you want to add information about your project, edit `myproject.murano`.
+You can add a description, the list of authors, a version number, and more.
+
+If you are connecting to an existing project
+created with the [web interface](https://www.exosite.io/business/),
+you may need to run `murano link set` to connect the product and the application.
+But if you create a new product and application using MuranoCLI, they will
+automatically be connected.
+
+If you are connecting to an existing project, you may want to run
+`murano syncdown` to pull down your project files from Murano.
+
+Now do stuff, like add and edit files.
+
+To see what files have changed, run `murano status`.
+
+To see exactly what changed, try `murano diff`.
+
+When you are ready to deploy, run `murano syncup`.
+
+### Start a new project manually, step-by-step
+
+If you would like to setup a project without using `murano init`,
+follow these steps.
+
+- Find your business ID. Run the command
+
+  `murano business list`
+
+  and copy its ID from the list.
+
+  - If this is the first time you've run `murano`, you will
+    need to enter your Murano username and password.
+
+    (To sign up for a free account, visit [exosite.com](https://exosite.com/signup/).)
+
+  - If you need to change change accounts, try
+
+    `murano logout`
+
+    `murano login`.
+
+    - To manually change you username and password, run
+
+      `murano config user.name <USERNAME>`
+
+      `murano password set <USERNAME>`.
+
+- Add the copied Business ID to your project config.
+
+  `murano config business.id <BUSINESS-ID>`
 
-If this is a new project, you will also need to run `murano assign set` to connect
-the product and solution.
+- Create a new Application and save its ID to the project config.
 
-If this is an existing project, you want to run `murano syncdown -V` after
-running `murano init`.
+  `murano application create myawesomeapplication --save`
 
-Now do stuff, see what changed: `murano status` or `murano diff`.
-Then deploy with `murano syncup`
+  - Alternatively, choose an existing Application.
 
-### To start a brand new project the hard way.
-There are a few steps and pieces to getting a solution with a product up and
-running in Murano. Here is the list.
+    `murano config application.id <APPLICATION-ID>`
 
-- Pick a business: `murano business list`
-  If this is the first time you've run `murano` it will ask for your Murano username
-  and password.
-- Set it: `murano config business.id ZZZZZZZZZ`
-- Create a product: `murano product create myawesomeproduct --save`
-- Add resource aliases to specs/resources.yaml
-- Sync the product definition up: `murano syncup -V --specs`
-- Create a solution: `murano solution create myawesomesolution --save`
-- Sync solution code up: `murano syncup -V`
-- Assign the product to the solution: `murano assign set`
+- Create a new Product and save its ID to the project config.
 
-Do stuff, see what changed: `murano status` or `murano diff`.
-Then deploy with `murano syncup`
+  `murano product create myawesomeproduct --save`
+
+  - Alternatively, choose an existing Product.
+
+    `murano config product.id <PRODUCT-ID>`
+
+- Link the Product to the Application.
+
+  `murano link set`
+
+- Build your project.
+
+  - Edit and create event handlers under `services/`.
+
+  - Create API endpoints under `routes/`.
+
+  - Add Lua modules under `modules/`.
+
+  - Add static files under `files/`.
+
+  - Add resource aliases to the file, `specs/resources.yaml`.
+
+- See what changed.
+
+  `murano status`
+
+  or
+
+  `murano diff`
+
+- Deploy your project. Sync up resources, code and files.
+
+  `murano syncup`
 
 ## Install
 
-### Gem Install (Linux and Macos)
+### Gem Install (Linux and macOS)
+
+The easiest way to install MuranoCLI is using the Gem installer.
 
-When upgrading from a 1.\* version to a 2.0, you should uninstall the old versions
-first.
 ```sh
-> gem uninstall MuranoCLI MrMurano
+gem install MuranoCLI
 ```
 
-And then install:
+- If you are upgrading from a `1.*` version, uninstall the old versions first.
 
 ```sh
-> gem install MuranoCLI
+gem uninstall MuranoCLI MrMurano
 ```
-Or
+
+- If you would like to install a specific version, such as the older,
+  pre-Murano CLI tool, you can specify the version to install.
+
+```sh
+gem install MuranoCLI -v 2.2.4
+```
+
+- To update to the latest gem (rather than installing a new gem side by
+  side with an older version of the same gem), update it.
+
 ```sh
-> gem update MuranoCLI
+gem update MuranoCLI
 ```
 
-You will likely need to be root for the above commands.  If you would rather not
-install as root, you can install gems in the user directory.
+You will likely need to be root for the above commands. If you would rather
+not install as root, you can install gems in the user directory.
 
 ```sh
-> gem install MuranoCLI --user-install
+gem install MuranoCLI --user-install
 ```
 
-Your `PATH` may need to be updated to find the installed `murano` command.  See the
-[Ruby Gem FAQ](http://guides.rubygems.org/faqs/#user-install).  In short, you need
-to add the output of `ruby -rubygems -e 'puts Gem.user_dir'` to your `PATH`.
+Your `PATH` may need to be updated to find the installed `murano` command.
+See the [Ruby Gem FAQ](http://guides.rubygems.org/faqs/#user-install).
+
+- In short, you need to add the output of
+  `ruby -rubygems -e 'puts Gem.user_dir'` to your `PATH`.
+
+  E.g., you may want to add this to your `~/.bashrc` file:
+
+  `export PATH=$PATH:$(ruby -rubygems -e 'puts Gem.user_dir')`
+
+#### Working With Different Versions of MuranoCLI
+
+The `murano` command line tool is a Ruby gem and, as such, you can install
+different versions of MuranoCLI and choose which one to execute.
+
+The following example shows how you can reference a specific version of the
+`murano` gem:
+
+```sh
+$ gem list MuranoCLI --local
+
+*** LOCAL GEMS ***
+
+MuranoCLI (3.0.1, 2.2.4)
+
+$ murano --version
+murano 3.0.1
+
+$ murano _2.2.4_ --version
+murano 2.2.4
+```
+
+Note: Not all OSes support multiple versions and will only execute the
+latest Gem installed. In this case, you will need to uninstall newer
+versions of MuranoCLI in order to use older versions.
 
 ### Windows Install
 
-The MuranoCLI gem will install on Windows.  There is also a single Windows binary
-Setup installer available in [releases](https://github.com/exosite/MuranoCLI/releases)
+The MuranoCLI gem will install on Windows.
+
+There is also a single Windows binary Setup installer available in
+[releases](https://github.com/exosite/MuranoCLI/releases).
 
 If you do not already use Ruby on Windows, then you should use the binary
 installer.
 
-When upgrading, it is best to run the uninstaller for the old version before
-installing the new version.
-
+When upgrading, it is best to run the uninstaller for the old version
+before installing the new version.
 
 ## Features
 
-### Project File
-
 ### Logs
 
-You can monitor the log messages from your solution with the `murano logs --follow`.
-Or quickly get the last few with `murano logs`
+You can monitor the log messages from your Application by running
+`murano logs application --follow`.
+
+Or quickly get the last few logs with simply `murano logs application`.
 
-MuranoCLI does a few things to make your log output easier to follow.
-- Adds color to easily see where each log message starts.
-- Reformats the timestamps to be in local time.
-- Finds JSON blobs and pretty prints them.
+MuranoCLI does a few things to make the log output easier to follow.
 
-All of these can be toggled with command line options.
+- It adds color to easily see where each log message starts.
+
+- It reformats the timestamps to be in local time.
+
+- It finds JSON blobs and pretty prints them.
+
+Each of these options can be disabled with command line options.
 
 ### CORS
 
-If you are developing you UI on separate services and you need cross-origin
+If you are developing a UI on separate services and need cross-origin
 resource sharing, you will need to set the
 [CORS](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing) options.
 
-The current CORS options can be fetched with `murano cors`
+The current CORS options can be fetched with `murano cors`.
 
-There are three options for setting, the first and preferred way is to put your CORS
-options into a file named `cors.yaml`.
+There are three different ways to configure CORS.
 
-Second and third are to put the CORS options in your project file.  In the `routes`
-section, add a `cors` sub-section with either the name of the file to read, or the
-CORS options inline.
+The first and preferred way is to add your CORS options to a file named
+`cors.yaml`.
 
-```yaml
-routes:
-  cors: my_cors_file.json
-```
-OR:
-```yaml
-routes:
-  cors: {"origin": true}
-```
+The second and third options are to put the CORS options in your project file.
 
-Then use `murano cors set` to push these options up to your solution.
+- In the `routes` section, add a `cors` sub-section with either the name of
+  the file to read, or the CORS options inline.
 
-### Writing Routes (or endpoints)
+  ```yaml
+  routes:
+    cors: my_cors_file.json
+  ```
 
-All of the routes that you create in your solution are identified by their method
-and path.  You set this with the following line:
+  OR:
+
+  ```yaml
+  routes:
+    cors: {"origin": true}
+  ```
+
+Then use `murano cors set` to push these options up to your application.
+
+### Writing Routes (a.k.a. Endpoints)
+
+All of the routes that you create in your application are identified
+by their method and path. You set this with the following line:
 
 ```lua
 --#ENDPOINT METHOD PATH
 ```
 
-Optionally, you can set what the expected content type is too. (If you don't set
-this, the value is `application/json`)
+Optionally, you can set what the expected content type is, too.
+(If you don't set this, it defaults to `application/json`.)
 
 ```lua
 --#ENDPOINT METHOD PATH CONTENT_TYPE
 ```
 
-An example of a route that puts CSV data:
+Here is an example of a route that puts CSV data:
+
 ```lua
 --#ENDPOINT PUT /api/upload text/csv
 ```
 
-After this header line, the script to handle the route follows.  Since many routes
-end up being a couple of lines or less, you can put multiple routes into a single
-file.
+After the magic header, add the script to handle the route.
+
+Since many routes end up being a couple of lines or less,
+you can put multiple routes into a single file.
+
+A routes file might look like this:
 
-Which looks like this:
 ```lua
 --#ENDPOINT GET /api/somedata
 return Tsdb.query(…)
@@ -177,18 +322,24 @@ return Tsdb.deleteAll()
 
 ### Writing Service Event Handlers
 
-All of the event handlers you add to your solution are identified by which service
-they are watching and which event in that service triggers the script.
+Each event handler in your project is identified by which service
+it watches and which event in that service triggers the script.
+
+This is set with the following magic header line:
 
-This is set with the following line:
 ```lua
 --#EVENT SERVICE EVENT
 ```
 
-For example, the event handler that processes all data coming from your devices
-could be:
+To make working with the Product ID easier, you can use the magic
+variable `{product.id}` instead of the actual Product ID.
+You can use this variable in both the filename and the magic header.
+
+For example, the event handler that processes all data coming from your
+devices might look like:
+
 ```lua
---#EVENT device datapoint
+--#EVENT {product.id} event
 local stamped = nil
 if data.api == "record" then
   stamped = tostring(data.value[1]) .. 's'
@@ -200,31 +351,40 @@ Tsdb.write{
 }
 ```
 
-### MURANO_CONFIGFILE environment and Dotenv
+### MURANO_CONFIGFILE Environment Variable and Dotenv
+
+The environment variable `MURANO_CONFIGFILE` is checked for an additional config
+to load. This, in conjunction with [dotenv](https://github.com/bkeepers/dotenv)
+support, allows you to easily switch between development, staging, and production
+setups.
 
-The environment variable `MURANO_CONFIGFILE` is checked for an additional config to
-load.  This, in conjunction with [dotenv](https://github.com/bkeepers/dotenv) support,
-allows for easily switching between development, staging, and production setups.
+To use this, write the three Application IDs and three Product IDs for your three
+deployments into the three files, `.murano.dev`, `.murano.stg`, and `.murano.prod`.
 
-To use this, write the three solution ids into `.murano.dev`, `.murano.stg`,
-and `.murano.prod`. Then write the `.env` file to point at the system you're
-currently working on.
+Then, write the `.env` file to point at the system you're currently working on.
 
 The files for this are then:
+
 ```sh
 cat >> .murano.dev <<EOF
-[solution]
+[application]
 id=AAAAAAAA
+[product]
+id=BBBBBBBB
 EOF
 
 cat >> .murano.stg <<EOF
-[solution]
-id=BBBBBBBB
+[application]
+id=LLLLLLLL
+[product]
+id=MMMMMMMM
 EOF
 
 cat >> .murano.prod <<EOF
-[solution]
-id=CCCCCCCC
+[application]
+id=XXXXXXXX
+[product]
+id=YYYYYYYY
 EOF
 
 cat > .env <<EOF
@@ -232,23 +392,25 @@ MURANO_CONFIGFILE=.murano.dev
 EOF
 ```
 
-This also allows for keeping private things in a separate config file and having
-the shared things checked into source control.
+This also allows for keeping private things in a separate config file and
+having the shared things checked into source control.
 
 ### Direct Service Access
 
-To aid with debugging, MuranoCLI has direct access to some of the services in a
-solution.
+To aid with debugging, MuranoCLI has direct access to some of the services
+in an application.
 
 Currently these are:
+
 - Keystore: `murano keystore`
+
 - TSDB: `murano tsdb`
 
 ### Output Format
 
-Many sub-commands respect the `outformat` setting.  This lets you switch the output
-between YAML, JSON, Ruby, CSV, and pretty tables.  Not all formats work with all
-commands.
+Many sub-commands respect the `outformat` setting. This lets you switch the
+output between YAML, JSON, Ruby, CSV, and pretty tables. (Not all formats
+work with all commands, however.)
 
 ```
 > murano tsdb product list
@@ -260,13 +422,14 @@ commands.
 
 ### Product Content Area
 
-MuranoCLI can manage the content area for a product.  This area is a place to store
-files for use by devices.  Typically holding firmware images for Over-The-Air
-updating.  Although any kind of fleet wide data that devices may need to download
-can be stored here.
+MuranoCLI can manage the content area for a product. This area is a place to
+store files for use by devices. Storing firmware images for over-the-air
+updates is one typical use, although any kind of fleet-wide data that devices
+may need to download can be stored here.
+
+Once the `product.id` is set, the content for that product can be accessed
+with the following commands:
 
-Once the `product.id` is set, the content for that product can be accessed with the
-following commands:
 ```
 > murano content list
 > murano content upload
@@ -275,7 +438,7 @@ following commands:
 > murano content download
 ```
 
-Call them with `--help` for details.
+Call `murano` with `--help` for more details.
 
 ## Developing
 
@@ -284,20 +447,30 @@ MuranoCLI uses [git flow](https://github.com/nvie/gitflow#getting-started) for
 
 MuranoCLI also uses [bundler](http://bundler.io).
 
-When submitting pull requests, please do them against the develop branch.
+When submitting pull requests, please do them against the `develop` branch.
+
+### Testing
 
-### Tests
 All test for MuranoCLI are done with rspec.
 
-The tests are internal (`--tag ~cmd`) or command (`--tag cmd`).  The internal tests
-are for the objects that build up the internals. The command tests run `murano` from
-the shell and are for testing the user facing components.  A subset of the command
-tests work with the live Murano servers (`--tag needs_password`).
+The tests are internal (`--tag ~cmd`) or command (`--tag cmd`).
+
+- The internal tests are for the objects that build up the internals.
+
+- The command tests run `murano` from the shell and are for testing
+  the user facing components.
+
+  A subset of the command tests work with the live Murano servers
+  (`--tag needs_password`).
 
 To use the live tests, the following environment variables need to be set:
-- `MURANO_CONFIGFILE` : A Config with the user.name, business.id, and net.host for
-  the integration tests.
-- `MURANO_PASSWORD` : Password for the user.name above.
 
-A free account on Murano is sufficient for these tests.
+- `MURANO_CONFIGFILE`:
+  A Config with the user.name, business.id, and net.host for the integration tests.
+
+- `MURANO_PASSWORD`:
+  Password for the user.name above.
+
+A free account on [Murano](https://exosite.com/signup/) is sufficient for
+these tests.