bixu · June 7, 2018 17:31 · Jun 7, 2018 · Jun 7, 2018 · Jun 7, 2018 · Jun 7, 2018
diff --git a/services_cli.md b/services_cli.md
@@ -1,4 +1,4 @@
-Habitat CLI UX
+## Habitat CLI UX
 
 What’s confusing now:
 - `start` does not load a service, but `load` starts one…

diff --git a/services_cli.md b/services_cli.md
@@ -1,4 +1,42 @@
-## `svcadm` commands
+Habitat CLI UX
+
+What’s confusing now:
+- `start` does not load a service, but `load` starts one…
+- historically, `start` or `load` would also install a service, but this is no longer the case for `start`
+
+
+Possible alternatives, with an imaginary workflow:
+```
+$ hab search/provides <ident>
+
+$ hab install <ident>
+
+$ hab start <ident>
+```
+
+Each of the above steps can be considered a set of nested sets representing service state:
+```
+——————————————————————————————————
+——————————————————————————        |
+————————————————          |       |
+search/provides | install | start | 
+————————————————          |       |
+——————————————————————————        |
+——————————————————————————————————
+```
+
+If user input is needed, like if we choose to `start` a not-yet-installed service, we should be present with a confirmation prompt and an optional auto-accept flag for automation:
+```
+$ hab start <ident>
+
+<ident> is not installed. Do you want to install it now?
+yes/no
+
+$ hab start <ident> --yes
+```
+
+## Prior Art
+### `svcadm` commands
 
 `enable [–s]`
 Enables the service instances specified by the operands. For each service instance, the assigned restarter will try to bring it to the online state. If the –s option is specified, svcadm enables each service instance and then waits for each service instance to enter the online or degraded state. svcadm will return early if it determines that the service cannot reach these states without administrator intervention.
@@ -15,10 +53,7 @@ For each service instance specified by the operands, requests that the assigned
 `clear [–s]`
 For each service instance specified by the operands, if the instance is in the maintenance state, signal to the assigned restarter that the service has been repaired.
 
-
-
-
-## `systemctl` unit commands:
+### `systemctl` unit commands:
 `start`
 Start (activate) one or more units specified on the command line.
 

diff --git a/services_cli.md b/services_cli.md
@@ -16,6 +16,8 @@ For each service instance specified by the operands, requests that the assigned
 For each service instance specified by the operands, if the instance is in the maintenance state, signal to the assigned restarter that the service has been repaired.
 
 
+
+
 ## `systemctl` unit commands:
 `start`
 Start (activate) one or more units specified on the command line.

diff --git a/services_cli.md b/services_cli.md
@@ -1,63 +1,33 @@
 ## `svcadm` commands
 
-enable [–s]
+`enable [–s]`
 Enables the service instances specified by the operands. For each service instance, the assigned restarter will try to bring it to the online state. If the –s option is specified, svcadm enables each service instance and then waits for each service instance to enter the online or degraded state. svcadm will return early if it determines that the service cannot reach these states without administrator intervention.
 
-disable [–s]
+`disable [–s]`
 Disables the service instance specified by the operands.
 
-restart [–s]
+`restart [–s]`
 Requests that the service instances specified by the operands be restarted.
 
-refresh [–s]
+`refresh [–s]`
 For each service instance specified by the operands, requests that the assigned restarter update the service's running configuration snapshot with the values from the current configuration.
 
-clear [–s]
+`clear [–s]`
 For each service instance specified by the operands, if the instance is in the maintenance state, signal to the assigned restarter that the service has been repaired.
 
 
 ## `systemctl` unit commands:
-
-Unit Commands
-
-list-units [PATTERN…]
-List units that systemd currently has in memory.
-
-start PATTERN…
+`start`
 Start (activate) one or more units specified on the command line.
 
-stop PATTERN…
+`stop`
 Stop (deactivate) one or more units specified on the command line.
 
-reload PATTERN…
+`reload`
 Asks all units listed on the command line to reload their configuration.
 
-restart PATTERN…
+`restart`
 Stop and then start one or more units specified on the command line.
 
-try-restart PATTERN…
-Stop and then start one or more units specified on the command line if the units are running. This does nothing if units are not running.
-
-reload-or-restart PATTERN…
-Reload one or more units if they support it. If not, stop and then start them instead. If the units are not running yet, they will be started.
-
-try-reload-or-restart PATTERN…
-Reload one or more units if they support it. If not, stop and then start them instead. This does nothing if the units are not running.
-
-isolate UNIT
-Start the unit specified on the command line and its dependencies and stop all others.
-
-kill PATTERN…
-Send a signal to one or more processes of the unit.
-
-status [PATTERN…|PID…]]
+`status`
 Show terse runtime status information about one or more units, followed by most recent log data from the journal.
-
-show [PATTERN…|JOB…]
-Show properties of one or more units, jobs, or the manager itself.
-
-cat PATTERN…
-Show backing files of one or more units.
-
-set-property UNIT PROPERTY=VALUE…
-Set the specified unit properties at runtime where this is supported.
diff --git a/services_cli.md b/services_cli.md
@@ -1,18 +1,18 @@
 ## `svcadm` commands
 
-enable [–rt ] [–s [–T timeout]] {FMRI | pattern}. . .
-Enables the service instances specified by the operands. For each service instance, the assigned restarter will try to bring it to the online state. If the –s option is specified, svcadm enables each service instance and then waits for each service instance to enter the online or degraded state. svcadm will return early if it determines that the service cannot reach these states without administrator intervention. If the –T option is specified along with the –s option, svcadm will wait timeout seconds for the synchronous operation to complete. If timeout seconds pass and the action still has potential, svcadm will return early.
+enable [–s]
+Enables the service instances specified by the operands. For each service instance, the assigned restarter will try to bring it to the online state. If the –s option is specified, svcadm enables each service instance and then waits for each service instance to enter the online or degraded state. svcadm will return early if it determines that the service cannot reach these states without administrator intervention.
 
-disable [–t] [– s [–T timeout ]] {FMRI | pattern }. . .
+disable [–s]
 Disables the service instance specified by the operands.
 
-restart [–s [–T timeout] ] {FMRI | pattern}. . .
+restart [–s]
 Requests that the service instances specified by the operands be restarted.
 
-refresh [–s [–T timeout] ] {FMRI | pattern}. . .
+refresh [–s]
 For each service instance specified by the operands, requests that the assigned restarter update the service's running configuration snapshot with the values from the current configuration.
 
-clear [–s [–T timeout] ] {FMRI | pattern}. . .
+clear [–s]
 For each service instance specified by the operands, if the instance is in the maintenance state, signal to the assigned restarter that the service has been repaired.
 
 

diff --git a/services_cli.md b/services_cli.md
@@ -1,6 +1,6 @@
-`svcadm` commands
+## `svcadm` commands
 
-`enable` [–rt ] [–s [–T timeout]] {FMRI | pattern}. . .
+enable [–rt ] [–s [–T timeout]] {FMRI | pattern}. . .
 Enables the service instances specified by the operands. For each service instance, the assigned restarter will try to bring it to the online state. If the –s option is specified, svcadm enables each service instance and then waits for each service instance to enter the online or degraded state. svcadm will return early if it determines that the service cannot reach these states without administrator intervention. If the –T option is specified along with the –s option, svcadm will wait timeout seconds for the synchronous operation to complete. If timeout seconds pass and the action still has potential, svcadm will return early.
 
 disable [–t] [– s [–T timeout ]] {FMRI | pattern }. . .
@@ -16,7 +16,7 @@ clear [–s [–T timeout] ] {FMRI | pattern}. . .
 For each service instance specified by the operands, if the instance is in the maintenance state, signal to the assigned restarter that the service has been repaired.
 
 
-systemctl unit commands:
+## `systemctl` unit commands:
 
 Unit Commands
 

diff --git a/services_cli.md b/services_cli.md
@@ -0,0 +1,63 @@
+`svcadm` commands
+
+`enable` [–rt ] [–s [–T timeout]] {FMRI | pattern}. . .
+Enables the service instances specified by the operands. For each service instance, the assigned restarter will try to bring it to the online state. If the –s option is specified, svcadm enables each service instance and then waits for each service instance to enter the online or degraded state. svcadm will return early if it determines that the service cannot reach these states without administrator intervention. If the –T option is specified along with the –s option, svcadm will wait timeout seconds for the synchronous operation to complete. If timeout seconds pass and the action still has potential, svcadm will return early.
+
+disable [–t] [– s [–T timeout ]] {FMRI | pattern }. . .
+Disables the service instance specified by the operands.
+
+restart [–s [–T timeout] ] {FMRI | pattern}. . .
+Requests that the service instances specified by the operands be restarted.
+
+refresh [–s [–T timeout] ] {FMRI | pattern}. . .
+For each service instance specified by the operands, requests that the assigned restarter update the service's running configuration snapshot with the values from the current configuration.
+
+clear [–s [–T timeout] ] {FMRI | pattern}. . .
+For each service instance specified by the operands, if the instance is in the maintenance state, signal to the assigned restarter that the service has been repaired.
+
+
+systemctl unit commands:
+
+Unit Commands
+
+list-units [PATTERN…]
+List units that systemd currently has in memory.
+
+start PATTERN…
+Start (activate) one or more units specified on the command line.
+
+stop PATTERN…
+Stop (deactivate) one or more units specified on the command line.
+
+reload PATTERN…
+Asks all units listed on the command line to reload their configuration.
+
+restart PATTERN…
+Stop and then start one or more units specified on the command line.
+
+try-restart PATTERN…
+Stop and then start one or more units specified on the command line if the units are running. This does nothing if units are not running.
+
+reload-or-restart PATTERN…
+Reload one or more units if they support it. If not, stop and then start them instead. If the units are not running yet, they will be started.
+
+try-reload-or-restart PATTERN…
+Reload one or more units if they support it. If not, stop and then start them instead. This does nothing if the units are not running.
+
+isolate UNIT
+Start the unit specified on the command line and its dependencies and stop all others.
+
+kill PATTERN…
+Send a signal to one or more processes of the unit.
+
+status [PATTERN…|PID…]]
+Show terse runtime status information about one or more units, followed by most recent log data from the journal.
+
+show [PATTERN…|JOB…]
+Show properties of one or more units, jobs, or the manager itself.
+
+cat PATTERN…
+Show backing files of one or more units.
+
+set-property UNIT PROPERTY=VALUE…
+Set the specified unit properties at runtime where this is supported.