Print full usage on missing required flags; support IMMICH_DIR

Bare "required flag(s) ... not set" with no usage text wasn't
actionable. Required-flag checking now happens in PreRunE, which
prints cmd.UsageString() before returning the error; runtime errors
from RunE (network failures, sync errors) stay terse as before.

--dir now also reads from IMMICH_DIR, matching --url/--api-key's
IMMICH_URL/IMMICH_API_KEY pattern. Also fixed a malformed 4-column
row in the README flags table.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Author: jochbru

README.md

@@ -9,8 +9,11 @@ Immich-go-style sidecar JSON carrying the full original asset metadata.
 ```sh
 export IMMICH_URL=https://photos.example.com
 export IMMICH_API_KEY=your-user-api-key
+export IMMICH_DIR=/path/to/archive
 
-immich-archiver --dir /path/to/archive  # --dir is required
+immich-archiver
+# or, without env vars:
+immich-archiver --url https://photos.example.com --api-key your-user-api-key --dir /path/to/archive
 ```
 
 On a second run, assets already present on disk (verified by filename + a matching asset ID in
@@ -34,9 +37,9 @@ Live Photos are downloaded as a still + a paired motion video sharing the same b
 
 | Flag | Default | Description |
 |---|---|---|
-| `--url` | `$IMMICH_URL` | Immich server URL |
-| `--api-key` | `$IMMICH_API_KEY` | Immich user API key |
-| `--dir` | *(required)* | destination root directory |
+| `--url` | *(required)* | Immich server URL (env `IMMICH_URL`) |
+| `--api-key` | *(required)* | Immich user API key (env `IMMICH_API_KEY`) |
+| `--dir` | *(required)* | destination root directory (env `IMMICH_DIR`) |
 | `--path-template` | `{year}/{year}-{month}` | folder structure template |
 | `--include-shared` | `false` | also mirror assets from albums shared with you |
 | `--shared-dir` | `<dir>/shared-with-me` | destination root for shared assets |

cmd/root.go

@@ -4,6 +4,7 @@ import (
 	"context"
 	"fmt"
 	"os"
+	"strings"
 	"time"
 
 	"github.com/pixelunioneu/immich-archiver/internal/archive"
@@ -42,14 +43,17 @@ func newRootCmd() *cobra.Command {
 		Version:       version,
 		SilenceUsage:  true,
 		SilenceErrors: true,
+		PreRunE: func(cmd *cobra.Command, args []string) error {
+			return validateFlags(cmd, f)
+		},
 		RunE: func(cmd *cobra.Command, args []string) error {
 			return runSync(cmd, f)
 		},
 	}
 
 	cmd.Flags().StringVar(&f.url, "url", os.Getenv("IMMICH_URL"), "Immich server URL (env IMMICH_URL)")
 	cmd.Flags().StringVar(&f.apiKey, "api-key", os.Getenv("IMMICH_API_KEY"), "Immich user API key (env IMMICH_API_KEY)")
-	cmd.Flags().StringVar(&f.dir, "dir", "", "destination root directory (required)")
+	cmd.Flags().StringVar(&f.dir, "dir", os.Getenv("IMMICH_DIR"), "destination root directory (required, env IMMICH_DIR)")
 	cmd.Flags().StringVar(&f.pathTemplate, "path-template", archive.DefaultPathTemplate, "folder structure template; supports {year}, {month}, {day}")
 	cmd.Flags().BoolVar(&f.includeShared, "include-shared", false, "also mirror assets shared with you into a separate folder")
 	cmd.Flags().StringVar(&f.sharedDir, "shared-dir", "", "destination root for shared assets (default: <dir>/shared-with-me)")
@@ -59,21 +63,31 @@ func newRootCmd() *cobra.Command {
 	cmd.Flags().BoolVar(&f.dryRun, "dry-run", false, "list what would be downloaded without writing anything")
 	cmd.Flags().BoolVarP(&f.verbose, "verbose", "v", false, "log a line per asset instead of showing a progress bar")
 
-	if err := cmd.MarkFlagRequired("dir"); err != nil {
-		panic(err)
-	}
-
 	return cmd
 }
 
-func runSync(cmd *cobra.Command, f *flags) error {
+// validateFlags checks required inputs before RunE. Failures print the full
+// usage/help text (unlike runtime errors from RunE, which stay terse) so a
+// missing/misspelled flag is immediately actionable.
+func validateFlags(cmd *cobra.Command, f *flags) error {
+	var missing []string
+	if f.dir == "" {
+		missing = append(missing, "--dir (or IMMICH_DIR)")
+	}
 	if f.url == "" {
-		return fmt.Errorf("an Immich server URL is required: pass --url or set IMMICH_URL")
+		missing = append(missing, "--url (or IMMICH_URL)")
 	}
 	if f.apiKey == "" {
-		return fmt.Errorf("an Immich API key is required: pass --api-key or set IMMICH_API_KEY")
+		missing = append(missing, "--api-key (or IMMICH_API_KEY)")
+	}
+	if len(missing) == 0 {
+		return nil
 	}
+	_, _ = fmt.Fprintln(cmd.OutOrStderr(), cmd.UsageString())
+	return fmt.Errorf("missing required flag(s): %s", strings.Join(missing, ", "))
+}
 
+func runSync(cmd *cobra.Command, f *flags) error {
 	client := immich.NewClient(f.url, f.apiKey)
 	client.Retries = f.retries