stashd

stashd

stashd is a simple CLI tool for creating timestamped ZIP archives of directories. This easy-to-use CLI makes setting up CRON jobs for automated backups trivial. The tool has no external dependencies, is lightweight, and is free and open source software under the MIT license.

Installation

To install stashd, clone the repository and build it:

git clone https://github.com/morpheuszero/stashd.git
cd stashd
go build -o stashd

Or install directly using Go:

go install github.com/morpheuszero/stashd@latest

Usage

Command Syntax

stashd [--verbose] <SOURCE_DIR> <OUTPUT_DIR>

Parameters

• SOURCE_DIR (required): The directory to archive. All regular files within this directory and its subdirectories will be included in the ZIP archive.
• OUTPUT_DIR (required): The directory where the ZIP archive will be created. This directory must already exist.
• --verbose (optional): When specified, prints the relative path of each file as it is added to the archive. Must be the first argument if used.

Output Format

Archives are created with the following filename format:

YYYY-MM-DD_UNIXMILLIS.zip

For example: 2026-01-24_1737715200000.zip

What Gets Archived

• Included: All regular files in the source directory and its subdirectories
• Excluded: Directories (structure is preserved, but empty directories are not included), symbolic links, and other special file types

Examples

Archive a directory:

stashd /path/to/directory /output/path

Archive a directory with verbose output:

stashd --verbose /path/to/directory /output/path

Exit Codes

• 0: Success - archive created successfully
• 1: Error - invalid arguments, directory not found, or archive creation failed

Setting up Automated Backups with CRON

Create a CRON job to run daily backups:

0 2 * * * /usr/local/bin/stashd /images /backups

This will run a backup every day at 2:00 AM, archiving /images to /backups.