feat: name and version flags on create + generates CLI docs (#768)

Co-authored-by: Darcy Cleaver <[email protected]>
Co-authored-by: Tristan Holaday <[email protected]>

.github/workflows/test-schema.yaml → .github/workflows/test-schema-and-docs.yaml

@@ -1,4 +1,4 @@
-name: Validate Schema
+name: Validate Schema and Docs
 on:
   pull_request:
 
@@ -18,9 +18,12 @@ jobs:
       - name: Install UDS CLI
         uses: ./.github/actions/install-uds-cli
 
-      - name: Docs and schemas
+      - name: Test schemas
         run: uds run schema:test
 
+      - name: Test docs
+        run: uds run docs:test
+
       - name: Save logs
         if: always()
         uses: ./.github/actions/save-logs

.golangci.yml

@@ -1,4 +1,3 @@
----
 run:
   concurrency: 6
   timeout: 5m
@@ -13,6 +12,8 @@ issues:
   # Default: 3
   max-same-issues: 0
   new-from-rev: ""
+  exclude-dirs:
+    - docs/command-reference
   exclude-rules:
     - path: 'test/.*'
       linters:

.pre-commit-config.yaml

@@ -10,6 +10,7 @@ repos:
           - "--allow-missing-credentials"
       - id: detect-private-key
       - id: end-of-file-fixer
+        exclude: docs/command-reference
       - id: fix-byte-order-marker
       - id: trailing-whitespace
         args: [--markdown-linebreak-ext=md]

docs/bundle-anatomy.md

@@ -1,7 +1,7 @@
 ---
 title: Bundle Anatomy
 type: docs
-weight: 6
+weight: 4
 ---
 
 ## Bundle Anatomy

docs/command-reference/_index.md

@@ -0,0 +1,5 @@
+---
+title: Command Reference
+type: docs
+weight: 6
+---

docs/command-reference/uds.md

@@ -0,0 +1,42 @@
+---
+title: uds
+description: UDS CLI command reference for <code>uds</code>.
+type: docs
+---
+## uds
+
+CLI for UDS Bundles
+
+```
+uds COMMAND [flags]
+```
+
+### Options
+
+```
+  -a, --architecture string   Architecture for UDS bundles and Zarf packages
+  -h, --help                  help for uds
+      --insecure              Allow access to insecure registries and disable other recommended security enforcements such as package checksum and signature validation. This flag should only be used if you have a specific reason and accept the reduced security posture.
+  -l, --log-level string      Log level when running UDS-CLI. Valid options are: warn, info, debug, trace (default "info")
+      --no-log-file           Disable log file creation
+      --no-progress           Disable fancy UI progress bars, spinners, logos, etc
+      --oci-concurrency int   Number of concurrent layer operations to perform when interacting with a remote bundle. (default 3)
+      --tmpdir string         Specify the temporary directory to use for intermediate files
+      --uds-cache string      Specify the location of the UDS cache directory (default "~/.uds-cache")
+```
+
+### SEE ALSO
+
+* [uds completion](/cli/command-reference/uds_completion/)	 - Generate the autocompletion script for the specified shell
+* [uds create](/cli/command-reference/uds_create/)	 - Create a bundle from a given directory or the current directory
+* [uds deploy](/cli/command-reference/uds_deploy/)	 - Deploy a bundle from a local tarball or oci:// URL
+* [uds dev](/cli/command-reference/uds_dev/)	 - [beta] Commands useful for developing bundles
+* [uds inspect](/cli/command-reference/uds_inspect/)	 - Display the metadata of a bundle
+* [uds logs](/cli/command-reference/uds_logs/)	 - View most recent UDS CLI logs
+* [uds monitor](/cli/command-reference/uds_monitor/)	 - Monitor a UDS Cluster
+* [uds publish](/cli/command-reference/uds_publish/)	 - Publish a bundle from the local file system to a remote registry
+* [uds pull](/cli/command-reference/uds_pull/)	 - Pull a bundle from a remote registry and save to the local file system
+* [uds remove](/cli/command-reference/uds_remove/)	 - Remove a bundle that has been deployed already
+* [uds run](/cli/command-reference/uds_run/)	 - Run a task using maru-runner
+* [uds version](/cli/command-reference/uds_version/)	 - Shows the version of the running UDS-CLI binary
+

docs/command-reference/uds_completion.md

@@ -0,0 +1,42 @@
+---
+title: uds completion
+description: UDS CLI command reference for <code>uds completion</code>.
+type: docs
+---
+## uds completion
+
+Generate the autocompletion script for the specified shell
+
+### Synopsis
+
+Generate the autocompletion script for uds for the specified shell.
+See each sub-command's help for details on how to use the generated script.
+
+
+### Options
+
+```
+  -h, --help   help for completion
+```
+
+### Options inherited from parent commands
+
+```
+  -a, --architecture string   Architecture for UDS bundles and Zarf packages
+      --insecure              Allow access to insecure registries and disable other recommended security enforcements such as package checksum and signature validation. This flag should only be used if you have a specific reason and accept the reduced security posture.
+  -l, --log-level string      Log level when running UDS-CLI. Valid options are: warn, info, debug, trace (default "info")
+      --no-log-file           Disable log file creation
+      --no-progress           Disable fancy UI progress bars, spinners, logos, etc
+      --oci-concurrency int   Number of concurrent layer operations to perform when interacting with a remote bundle. (default 3)
+      --tmpdir string         Specify the temporary directory to use for intermediate files
+      --uds-cache string      Specify the location of the UDS cache directory (default "~/.uds-cache")
+```
+
+### SEE ALSO
+
+* [uds](/cli/command-reference/uds/)	 - CLI for UDS Bundles
+* [uds completion bash](/cli/command-reference/uds_completion_bash/)	 - Generate the autocompletion script for bash
+* [uds completion fish](/cli/command-reference/uds_completion_fish/)	 - Generate the autocompletion script for fish
+* [uds completion powershell](/cli/command-reference/uds_completion_powershell/)	 - Generate the autocompletion script for powershell
+* [uds completion zsh](/cli/command-reference/uds_completion_zsh/)	 - Generate the autocompletion script for zsh
+

docs/command-reference/uds_completion_bash.md

@@ -0,0 +1,61 @@
+---
+title: uds completion bash
+description: UDS CLI command reference for <code>uds completion bash</code>.
+type: docs
+---
+## uds completion bash
+
+Generate the autocompletion script for bash
+
+### Synopsis
+
+Generate the autocompletion script for the bash shell.
+
+This script depends on the 'bash-completion' package.
+If it is not installed already, you can install it via your OS's package manager.
+
+To load completions in your current shell session:
+
+	source <(uds completion bash)
+
+To load completions for every new session, execute once:
+
+#### Linux:
+
+	uds completion bash > /etc/bash_completion.d/uds
+
+#### macOS:
+
+	uds completion bash > $(brew --prefix)/etc/bash_completion.d/uds
+
+You will need to start a new shell for this setup to take effect.
+
+
+```
+uds completion bash
+```
+
+### Options
+
+```
+  -h, --help              help for bash
+      --no-descriptions   disable completion descriptions
+```
+
+### Options inherited from parent commands
+
+```
+  -a, --architecture string   Architecture for UDS bundles and Zarf packages
+      --insecure              Allow access to insecure registries and disable other recommended security enforcements such as package checksum and signature validation. This flag should only be used if you have a specific reason and accept the reduced security posture.
+  -l, --log-level string      Log level when running UDS-CLI. Valid options are: warn, info, debug, trace (default "info")
+      --no-log-file           Disable log file creation
+      --no-progress           Disable fancy UI progress bars, spinners, logos, etc
+      --oci-concurrency int   Number of concurrent layer operations to perform when interacting with a remote bundle. (default 3)
+      --tmpdir string         Specify the temporary directory to use for intermediate files
+      --uds-cache string      Specify the location of the UDS cache directory (default "~/.uds-cache")
+```
+
+### SEE ALSO
+
+* [uds completion](/cli/command-reference/uds_completion/)	 - Generate the autocompletion script for the specified shell
+

docs/command-reference/uds_completion_fish.md

@@ -0,0 +1,52 @@
+---
+title: uds completion fish
+description: UDS CLI command reference for <code>uds completion fish</code>.
+type: docs
+---
+## uds completion fish
+
+Generate the autocompletion script for fish
+
+### Synopsis
+
+Generate the autocompletion script for the fish shell.
+
+To load completions in your current shell session:
+
+	uds completion fish | source
+
+To load completions for every new session, execute once:
+
+	uds completion fish > ~/.config/fish/completions/uds.fish
+
+You will need to start a new shell for this setup to take effect.
+
+
+```
+uds completion fish [flags]
+```
+
+### Options
+
+```
+  -h, --help              help for fish
+      --no-descriptions   disable completion descriptions
+```
+
+### Options inherited from parent commands
+
+```
+  -a, --architecture string   Architecture for UDS bundles and Zarf packages
+      --insecure              Allow access to insecure registries and disable other recommended security enforcements such as package checksum and signature validation. This flag should only be used if you have a specific reason and accept the reduced security posture.
+  -l, --log-level string      Log level when running UDS-CLI. Valid options are: warn, info, debug, trace (default "info")
+      --no-log-file           Disable log file creation
+      --no-progress           Disable fancy UI progress bars, spinners, logos, etc
+      --oci-concurrency int   Number of concurrent layer operations to perform when interacting with a remote bundle. (default 3)
+      --tmpdir string         Specify the temporary directory to use for intermediate files
+      --uds-cache string      Specify the location of the UDS cache directory (default "~/.uds-cache")
+```
+
+### SEE ALSO
+
+* [uds completion](/cli/command-reference/uds_completion/)	 - Generate the autocompletion script for the specified shell
+

docs/command-reference/uds_completion_zsh.md

@@ -0,0 +1,63 @@
+---
+title: uds completion zsh
+description: UDS CLI command reference for <code>uds completion zsh</code>.
+type: docs
+---
+## uds completion zsh
+
+Generate the autocompletion script for zsh
+
+### Synopsis
+
+Generate the autocompletion script for the zsh shell.
+
+If shell completion is not already enabled in your environment you will need
+to enable it.  You can execute the following once:
+
+	echo "autoload -U compinit; compinit" >> ~/.zshrc
+
+To load completions in your current shell session:
+
+	source <(uds completion zsh)
+
+To load completions for every new session, execute once:
+
+#### Linux:
+
+	uds completion zsh > "${fpath[1]}/_uds"
+
+#### macOS:
+
+	uds completion zsh > $(brew --prefix)/share/zsh/site-functions/_uds
+
+You will need to start a new shell for this setup to take effect.
+
+
+```
+uds completion zsh [flags]
+```
+
+### Options
+
+```
+  -h, --help              help for zsh
+      --no-descriptions   disable completion descriptions
+```
+
+### Options inherited from parent commands
+
+```
+  -a, --architecture string   Architecture for UDS bundles and Zarf packages
+      --insecure              Allow access to insecure registries and disable other recommended security enforcements such as package checksum and signature validation. This flag should only be used if you have a specific reason and accept the reduced security posture.
+  -l, --log-level string      Log level when running UDS-CLI. Valid options are: warn, info, debug, trace (default "info")
+      --no-log-file           Disable log file creation
+      --no-progress           Disable fancy UI progress bars, spinners, logos, etc
+      --oci-concurrency int   Number of concurrent layer operations to perform when interacting with a remote bundle. (default 3)
+      --tmpdir string         Specify the temporary directory to use for intermediate files
+      --uds-cache string      Specify the location of the UDS cache directory (default "~/.uds-cache")
+```
+
+### SEE ALSO
+
+* [uds completion](/cli/command-reference/uds_completion/)	 - Generate the autocompletion script for the specified shell
+

docs/command-reference/uds_create.md

@@ -0,0 +1,42 @@
+---
+title: uds create
+description: UDS CLI command reference for <code>uds create</code>.
+type: docs
+---
+## uds create
+
+Create a bundle from a given directory or the current directory
+
+```
+uds create [DIRECTORY] [flags]
+```
+
+### Options
+
+```
+  -c, --confirm                       Confirm bundle creation without prompting
+  -h, --help                          help for create
+  -n, --name string                   Specify the name of the bundle
+  -o, --output string                 Specify the output (an oci:// URL) for the created bundle
+  -k, --signing-key string            Path to private key file for signing bundles
+  -p, --signing-key-password string   Password to the private key file used for signing bundles
+  -v, --version string                Specify the version of the bundle
+```
+
+### Options inherited from parent commands
+
+```
+  -a, --architecture string   Architecture for UDS bundles and Zarf packages
+      --insecure              Allow access to insecure registries and disable other recommended security enforcements such as package checksum and signature validation. This flag should only be used if you have a specific reason and accept the reduced security posture.
+  -l, --log-level string      Log level when running UDS-CLI. Valid options are: warn, info, debug, trace (default "info")
+      --no-log-file           Disable log file creation
+      --no-progress           Disable fancy UI progress bars, spinners, logos, etc
+      --oci-concurrency int   Number of concurrent layer operations to perform when interacting with a remote bundle. (default 3)
+      --tmpdir string         Specify the temporary directory to use for intermediate files
+      --uds-cache string      Specify the location of the UDS cache directory (default "~/.uds-cache")
+```
+
+### SEE ALSO
+
+* [uds](/cli/command-reference/uds/)	 - CLI for UDS Bundles
+