qiot-io-cli
v0.1.1
Published
command line interface tool for qiot.io
Downloads
3
Readme
qiot-io-cli

Overview
The qiot-io-cli
allows an authorized user to access the APIs for any instance of the qiot-io
platform.
Command Summary
Usage: qc [options] <command> ...
Commands:
init [options] initialize general configuration settings
signin|si [email] [password] signin a local user with email and password
impersonate|i [userid] impersonate a userid, or clear impersonation if none provided
whoami|? dump current user information
accounts|a list visible accounts
collections|c list collections for an account
things|t [options] list things for an account or collection
users|u list users
messages|ms [options] [thing_token] list most recent messages
rest <method> <path> [body] make a REST api call
register|r [options] <identity> register a thing with an identity in the form of [<type>:]<value>[,[<type>:]<value>...]
log|l <thing_token> <message> log a message for a thing
mailbox|mb [options] <thing_token> [message] receive the mailbox entry for a thing without a message, send with one
fota <thing_token> <specs...> send mailbox FOTA specs (<target>,<version>[,<url>]) to the thing (experimental)
cota <thing_token> <settings...> send mailbox <key>=<value> settings to the thing (experimental)
socket|io <service> <event> <data> connect using socket.io to a service
mqtt|mq <thing_token> connect using an MQTT client for a thing
Options:
-h, --help output usage information
-V, --version output the version number
-a --account <id-or-token> target account (save-able)
-c --collection <id-or-token> target collection (save-able)
-n --limit <number> limit used for some queries
-s --save remember the applicable options as "current"
--clear forget the applicable options as "current"
--raw do not output any ansi special characters
--csv output query results to CSV format
--tsv output query results to TSV format
--json output query results in JSON format
--silent do not output query results
--debug turn on debugging for this command
--timestamps add timestamps to logs
-v --verbose display maximal output
One special note: Anywhere that a "thing_token" is specified as a command line argument,
you may use the special symbol @
to represent a "current thing" stored in the configuration file.
This "current thing" can be captured automatically with the qc register
command and the --save
option.
A few commands have command-specific options such as the following:
init
Usage: init [options]
initialize general configuration settings
Options:
-h, --help output usage information
--defaults prompt with defaults instead of current settings
--reset reset settings to defaults
messages
Usage: messages|ms [options] [thing_token]
list most recent messages
Options:
-h, --help output usage information
-f --filter <field-names> a comma-separated list of field labels to display
--socket message socket only available when a thing_token is given
--from <datetime> return messages after the given datetime
--to <datetime> return messages before the given datetime
things
Usage: things|t [options]
list things for an account or collection
Options:
-h, --help output usage information
--socket thing socket only available when an account is given
Getting Started
Install
You can install globally as follows:
npm install qiot-io-cli -g
Configure
Start by using qc init
to setup your initial configuration settings.
If you are accessing the standard public site as a user, you can accept the defaults.
If you want to access the "thing-proxy" to simulate device communications,
you will need to provide an account_token
--
you can find your account_token
on the settings page when logging in as a web user.
This information is stored in the current working directory called .qc.json
.
NOTE: qc
is sensitive to current working directory where .qc.json
is stored.
this allows you to have different profiles for execution by changing working directory.
Sign In or Capture API Token
If you are a superadmin on your qiot.io
deployment,
use qc signin
to sign in to the services layer to receive a user_token
that will be used
to authenticate your API requests.
NOTE: At this time, only local users are able to use the qc signin
command.
Otherwise, you can capture the "API Token" to clipboard on the "Settings" page of the web application.
Paste this as the user_token
when prompted in the qc init
command.
Next Steps
- Support loading message bodies from the file system
- Support centralized storage of multiple profiles
- Support more/all REST actions of the API (e.g., PUT (more), PATCH, DELETE)
Tips and Tricks
servers
If you are running development instances of the qiot-io
services, you can manually change the .qc.json
configuration file
to reference all APIs and socket endpoints (e.g., MQTT and socket.io) on localhost.
To do this you need to make the following changes:
{
"host_service": "http",
"host_dns": "localhost",
"host_port": 3000,
"proxy_dns": "localhost",
"mqtt_protocol":"mqtt",
"mqtt_port": 1883
}
mqtt
The qc mqtt
command will accept a JSON message payload when prompted and will 1) verify that the JSON is valid and 2) put add it as the contents of {"messages":[ ... ]}
to construct a properly complete message to the server.
However, sometimes you might want to test invalid JSON so simply use the --raw
option when executing the command,
but keep in mind that you will then be required to include the full message payload if needed.
How to contribute?
You are welcome to help add/extend this tool.
To do so, please use pull requests and follow the general style of the code already in place.
For a pull request to be accepted, it must maintain the commitment to 100% code coverage.
NOTE: This tool is designed to run using node v4.5.0 in order to support embedded Linux. This means that ES6 syntax should NOT be used.
Thanks!