Improve artifact commands docs

Signed-off-by: Stefan Prodan <stefan.prodan@gmail.com>

cmd/flux/build_artifact.go

@@ -29,8 +29,11 @@ var buildArtifactCmd = &cobra.Command{
 	Use:   "artifact",
 	Short: "Build artifact",
 	Long:  `The build artifact command creates an tgz file with the manifests from the given directory.`,
-	Example: `# Build the given manifests directory into an artifact
-flux build artifact --path ./path/to/local/manifests --output ./path/to/artifact.tgz
+	Example: `  # Build the given manifests directory into an artifact
+  flux build artifact --path ./path/to/local/manifests --output ./path/to/artifact.tgz
+
+  # List the files bundles in the artifact
+  tar -ztvf ./path/to/artifact.tgz
 `,
 	RunE: buildArtifactCmdRun,
 }

cmd/flux/list_artifact.go

@@ -31,9 +31,9 @@ var listArtifactsCmd = &cobra.Command{
 	Use:   "artifacts",
 	Short: "list artifacts",
 	Long: `The list command fetches the tags and their metadata from a remote OCI repository.
-The list command uses the credentials from '~/.docker/config.json'.`,
-	Example: `# list the artifacts stored in an OCI repository
-flux list artifact oci://ghcr.io/org/manifests/app
+The command uses the credentials from '~/.docker/config.json'.`,
+	Example: `  # List the artifacts stored in an OCI repository
+  flux list artifact oci://ghcr.io/org/config/app
 `,
 	RunE: listArtifactsCmdRun,
 }

cmd/flux/push_artifact.go

@@ -29,13 +29,21 @@ import (
 var pushArtifactCmd = &cobra.Command{
 	Use:   "artifact",
 	Short: "Push artifact",
-	Long: `The push artifact command creates a tarball from the given directory and uploads the artifact to a OCI repository.
-The push command uses the credentials from '~/.docker/config.json'.`,
-	Example: `# Push the local manifests to GHCR
-flux push artifact oci://ghcr.io/org/manifests/app:v0.0.1 \
+	Long: `The push artifact command creates a tarball from the given directory and uploads the artifact to an OCI repository.
+The command uses the credentials from '~/.docker/config.json'.`,
+	Example: `  # Push manifests to GHCR using the short Git SHA as the OCI artifact tag
+  echo $GITHUB_PAT | docker login ghcr.io --username flux --password-stdin
+  flux push artifact oci://ghcr.io/org/config/app:$(git rev-parse --short HEAD) \
 	--path="./path/to/local/manifests" \
 	--source="$(git config --get remote.origin.url)" \
 	--revision="$(git branch --show-current)/$(git rev-parse HEAD)"
+
+  # Push manifests to Docker Hub using the Git tag as the OCI artifact tag
+  echo $DOCKER_PAT | docker login --username flux --password-stdin
+  flux push artifact oci://docker.io/org/app-config:$(git tag --points-at HEAD) \
+	--path="./path/to/local/manifests" \
+	--source="$(git config --get remote.origin.url)" \
+	--revision="$(git tag --points-at HEAD)/$(git rev-parse HEAD)"
 `,
 	RunE: pushArtifactCmdRun,
 }
@@ -50,7 +58,7 @@ var pushArtifactArgs pushArtifactFlags
 
 func init() {
 	pushArtifactCmd.Flags().StringVar(&pushArtifactArgs.path, "path", "", "Path to the directory where the Kubernetes manifests are located.")
-	pushArtifactCmd.Flags().StringVar(&pushArtifactArgs.source, "source", "", "The source address, e.g. Git URL.")
+	pushArtifactCmd.Flags().StringVar(&pushArtifactArgs.source, "source", "", "The source address, e.g. the Git URL.")
 	pushArtifactCmd.Flags().StringVar(&pushArtifactArgs.revision, "revision", "", "The source revision in the format '<branch|tag>/<commit-sha>'")
 	pushCmd.AddCommand(pushArtifactCmd)
 }

cmd/flux/tag_artifact.go

@@ -29,9 +29,9 @@ var tagArtifactCmd = &cobra.Command{
 	Use:   "artifact",
 	Short: "Tag artifact",
 	Long: `The tag artifact command creates tags for the given OCI artifact.
-The tag command uses the credentials from '~/.docker/config.json'.`,
-	Example: `# Tag an artifact version as latest
-flux tag artifact oci://ghcr.io/org/manifests/app:v0.0.1 --tag latest
+The command uses the credentials from '~/.docker/config.json'.`,
+	Example: `  # Tag an artifact version as latest
+  flux tag artifact oci://ghcr.io/org/manifests/app:v0.0.1 --tag latest
 `,
 	RunE: tagArtifactCmdRun,
 }