README
¶
What
conch is a CLI for accessing the Conch API.
Getting The App
Releases are available over at https://github.com/joyent/conch-shell/releases for a handful of platforms, including macOS, Linux, and Solaris/SmartOS.
Joyent Employees
The latest production release at https://github.com/joyent/conch-shell/releases/latest is certified against the production instance.
The most recent release is not certified for production yet (thus the 'pre-release' tag) and probably works best against the staging instance. Grab it at https://github.com/joyent/conch-shell/releases
Data Guarantee
One of the major goals of this application is to provide a stable data
interface for the Conch API. To that end, to the best of our ability, the JSON
output (conch -j :command) will not remove data or change its meaning. Data
may be added, but not subtracted. If data must be removed, this change will
be announced in advance and the major version of the application will be
incremented.
Exceptions
Device Reports
Device reports have evolved organically over time and are inconsistent. While an effort is underway to standardize those reports, at the time of writing, existing reports cannot be parsed in such a way as to guarantee consistent results. As such, the JSON output of a device report matches the data as provided by the API, without any guarantees of compatibility.
Notes
SSL Certs
Go makes a lot of assumptions about a user's runtime environment. One assumption
is that a system holds SSL certs in a set of default directories which are
hardcoded into the go runtime by platform. If the user's runtime differs from
go's expectation, the user will receive a message like x509: failed to load system roots and no roots provided.
To set a custom location for SSL certs, one can specify SSL_CERT_DIR or
SSL_CERT_FILE in the environment before running conch shell.
For instance: SSL_CERT_FILE=/opt/certs.pem conch login
Copyright / License
Copyright Joyent Inc
This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0. If a copy of the MPL was not distributed with this file, You can obtain one at http://mozilla.org/MPL/2.0/.
Building
go get github.com/joyent/conch-shell. This installs the code at$GOPATH/src/github.com/joyent/conch-shell- In the
conch-shellcheckout:make tools- Install the necessary build toolsmake- Build the application
Notes
Always use the Makefile to build the app. The Makefile passes necessary build vars into the app.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
pkg
|
|
|
commands
Package commands is the parent that loads up the full command set
|
Package commands is the parent that loads up the full command set |
|
commands/internal/admin
Package admin contains administrative commands for the conch api
|
Package admin contains administrative commands for the conch api |
|
commands/internal/api
Package api contains commands that allow direct API access
|
Package api contains commands that allow direct API access |
|
commands/internal/devices
Package devices contains commands pertaining to individual devices
|
Package devices contains commands pertaining to individual devices |
|
commands/internal/global
Package global contains commands that operate on structures in the global domain, rather than a workspace.
|
Package global contains commands that operate on structures in the global domain, rather than a workspace. |
|
commands/internal/hardware
Package hardware contains commands related to hardware products, profiles, and the like
|
Package hardware contains commands related to hardware products, profiles, and the like |
|
commands/internal/profile
Package profile contains commands pertaining to login profiles
|
Package profile contains commands pertaining to login profiles |
|
commands/internal/relay
Package relay contains commands that pertain to relay devices
|
Package relay contains commands that pertain to relay devices |
|
commands/internal/update
Package update contains commands related to updating conch-shell
|
Package update contains commands related to updating conch-shell |
|
commands/internal/user
Package user contains command pertaining to the active Conch user
|
Package user contains command pertaining to the active Conch user |
|
commands/internal/validation
Package validation contains commands for validation related commands Package validation contains commands for validation related commands Package validation contains commands for validation related commands Package validation contains commands for validation related commands
|
Package validation contains commands for validation related commands Package validation contains commands for validation related commands Package validation contains commands for validation related commands Package validation contains commands for validation related commands |
|
commands/internal/workspaces
Package workspaces contains commands for dealing with objects tied to a workspace
|
Package workspaces contains commands for dealing with objects tied to a workspace |
|
conch
Package conch provides access to the Conch API
|
Package conch provides access to the Conch API |
|
config
Package config wraps a conch shell config.
|
Package config wraps a conch shell config. |
|
pgtime
Package pgtime provides a wrapper around the raw Postgres 'timestamp with time zone' that comes back from the API, providing JSON marshalling and unmarshalling
|
Package pgtime provides a wrapper around the raw Postgres 'timestamp with time zone' that comes back from the API, providing JSON marshalling and unmarshalling |
|
util
Package util contains common routines used throughout the command base Package util contains common routines used throughout the command base
|
Package util contains common routines used throughout the command base Package util contains common routines used throughout the command base |