gHashIDs

ghashids is a fast, lightweight Go command-line interface (CLI) that mimics the behavior of the popular PHP/Laravel package vinkla/hashids. It generates short, unique, non-sequential, and URL-safe IDs (like YouTube's hash IDs) from one or more non-negative integers.

It is designed to be fully configurable via flags, environment variables, local directory config files, or user home directory config files.

---

Features

• Encode & Decode: Effortlessly hash one or multiple non-negative integers and decode them back.
• Vinkla/Hashids Compatible: Uses the exact same underlying Hashids algorithm, ensuring full compatibility with existing hashes.
• Short Command Aliases: e / enc for encode, and d / dec for decode.
• Robust Configuration Resolution Hierarchy:
  1. CLI Flags (-s, -l, -a, -c)
  2. Environment Variables (GHASHIDS_SALT, GHASHID_SALT, etc.)
  3. Explicit Configuration File (passed via -c/--config)
  4. Local Directory Config (./.ghashids.yaml or other extensions)
  5. Global Home Config (~/.ghashids/config.yaml, ~/.config/ghashids/config.yaml, or ~/.ghashids.yaml)
  6. Library Defaults (Empty salt, min-length 0, default alphabet)

---

Installation

1. Prerequisite: Go Installed

If you have Go installed on your system, install ghashids globally:

go install github.com/adnanex/ghashids@latest

Alternatively, build locally from the source:

# Clone the repository and navigate inside
make build
# Binary 'ghashids' is created locally

2. Prerequisite: No Go Installed (Using Docker)

If you do not have Go installed on your system, you can build and run ghashids using Docker (see Docker Usage).

---

Usage Examples

Encoding IDs

Encode one or multiple integers into a hash ID string:

# Using full command name
ghashids encode 1 2 3 --salt "my-salt" --min-length 8
# Output: j2T2hg6a

# Using short command alias and short flags
ghashids e 1 2 3 -s "my-salt" -l 8
# Output: j2T2hg6a

Decoding IDs

Decode a generated hash ID string back into its original space-separated integers:

# Using full command name
ghashids decode j2T2hg6a --salt "my-salt" --min-length 8
# Output: 1 2 3

# Using short command alias and short flags
ghashids d j2T2hg6a -s "my-salt" -l 8
# Output: 1 2 3

---

Configuration

ghashids resolves three main parameters:

• Salt: The secret key to obfuscate the hashes.
• Min Length: The minimum length of the generated hash.
• Alphabet: The characters used to construct the hash.

1. Environment Variables

You can configure the tool using environment variables prefixed with either GHASHIDS_ or GHASHID_:

export GHASHIDS_SALT="my-env-salt"
export GHASHIDS_MIN_LENGTH=10
export GHASHIDS_ALPHABET="abcdefghijklmnopqrstuvwxyz1234567890"

# Now run without flags:
ghashids e 42
# Output: w70mrl1op9

2. Configuration Files

The application supports YAML, JSON, TOML, and env files. It checks the following file paths in order of priority:

1. ./.ghashids.yaml (Local folder)
2. ~/.ghashids/config.yaml (Global configuration folder)
3. ~/.config/ghashids/config.yaml (XDG config style)
4. ~/.ghashids.yaml (Home directory root file)

(You can also use .yml, .json, .toml, or .env extensions).

Example config.yaml:

salt: "my-secret-salt"
min_length: 8
alphabet: "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890"

Example .env:

salt=my-secret-salt
min_length=8
alphabet=abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890

To run with a custom config file path explicitly:

ghashids e 99 -c /path/to/custom/config.json

---

Docker Usage

If you don't have Go installed, you can build and run everything in a Docker container.

1. Build the Docker Image

docker build -t ghashids .
# Or using make:
make docker-build
# Or using task:
task docker:build

2. Run the CLI

Provide arguments directly to the container:

docker run --rm ghashids e 1 2 3 --salt "my-salt"
# Output: jlxomslckx

3. Using Configuration Files inside Docker

To use a local config file (e.g. .ghashids.yaml in your host directory) inside the container, mount your current working directory:

# Mount current directory to /app and run
docker run --rm -v $(pwd):/app -w /app ghashids e 1 2 3

4. Using Environment Variables in Docker

Pass env variables via the -e flag:

docker run --rm -e GHASHIDS_SALT="docker-salt" ghashids e 42

5. Compile and Install Natively to Host (Run Natively without Go Installed)

Since Go compiles self-contained static binaries, you can build the application inside a Docker container and copy the resulting executable directly onto your host system's global /usr/local/bin/ folder.

Option A: Using Makefile

make docker-install
# Compiles inside Docker, installs to /usr/local/bin/ghashids (asks for sudo password), and cleans up

Option B: Using Taskfile

task docker:install
# Compiles inside Docker, installs to /usr/local/bin/ghashids (asks for sudo password), and cleans up

Option C: Extract and Move Manually If you want to copy the binary locally first and move/install it manually:

# 1. Build and copy out the binary locally:
make extract-binary   # or 'task docker:extract'

# 2. Make it executable and move it to your path
chmod +x ./bin/ghashids
sudo mv ./bin/ghashids /usr/local/bin/ghashids

Once installed, you can run it natively from anywhere on your host machine:

ghashids e 1 2 3 -s "my-salt"
# Output: jlxomslckx

---

Developer Commands

If you have Go and tools like make or task installed:

Using Makefile:

• make build: Compile the binary locally.
• make test: Run all unit tests.
• make install: Install the binary to your global GOBIN path.
• make clean: Clean local build output.
• make docker-build: Build Docker image.

Using Taskfile:

• task build: Build local binary.
• task test: Run tests.
• task install: Install binary globally.
• task docker:build: Build Docker image.
• task docker:run -- e 1 2 3: Run CLI inside Docker with arguments.

---

License

This project is open-sourced under the MIT License. Feel free to use, modify, and distribute it.