.TH S3-GENINDEX 1 "December 2025" "s3-genindex 1.0.0" "User Commands"
.SH NAME
s3-genindex \- Generate HTML directory indexes for local directories and S3 storage
.SH SYNOPSIS
.B s3-genindex
[\fIOPTIONS\fR]
.SH DESCRIPTION
.B s3-genindex
generates HTML directory indexes with file type icons and responsive design for local directories and S3-compatible storage. This is particularly useful for S3 buckets that are publicly readable.

The tool creates hierarchical directory structures with responsive HTML pages that include file type icons, sorting capabilities, and optional watermark branding.

By default, recursive processing is enabled, hidden files are included, and the output file is named 'index.html' with directory href appending enabled.

.SH OPTIONS
.TP
.BR \-d " \fIDIRECTORY\fR"
Process local directory. Mutually exclusive with \-s3.

.TP
.BR \-s3 " \fIURL\fR"
Process S3-compatible storage. URL format: http://host:port/bucket or https://host/bucket.
Mutually exclusive with \-d.

.TP
.BR \-f " \fIGLOB\fR"
Only include files matching glob pattern (default: "*").
Example: "*.py" to include only Python files.

.TP
.BR \-n
Dry run mode. Show what would be written without actually creating files.

.TP
.BR \-x " \fIREGEX\fR"
Exclude files matching regular expression pattern.

.TP
.BR \-v
Verbose mode. List every processed file during operation.

.TP
.BR \-i
Show index.html files in directory listings (normally hidden).

.TP
.BR \-wm " \fIURL\fR"
Watermark logo URL to display in top left corner of generated pages.

.TP
.BR \-\-version
Show version information and exit.

.SH ENVIRONMENT
For S3 operations, the following environment variables must be set:

.TP
.B AWS_ACCESS_KEY_ID
S3 access key ID for authentication.

.TP
.B AWS_SECRET_ACCESS_KEY
S3 secret access key for authentication.

.SH EXAMPLES
.TP
Process a local directory:
.B s3-genindex -d /var/www/html

.TP
Process an S3 bucket with verbose output:
.B s3-genindex -v -s3 http://minio.example.com:9000/my-bucket

.TP
Dry run with file filtering:
.B s3-genindex -n -f "*.log" -d /var/log

.TP
S3 processing with watermark and filtering:
.B s3-genindex -v -f "*.jpg" -wm https://example.com/logo.svg -s3 https://s3.amazonaws.com/photos

.TP
Show version information:
.B s3-genindex --version

.SH FILES
.TP
.B index.html
Default output filename for generated directory indexes.

.SH EXIT STATUS
.TP
.B 0
Success
.TP
.B 1
Error (invalid arguments, missing credentials, file system errors, etc.)

.SH FEATURES
.IP \(bu 2
Local directory indexing with recursive traversal
.IP \(bu 2
S3-compatible storage support (MinIO, AWS S3, etc.)
.IP \(bu 2
Hierarchical directory structure for S3 buckets
.IP \(bu 2
Responsive HTML design with file type icons
.IP \(bu 2
Dry run mode for testing
.IP \(bu 2
Flexible filtering with glob patterns and regex exclusion
.IP \(bu 2
Hidden file control and index.html visibility options
.IP \(bu 2
Watermark support for branding

.SH SEE ALSO
.BR ls (1),
.BR find (1),
.BR tree (1)

.SH AUTHOR
Pim van Pelt <pim@ipng.ch>

.SH COPYRIGHT
Copyright \(co 2025 Pim van Pelt. Licensed under the APACHE-2.0 License.