Overview

Version 1.1.0 · AES-256-GCM · PBKDF2-HMAC-SHA256 (600k)

Gecko is a portable CLI vault for securely storing files and notes. This page documents all commands and advanced features including time-based access controls, file versioning, keyfile 2FA, search, import/export, backup, merge, and compact.

Table of Contents Installation Basics File Operations Time-Based Access File Versioning Notes Search Import / Export Backup Merge Compact Keyfile 2FA Steganography Emergency Wipe Audit Logging

Installation

Windows

Download installer or portable EXE from Releases.

Linux

tar -xzf gecko-linux-x64.tar.gz
sudo mv gecko /usr/local/bin/

Build from source

git clone https://github.com/kpawnd/gecko.git
cd gecko
cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build

Basics

Create Vault

gecko create -v vault.gko -p <password>

Open / Info

gecko info -v vault.gko -p <password>

Verify

gecko verify -v vault.gko -p <password>

Change Password

gecko passwd -v vault.gko -p <old> -n <new>

File Operations

Add

gecko add -v vault.gko -p <pw> -f file.txt -n file.txt

List

gecko ls -v vault.gko -p <pw>

Get

gecko get -v vault.gko -p <pw> -n file.txt -o out.txt

Remove

gecko rm -v vault.gko -p <pw> -n file.txt

Cat

gecko cat -v vault.gko -p <pw> -n file.txt

Time-Based Access Controls

Add with Expiration

gecko add-expire vault.gko name file.txt 24

Add file with 24-hour expiration.

Auto-Delete on Expiry

gecko add-expire vault.gko name file.txt 168 --auto-delete

Add file with 1-week expiration and automatic deletion.

Check Expiration

gecko info vault.gko

Shows expiry times for all entries.

Files can be set to automatically expire after a specified number of hours. Use --auto-delete to automatically remove expired files from the vault.

File Versioning

List Versions

gecko versions vault.gko name

Show all versions of a file with timestamps.

Restore Version

gecko restore vault.gko name 2

Restore specific version (overwrites current).

Restore to File

gecko restore vault.gko name 1 restored.txt

Restore version to a new file.

Gecko maintains version history for files. Each time a file is added with the same name, a new version is created. Use versioning to recover previous versions of files.

Notes

Add Note

gecko note -v vault.gko -p <pw> -n mynote -t "content"

Read Note

gecko read -v vault.gko -p <pw> -n mynote

Search

Pattern Match

gecko search -v vault.gko -p <pw> -q "*.pdf"

Import / Export

Import Directory

gecko import -v vault.gko -p <pw> -d ./docs -x "*"

Export Vault

gecko export -v vault.gko -p <pw> -d ./out

Backup

Timestamped Backup

gecko backup -v vault.gko -p <pw> -d ./backups

Merge

Password-only Vaults

gecko merge -v main.gko -p <pw> -o other.gko -op <otherpw>

Keyfile Vaults 2FA

gecko merge -v main.gko -p <pw> -k main.key -o other.gko -op <otherpw> --ok other.key

Compact

Reclaim Space

gecko compact -v vault.gko -p <pw>

Keyfile 2FA

Generate Keyfile

gecko keygen -o vault.key

Create with Keyfile

gecko create -v vault.gko -p <pw> -k vault.key

Use Keyfile

gecko add/get/ls -v vault.gko -p <pw> -k vault.key ...

Steganography

Hide Data

gecko hide -i cover.bmp -s secret.txt -o steg.bmp

Extract Data

gecko unhide -i steg.bmp -o extracted.txt

Emergency Wipe

Destroy Vault

gecko shred -v vault.gko

Secure multi-pass overwrite followed by deletion.

Audit Logging

Enable + Log

gecko info -v vault.gko -p <pw> --audit ./audit/log.txt

Records operations and events for forensics.

For API usage (embedding Gecko as a library), see headers in include/gecko/*.h.