adds uds runner docs

README.md

@@ -7,6 +7,14 @@
 
 **:warning: Warning**:  UDS-CLI is in early alpha, expect changes to the schema and workflow
 
+## Install
+Recommended installation method is with Brew:
+```
+brew tap defenseunicorns/tap && brew install uds
+```
+UDS CLI Binaries are also included with each [Github Release](https://github.com/defenseunicorns/uds-cli/releases)
+
+
 ## Quickstart
 The UDS-CLI's flagship feature is deploying multiple, independent Zarf packages. To create a `UDSBundle` of Zarf packages, create a `uds-bundle.yaml` file like so:
 
@@ -106,4 +114,7 @@ That is to say, deploy-time variables declared in `uds-config.yaml` take precede
 ## Bundle Anatomy
 A UDS Bundle is an OCI artifact with the following form:
 
-![](docs/.images/uds-bundle.png)
+![](docs/.images/uds-bundle.png)
+
+## UDS Runner
+UDS runner docs can be found [here](docs/runner.md)

docs/runner.md

@@ -0,0 +1,250 @@
+# UDS Runner
+
+UDS runner enables UDS Bundle developers to automate UDS builds and perform common shell tasks. It
+uses [Zarf](https://zarf.dev/) under the hood to perform tasks and shares a syntax similar to `zarf.yaml` manifests.
+Many [Zarf Actions features](https://docs.zarf.dev/docs/create-a-zarf-package/component-actions) are also available in
+UDS runner.
+
+## Table of Contents
+
+1. [Quickstart](#quickstart)
+2. [Key Concepts](#key-concepts)
+    - [Tasks](#tasks)
+    - [Actions](#actions)
+        - [Task](#task)
+        - [Cmd](#cmd)
+    - [Variables](#variables)
+    - [Files](#files)
+    - [Wait](#wait)
+
+## Quickstart
+
+Create a file called `tasks.yaml`
+
+```yaml
+variables:
+  - name: FOO
+    default: foo
+
+tasks:
+  - name: example
+    actions:
+      - task: set-variable
+      - task: echo-variable
+
+  - name: set-variable
+    actions:
+      - cmd: echo "bar"
+        setVariables:
+          - name: FOO
+
+  - name: echo-variable
+    actions:
+      - cmd: echo ${FOO}
+```
+
+From the same directory as the `tasks.yaml`, run the `example` task using:
+
+```
+uds run example
+```
+
+This will run the `example` tasks which in turn runs the `set-variable` and `echo-variable`. In this example, the text "
+bar" should be printed to the screen twice.
+
+Optionally, you can specify the location and name of your `tasks.yaml` using the `--file` or `-f` flag:
+
+```
+uds run example -f tmp/tasks.yaml
+```
+
+## Key Concepts
+
+### Tasks
+
+Tasks are the fundamental building blocks of the UDS runner and they define operations to be performed. The `tasks` key
+at the root of `tasks.yaml` define a list of tasks to be run. This underlying operations performed by a task are defined
+under the `actions` key:
+
+```yaml
+tasks:
+  - name: all-the-tasks
+    actions:
+      - task: make-build-dir
+      - task: install-deps
+```
+
+In this example, the name of the task is "all-the-tasks", and it is composed multiple sub-tasks to run. These sub-tasks
+would also be defined in the list of `tasks`:
+
+```yaml
+tasks:
+  - name: all-the-tasks
+    actions:
+      - task: make-build-dir
+      - task: install-deps
+
+  - name: make-build-dir
+    actions:
+      - cmd: mkdir -p build
+
+  - name: install-deps
+    actions:
+      - cmd: go mod tidy
+```
+
+Using the UDS CLI, these tasks can be run individually:
+
+```
+uds run all-the-tasks   # runs all-the-tasks, which calls make-build-dir and install-deps
+uds run make-build-dir  # only runs make-build-dir
+```
+
+### Actions
+
+Actions are the underlying operations that a task will perform. Each action under the `actions` key has a unique syntax.
+<section class="indent">
+
+#### Task
+
+A task can reference a task, thus making tasks composable.
+
+```yaml
+tasks:
+  - name: foo
+    actions:
+      - task: bar
+  - name: bar
+    actions:
+      - task: baz
+  - name: baz
+    actions:
+      - cmd: "echo task foo is composed of task bar which is composed of task baz!"
+```
+
+In this example, the task `foo` calls a task called `bar` which calls a task `baz` which prints some output to the
+console.
+
+#### Cmd
+
+Actions can run arbitrary bash commands including in-line scripts, and the output of a command can be placed in a
+variable using the `setVariables` key
+
+```yaml
+tasks:
+  - name: foo
+    actions:
+      - cmd: |
+          ARCH=$(uname -m)
+          [ "$ARCH" = "x86_64" ] && ARCH="amd64"
+          echo $ARCH
+        setVariables:
+          - name: FOO
+  ```
+
+This task will print out the name of the system architecture and set a variable named `FOO` that can be used in other
+tasks.
+
+Command blocks can have several other properties including:
+
+- `description`: description of the command
+    - `mute`: boolean value to mute the output of a command
+    - `dir`: the directory to run the command in
+    - `env`: list of environment variables to run for this `cmd` block only
+      ```yaml
+        tasks:
+          - name: foo
+            actions:
+              - cmd: echo ${BAR}
+                env:
+                  - BAR=bar
+       ```
+    - `maxRetries`: number of times to retry the command
+    - `maxTotalSeconds`: max number of seconds the command can run until it is killed; takes precendence
+      over `maxRetries`
+
+</section>
+
+### Variables
+
+Variables can be defined in 3 ways:
+
+1. At the top of the `tasks.yaml`
+    ```yaml
+   variables:
+      - name: FOO
+        default: foo
+   
+   tasks:
+     ...
+   ```
+1. As the output of a `cmd`
+   ```yaml
+   variables:
+      - name: FOO
+        default: foo
+   tasks:
+      - name: foo
+        actions:
+          - cmd: uname -m
+            mute: true
+            setVariables:
+              - name: FOO
+          - cmd: echo ${FOO}
+   ```
+1. Using the `--set` flag :construction:
+
+To use a variable, reference it using `${VAR_NAME}`
+
+Note that variables also have the following attributes:
+
+- `sensitive`: boolean value indicating if a variable should be visible in output
+- `default`: default value of a variable
+
+### Files
+
+The `files` key is used to copy local or remote files to the current working directory
+
+```yaml
+tasks:
+  - name: copy-local
+    files:
+      - source: /tmp/foo
+        target: foo
+  - name: copy-remote
+    files:
+      - source: https://cataas.com/cat
+        target: cat.jpeg
+```
+
+Files blocks can also use the following attributes:
+
+- `executable`: boolean value indicating if the file is executable
+- `shasum`: SHA string to verify the integrity of the file
+- `symlinks`: list of strings referring to symlink the file to
+
+### Wait
+
+The `wait`key is used to block execution while waiting for a resource, including network responses and K8s operations
+
+```yaml
+tasks:
+  - name: network-response
+    wait:
+      network:
+        protocol: https
+        address: 1.1.1.1
+        code: 200
+  - name: configmap-creation
+    wait:
+      cluster:
+        kind: configmap
+        name: simple-configmap
+        namespace: foo
+```
+
+<style>
+  .indent {
+    padding-left: 2em;
+  }
+</style>