docs: add secret documentation and tidy up exec

docs/guide/executable.md

@@ -1,8 +1,7 @@
-Executables are customizable actions defined in a YAML [flowfile](#flowfile).
-
 ## Finding Executables
 
-There are a few different [flow library](../cli/flow_library.md) command that can be used to find executables:
+Executables are customizable actions defined in a YAML [flowfile](#flowfile). There are a few [flow library](../cli/flow_library.md)
+command that can be used to find executables:
 
 ```shell
 flow library # Multi-pane view for browsing executables
@@ -14,7 +13,10 @@ The `flow library` and `flow library glance` commands accept optional command-li
 executables by workspace, namespace, verb, or tag:
 
 ```shell
-flow library --workspace ws --namespace ns --verb exec --tag my-tag
+flow library --workspace ws --namespace ns --verb exec --tag my-tag 
+# additionally, the --all flag can be used to show executables from all namespaces and the 
+# --filter flag can be used to search the executable names and descriptions
+flow library --all --filter "search string"
 ```
 
 ## Running Executables
@@ -215,7 +217,7 @@ executables:
   - verb: "test"
     name: "unit"
     exec:
-      file: "run-tests.sh"
+      cmd: "cp $HOME/unit-tests.sh . && ./unit-tests.sh"
       dir: "f:tmp"
 ```
 
@@ -309,34 +311,34 @@ executables:
 
 ```yaml
 executables:
-  - verb: open
-    name: ws-config
+  - verb: "open"
+    name: "ws-config"
     launch:
-      uri: $FLOW_WORKSPACE_PATH
+      uri: "$FLOW_WORKSPACE_PATH"
       wait: true
 ```
 
 ##### request
 
 ```yaml
 executables:
-  - verb: transform
-    name: request-response
+  - verb: "transform"
+    name: "greeting"
     request:
-      method: POST
-      url: https://httpbin.org/post
+      method: "POST"
+      url: "https://httpbin.org/post"
       body: '{"hello": "world"}'
       logResponse: true
-      transformResponse: .args.hello = "universe" | .args
+      transformResponse: ".args.hello = 'universe' | .args"
 ```
 
 ##### render
 
 ```yaml
 executables:
-  - verb: render
-    name: documentation
+  - verb: "render"
+    name: "documentation"
     render:
-      templateFile: template.md
-      templateDataFile: template-data.yaml
+      templateFile: "template.md"
+      templateDataFile: "template-data.yaml"
 ```

docs/guide/secret.md

@@ -1,3 +1,60 @@
-coming soon...
+## Vault Setup
 
-In the meantime, see [flow secret](../cli/flow_secret.md).
+The flow CLI has an integrated vault that can be used to store secrets. The vault is encrypted using a password that you provide. 
+Secrets are stored locally and encrypted with a generated key. To setup a new vault, run the following command:
+
+```shell
+flow secret vault create
+```
+
+The output will include the randomly generated key. You will need to store this key in a safe place. If you lose this key, 
+you will not be able to access your secrets.
+
+Whenever you invoke an executable that requires access to the vault or modify vault data, you will be prompted to enter 
+the generated key. The `FLOW_VAULT_KEY` environment variable can be used to set the key. You could include this in your 
+shell profile to avoid having to enter the key each time.
+
+> [!TIP]
+> You can create multiple vaults by repeating the above command. Switch your encryption key to switch between vaults.
+
+## Adding Secrets
+
+To add a secret to the vault, run the following command:
+
+```shell
+flow secret set KEY VALUE
+# Alternatively, you can just include the key and the CLI will prompt you for the value
+flow secret set KEY
+```
+
+## Retrieving Secrets
+
+See the [executable guide](executable.md#environment-variables) for information on how to include secrets as executable
+environment variables. The `secretRef` provided is equivalent to the key you used when adding the secret to the vault.
+
+Additionally, you can view secrets in the vault by running the following commands:
+
+```shell
+flow secret list # List all secrets in the vault
+flow secret view KEY # View the value of a specific secret
+```
+
+By default, those commands will not display the secret values. You will need to provide the `--plainText` flag to view 
+the values.
+
+## Removing Secrets
+
+To remove a secret from the vault, run the following command:
+
+```shell
+flow secret delete KEY
+```
+
+You can also delete secrets in the interactive views when retrieving secrets.
+
+## Backup and Restore
+
+The vault data is stored in flow cache directory. On Linux, this is typically `~/.cache/flow/vault` or `$XDG_CACHE_HOME/flow/vault`.
+On MacOS, this is typically `~/Library/Caches/flow/vault`. There is a directory for each vault you create. 
+
+You can back up the vault by copying the directory to a safe location. To restore the vault, copy the directory back to the cache location.