helps

cmd/log.go

@@ -19,10 +19,10 @@ var (
 func init() {
 	RootCmd.AddCommand(logCmd)
 
-	logCmd.Flags().BoolVar(&oneline, "oneline", false, "Show each commit on a single line")
-	logCmd.Flags().BoolVar(&noColor, "no-color", false, "Disable color output")
-	logCmd.Flags().BoolVar(&ignoreEmpty, "ignore-empty", false, "Ignore empty repositories")
-	logCmd.Flags().IntVarP(&maxCount, "max-count", "n", 0, "Limit the number of commits shown per repo (0 means no limit)")
+	logCmd.Flags().BoolVar(&oneline, "oneline", false, "show each commit on a single line")
+	logCmd.Flags().BoolVar(&noColor, "no-color", false, "disable color output")
+	logCmd.Flags().BoolVar(&ignoreEmpty, "ignore-empty", false, "ignore empty repositories")
+	logCmd.Flags().IntVarP(&maxCount, "max-count", "n", 0, "limit the number of commits shown per repo (0 means no limit)")
 }
 
 var logCmd = &cobra.Command{

cmd/root.go

@@ -40,6 +40,13 @@ func initEnvs() {
 var RootCmd = &cobra.Command{
 	Use:   "align [flags]",
 	Short: "Tool for managing git repos together",
+	Long: `align fans out git operations across every git repository in the current directory.
+
+Each sub-command mirrors its git equivalent and runs it against all repos found in the working directory.
+
+Use --verbose (-v) when scripting or using align with AI tools. Verbose mode replaces the
+interactive progress bars with structured per-repo output written to stdout, which is easier
+to parse and redirect.`,
 	PersistentPreRunE: func(cmd *cobra.Command, args []string) error {
 		if _, err := exec.LookPath("git"); err != nil {
 			return fmt.Errorf("git is not installed or not on PATH — it is required for align to function")

cmd/stash/stash.go

@@ -21,6 +21,7 @@ var StashCmd = &cobra.Command{
 	Use:              "stash",
 	Short:            "Stash changes across all repos in a directory",
 	Long:             "Stash uncommitted changes across all repos in a directory.",
+	Args:             cobra.NoArgs,
 	PersistentPreRun: setupClient,
 	RunE:             stashFunc,
 }

cmd/tag.go

@@ -32,9 +32,12 @@ func init() {
 }
 
 var tagCmd = &cobra.Command{
-	Use:               "tag",
-	Short:             "Create, list, or delete tags across all repos in a directory",
-	Long:              `Create, list, or delete tags across all repos in a directory.`,
+	Use:   "tag [<tagname>]",
+	Short: "Create, list, or delete tags across all repos in a directory",
+	Long: `Create, list, or delete tags across all repos in a directory.
+
+When called with no arguments, lists all tags in each repo (equivalent to --list).
+Provide a tag name to create a tag in each repo that has a matching branch or ref.`,
 	ValidArgsFunction: tagCmdValidArgsFunc,
 	PersistentPreRun:  setupClient,
 	RunE:              tagFunc,