Raptor

Raptor is a cross-platform CLI application for managing your secrets in a fast and smart way.
It lets you encrypt and decrypt files or folders and manage encrypted boxes (JSON-based containers) where you can safely store credentials, tokens, and other sensitive data.

Raptor is designed to be simple, portable, and secure — working on macOS, Linux, and Windows.

---

• Installing Raptor
  • From Source (for Linux and Mac users)
  • macOS / Linux
  • Optional dependencies (Linux clipboard)
  • Windows (PowerShell)
  • Uninstall on macOS/Linux
  • Uninstall on Windows
  • Troubleshooting
• Command Reference
• Typical Workflow
• Usage Examples
  • Encrypt a File
  • Decrypt a File
  • Create a Box
  • Add a Secret to a Box
  • Generate a Random Password
  • List Secrets in a Box
  • Get a Secret and Copy to Clipboard
  • Edit a Secret
• Environment Variables
• How It Works
• Development
• Contributing
• License

Installing Raptor

From Source (for Linux and Mac users)

You need Go 1.21 or later.

git clone https://github.com/your/repo.git
cd raptor
make build

This will produce a binary raptor in the project folder.

macOS / Linux

Use the installer script to download the latest release for your OS/CPU and place the binary on your PATH.

# macOS or Linux
curl -fsSL https://raw.githubusercontent.com/mas2020-golang/raptor/main/install.sh | bash

This script:

• Detects your OS/architecture
• Downloads the latest release
• Installs raptor into a standard location (e.g., /usr/local/bin or ~/.local/bin)
• Makes it executable

Verify

raptor version
raptor help

Optional dependencies (Linux clipboard)

On Linux, clipboard features (copying secrets directly) require one of these utilities:

• xclip
• xsel

Install them via your package manager if you want clipboard integration.

Windows (PowerShell)

Remove-Item "$env:LOCALAPPDATA\Programs\raptor\raptor.exe" -Force
iwr -UseBasicParsing https://raw.githubusercontent.com/mas2020-golang/raptor/main/install.ps1 | iex

Uninstall on macOS/Linux

Remove the binary (adjust the path if needed):

sudo rm -f /usr/local/bin/raptor
# or, if installed to ~/.local/bin
rm -f ~/.local/bin/raptor

If you have any box installed, remove it:

rm -rf $HOME/.cryptex/boxes

Uninstall on Windows

Remove the binary (adjust the path if needed):

• delete %LOCALAPPDATA%\Programs\raptor\raptor.exe
• optionally remove %LOCALAPPDATA%\Programs\raptor from your User PATH.

Troubleshooting

• raptor: command not found Ensure the install location is on your PATH. Common paths:
  • macOS (Intel/Apple Silicon): /usr/local/bin or /opt/homebrew/bin
  • Linux: /usr/local/bin or ~/.local/bin
• Clipboard flags don’t copy on Linux Install xclip or xsel (see “Optional dependencies”).

---

Command Reference

Command	Description
raptor encrypt FILE	Encrypt a file
raptor decrypt FILE.enc	Decrypt a file
raptor create box --name NAME	Create a new box
raptor create secret --box NAME --name KEY	Add a secret to a box
raptor create password [--length N]	Generate a random password
raptor list box	List all existing boxes
raptor list secret --box NAME	List secrets in a box
raptor get secret --box NAME --name KEY	Retrieve a secret (optionally copy to clipboard)
raptor edit secret --box NAME --name KEY	Edit a secret in the default editor
raptor print secret NAME --box NAME	Print all secrets in a box
raptor open NAME	Open a box and keep it active until timeout
raptor version	Show Raptor version info

Run raptor help <command> for full details on options.

---

Typical Workflow

Here’s a quick journey through Raptor’s main features:

1. Encrypt a file you want to protect

   raptor encrypt secrets.env

2. Create a box to organize secrets

   raptor create box my-box

3. Add secrets into the box

   raptor create secret --box my-box DB_PASSWORD
   raptor create secret --box my-box EMAIL_PASSWORD

4. List the secrets in your box

   raptor list secret --box my-box

5. Retrieve a secret safely

   raptor get secret --box my-box API_KEY

6. Edit or update a secret when it changes

   raptor edit secret --box my-box DB_PASSWORD

7. Print or open a box when you need to work interactively

   raptor open my-box

This flow covers the most common tasks: protecting files, creating secure containers, and handling credentials.

---

Usage Examples

Encrypt a File

raptor encrypt secrets.env

Decrypt a File

raptor decrypt secrets.env.enc

Create a Box

raptor create box my-box

Add a Secret to a Box

raptor create secret --box my-box API_KEY

Generate a Random Password

raptor create password --length 16

List Secrets in a Box

raptor list secret --box my-box
raptor secret ls --box test --name '^secret.*test$

Get a Secret and Copy to Clipboard

raptor get secret --box my-box API_KEY

Edit a Secret

raptor edit secret --box my-box API_KEY

---

Environment Variables

Raptor behavior can be customized with environment variables:

• CRYPTEX_FOLDER
  Folder where Raptor stores boxes.
  Default: $HOME/.cryptex/boxes

• CRYPTEX_BOX
  Default box to use if --box is not provided.

• RAPTOR_LOGLEVEL
  Logging level: debug, info, warn, error
  Default: error

• RAPTOR_TIMEOUT_SEC
  Timeout in seconds of inactivity before Raptor exits.
  Default: 600 (10 minutes)

---

How It Works

• Encryption: Files and boxes are encrypted using strong, authenticated encryption. Each box is a JSON file stored in encrypted form.
• Secrets: Inside a box, secrets are stored as key-value pairs. You can add, edit, list, and remove them without exposing other secrets.
• Passphrases: Boxes are protected by passphrases. Raptor derives keys from passphrases securely (using a memory-hard KDF).
• Clipboard integration: Secrets can be copied directly to clipboard, reducing accidental leaks in terminals.

---

Development

To build:

make build

To run tests:

make test

Lint and vet:

go vet ./...
golangci-lint run

---

Contributing

Contributions are welcome!

• Open issues for bugs or feature requests.
• Submit PRs with tests and docs updated.

---

License

See LICENSE.