From 37b2965953c8244805f63e1f966c61a5891c0f73 Mon Sep 17 00:00:00 2001 From: Doug Davis Date: Tue, 5 Jul 2016 13:58:02 -0700 Subject: [PATCH] Add initial pass at a cmd line spec Signed-off-by: Doug Davis --- Makefile | 1 + README.md | 1 + cmd.md | 96 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 98 insertions(+) create mode 100644 cmd.md diff --git a/Makefile b/Makefile index a35e2fac1..4d7e32b10 100644 --- a/Makefile +++ b/Makefile @@ -32,6 +32,7 @@ DOC_FILES := \ bundle.md \ runtime.md \ runtime-linux.md \ + cmd.md \ config.md \ config-linux.md \ config-solaris.md \ diff --git a/README.md b/README.md index 6835d82c3..9d9ac846d 100644 --- a/README.md +++ b/README.md @@ -16,6 +16,7 @@ Table of Contents - Runtime and Lifecycle - [General Runtime and Lifecycle](runtime.md) - [Linux-specific Runtime and Lifecycle](runtime-linux.md) + - [Runtime Command Line Interface](cmd.md) - Configuration - [General Configuration](config.md) - [Linux-specific Configuration](config-linux.md) diff --git a/cmd.md b/cmd.md new file mode 100644 index 000000000..1d07eee0b --- /dev/null +++ b/cmd.md @@ -0,0 +1,96 @@ +# Runtime Command Line Interface + +This document specifies the command line syntax for runtime operations defined in the [Runtime and Lifecycle](runtime.md) specification. +It is STRONGLY RECOMMENDED that implementations adhere to the command line definition defined below to ensure interoperability. +This document will not duplicate the information/semantics specified in the [Runtime and Lifecycle](runtime.md) document, rather it just focuses on syntax of the command line. + +## Convention + +For the purpose of this document, the following syntactical conventions are used: + +* `[ ... ]` denotes an optional field +* `< ... >` denotes a substitution field. +The word(s), or phrase, within the `<>` describes the information to be passed-in. + +## General Format and Behavior + +The general format of all commands MUST be: +``` +runtime [global-options] action [action-specific-options] [arguments] +``` + +Unknown options (global and action specific) MUST generate an error and exit with a non-zero exit code, without changing the state of the environment. + +Upon successful running of an action, the exit code MUST be zero. + +If there is an error during the running of an action, then: +* the exit code MUST be non-zero +* any error text MUST be displayed on stderr +* the state of the environment SHOULD be the same as if the action was never attempted (modulo any possible trivial ancillary changes such as logging) + +### Global Options + +Global options are ones that apply to all actions. +This specification doesn't define any global options. +Implementation MAY define their own. + +### Action Specific Options + +All actions MUST support the `--help` action-specific-option, which: +* MUST display some help text to stdout +* MUST NOT perform the `action` itself +* MUST have an exit code of zero if the help text is successfully displayed + +Implementations MAY define their own action-specific options. + +## Actions + +This section defines the actions defined by this specification. + +### State + +Format: `runtime [global-options] state [options] ` + +Options: None + +This action MUST display the state of the specific container to stdout. +Unless otherwise specified by the user, the format of the state MUST be in JSON. + +See [Query State](runtime.md#query-state). + +### Create + +Format: `runtime [global-options] create [options] ` + +Options: +* `-b `, `--bundle ` The path to the root of the bundle directory. If not specified the default value MUST be the current working directory. +* `--console ` The PTY slave path for the newly created container. +* `--pid-file ` The file path into which the process ID is written. If not specified then a file MUST NOT be created. + +See [Create](runtime.md#create). + +### Start + +Format: `runtime [global-options] start [options] ` + +Options: None + +See [Start](runtime.md#start). + +### Kill + +Format: `runtime [global-options] kill [options] ` + +Options: None + +The `signal` MUST either be the signal's numerical value (e.g. `15`) or the signal's name (e.g. `SIGTERM`). + +See [Kill](runtime.md#kill). + +### Delete + +Format: `runtime [global-options] delete [options] ` + +Options: None + +See [Delete](runtime.md#delete).