feat: experimental HTTP API

This is a very minimal first implementation, just to get the ball
rolling. This exposes most commands (excluding any interactive or
perpetually running commands) via an HTTP API, served by the
`garden serve` command, as well as during execution of commands that
watch for file changes, e.g. `garden dev`.

For now, the latter is only enabled if you set the GARDEN_ENABLE_SERVER
env variable, e.g. `GARDEN_ENABLE_SERVER=1 garden dev`. To avoid
conflicts, those commands start the server with a randomly allocated
free port, whereas `garden serve` uses a fixed port, which the user can
override.

docs/basics/quick-start.md

@@ -45,14 +45,14 @@ To run tests for all modules:
 $ garden test
 ```
 
-And if you prefer an interactive terminal that watches your project for changes and re-builds, re-deploys, and re-tests automatically, try:
+And if you prefer an all-in-one command that watches your project for changes and re-builds, re-deploys, and re-tests automatically, try:
 
 ```sh
 $ garden dev
 ```
 
 Go ahead, leave it running and change one of the files in the project, then watch it re-build.
 
-That's it for now. Check out our [Using Garden](../using-garden/README.md) section for other features like hot reload, remote clusters, integration tests, and lots more. 
+That's it for now. Check out our [Using Garden](../using-garden/README.md) section for other features like hot reload, remote clusters, integration tests, and lots more.
 
 To see how a Garden project is configured from scratch check, out the [Simple Project](../examples/simple-project.md) guide for a more in-depth presentation.

docs/reference/commands.md

@@ -17,7 +17,7 @@ The following option flags can be used with any of the CLI commands:
   | `--silent` | `-s` | boolean | Suppress log output.
   | `--env` | `-e` | string | The environment (and optionally namespace) to work against.
   | `--loglevel` | `-l` | `error` `warn` `info` `verbose` `debug` `silly` `0` `1` `2` `3` `4` `5`  | Set logger level. Values can be either string or numeric and are prioritized from 0 to 5 (highest to lowest) as follows: error: 0, warn: 1, info: 2, verbose: 3, debug: 4, silly: 5.
-  | `--output` | `-o` | `json` `yaml`  | Output command result in specified format (note: disables progress logging).
+  | `--output` | `-o` | `json` `yaml`  | Output command result in specified format (note: disables progress logging and interactive functionality).
   | `--emoji` |  | boolean | Enable emoji in output (defaults to true if the environment supports it).
 
 ### garden build
@@ -271,7 +271,7 @@ Examples:
 
 ##### Usage
 
-    garden exec <service> <command> 
+    garden exec <service> <command> [options]
 
 ##### Arguments
 
@@ -280,6 +280,12 @@ Examples:
   | `service` | Yes | The service to exec the command in.
   | `command` | Yes | The command to run.
 
+##### Options
+
+| Argument | Alias | Type | Description |
+| -------- | ----- | ---- | ----------- |
+  | `--interactive` |  | boolean | Set to false to skip interactive mode and just output the command result
+
 ### garden get secret
 
 Get a secret from the environment.
@@ -558,6 +564,24 @@ Scans your project and outputs an overview of all modules.
 
     garden scan 
 
+### garden serve
+
+Starts the Garden HTTP API service - **Experimental**
+
+**Experimental**
+
+Starts an HTTP server that exposes Garden commands and events.
+
+##### Usage
+
+    garden serve [options]
+
+##### Options
+
+| Argument | Alias | Type | Description |
+| -------- | ----- | ---- | ----------- |
+  | `--port` |  | number | The port number for the Garden service to listen on.
+
 ### garden set secret
 
 Set a secret value for a provider in an environment.