Sarra CLI

Daily developer enhancement tools - A collection of CLI utilities for common development tasks including ID generation, cryptography, data formatting, QR code generation, time utilities, and SSL certificate management.

Installation

For CLI Usage (Global)

npm install -g sarra

Or use directly with npx:

npx sarra <command>

For App/Library Usage (Local)

npm install sarra

→ See SDK Documentation below for using Sarra in your Node.js/React applications.

Demo

Quick Start

# Generate a UUID
sarra id uuid

# Hash some data
sarra crypto hash sha256 "hello world"

# Format JSON
echo '{"a":1}' | sarra data json format

# Generate a QR code
sarra qr generate "Hello World"

# Get current timestamp
sarra time now

# Generate SSL certificate for local development
sarra ssl generate

Command Groups

id - Identifiers, tokens, UUIDs (detailed docs)
crypto - Cryptography utilities (detailed docs)
data - Data encoding and formatting (detailed docs)
qr - QR code generation (detailed docs)
time - Date and time utilities (detailed docs)
ssl - SSL certificate generation (detailed docs)
ssl - Geolocation and IP location utilities (detailed docs)

Use --help on any command for more details:

sarra --help
sarra id --help
sarra crypto --help
sarra qr --help
sarra ssl --help

`id` - Identifiers, Tokens, and UUIDs

Generate and manage identifiers, tokens, and unique values commonly used in databases, APIs, authentication, and distributed systems.

📚 View detailed documentation

Commands

uuid - Generate UUIDs (v4, v7)
random - Generate cryptographically secure random tokens

Quick Examples

# Generate UUID
sarra id uuid

# Generate UUID v7 (time-ordered, recommended for databases)
sarra id uuid --uuid-version v7 --count 5

# Generate random token
sarra id random --length 32

# Output to file
sarra id uuid --count 10 -o uuids.txt

# JSON format
sarra id --format json uuid --uuid-version v7 -o uuids.json

Interactive Mode

Commands will prompt before saving:

📁 Save Location
   Current directory: /home/user/projects
   Default file: uuids.txt
   Full path: /home/user/projects/uuids.txt

Save to file? (Y/n/path):

Press Enter or y → Save to default location
Type n → Output to stdout
Type a path → Save to custom location
Use -y flag to skip prompt and output to stdout
Use -o <file> flag to save directly without prompt

`crypto` - Cryptography Utilities

Cryptographic utilities for hashing, encoding, and encryption.

Commands

hash - Generate cryptographic hashes (md5, sha1, sha256, sha512)
base64 - Base64 encode or decode data
aes-encrypt - Encrypt data using AES-256-GCM
aes-decrypt - Decrypt AES-256-GCM encrypted data
rsa-keygen - Generate RSA key pair
rsa-encrypt - Encrypt data using RSA public key
rsa-decrypt - Decrypt data using RSA private key

Global Options

--format <format>    Output format: text | json

Examples

Hashing

# Generate hashes
sarra crypto hash sha256 "hello world"
sarra crypto hash sha512 "data"
echo "hello" | sarra crypto hash sha256

# JSON output
sarra crypto --format json hash sha256 "data"

Base64

# Encode and decode
sarra crypto base64 "hello world"
sarra crypto base64 --decode SGVsbG8gd29ybGQ=
echo "hello" | sarra crypto base64

AES Encryption

# Encrypt (auto-generates key)
sarra crypto aes-encrypt "secret message"

# Encrypt with custom key
sarra crypto aes-encrypt "message" -k <64-hex-chars>

# Decrypt (requires key, IV, auth tag)
sarra crypto aes-decrypt <encrypted-hex> -k <key> -i <iv> -t <tag>

# JSON format (saves all parameters)
sarra crypto --format json aes-encrypt "data" -o encrypted.json

RSA Keys

# Generate key pair
sarra crypto rsa-keygen
sarra crypto rsa-keygen --size 4096 -o ./my-keys

# Encrypt/Decrypt
sarra crypto rsa-encrypt "message" -p public_key.pem
sarra crypto rsa-decrypt <base64-data> -k private_key.pem

Output Options

# Interactive prompt (default)
sarra crypto hash sha256 "data"

# Output to stdout
sarra crypto hash sha256 "data" -y

# Save to file
sarra crypto hash sha256 "data" -o hash.txt
sarra crypto --format json aes-encrypt "data" -o encrypted.json

Supported Algorithms

Hash Algorithms:

md5 - 128-bit (not cryptographically secure)
sha1 - 160-bit (deprecated for security)
sha256 - 256-bit (recommended)
sha512 - 512-bit (maximum security)

Encryption:

AES-256-GCM - Authenticated symmetric encryption (256-bit key)
RSA-OAEP - Asymmetric encryption (2048/3072/4096-bit keys)

Command Reference

`hash`

sarra crypto hash <algorithm> [input] [options]

Options:
  -o, --out <file>    Write output to file
  -y, --yes           Output to stdout

`base64`

sarra crypto base64 [input] [options]

Options:
  -d, --decode        Decode instead of encode
  -o, --out <file>    Write output to file
  -y, --yes           Output to stdout

`aes-encrypt`

sarra crypto aes-encrypt [input] [options]

Options:
  -k, --key <key>     Encryption key (hex, 32 bytes)
  -o, --out <file>    Write output to file
  -y, --yes           Output to stdout

`aes-decrypt`

sarra crypto aes-decrypt [input] [options]

Options:
  -k, --key <key>     Decryption key (required)
  -i, --iv <iv>       Initialization vector (required)
  -t, --tag <tag>     Auth tag (required)
  -o, --out <file>    Write output to file
  -y, --yes           Output to stdout

`rsa-keygen`

sarra crypto rsa-keygen [options]

Options:
  -s, --size <bits>   Key size: 2048, 3072, 4096 (default: 2048)
  -o, --out <dir>     Output directory
  -y, --yes           Output to stdout

`rsa-encrypt`

sarra crypto rsa-encrypt [input] [options]

Options:
  -p, --public-key <file>    Public key file (required)
  -o, --out <file>           Write output to file
  -y, --yes                  Output to stdout

`rsa-decrypt`

sarra crypto rsa-decrypt [input] [options]

Options:
  -k, --private-key <file>   Private key file (required)
  -o, --out <file>           Write output to file
  -y, --yes                  Output to stdout

Security Notes

⚠️ AES: Save encryption keys securely - you cannot decrypt without them. Use JSON format to save all decryption parameters together.
🔒 RSA: Keep private keys secure and never share them. Use chmod 600 on private key files.
✓ Use SHA-256 or SHA-512 for cryptographically secure hashing.
✓ For large data, use RSA to encrypt an AES key, then use AES for the data.

`data` - Data Encoding and Formatting

JSON utilities for formatting, validating, querying, and transforming JSON data.

📚 View detailed documentation

Commands

format (pretty) - Pretty-print JSON with configurable indentation
minify (min) - Minify JSON by removing whitespace
validate (check) - Validate JSON syntax
query (get) - Extract values using dot notation path
merge - Merge multiple JSON files into one
to-csv - Convert JSON array to CSV format

Quick Examples

# Format JSON
sarra data json format data.json

# Format with custom indentation
sarra data json format data.json -i 4

# Minify JSON
sarra data json minify large.json -o min.json

# Validate JSON
sarra data json validate config.json

# Query/extract data
sarra data json query "user.name" data.json
sarra data json query "items[0].id" data.json

# Merge JSON files
sarra data json merge config1.json config2.json -o merged.json

# Convert to CSV
sarra data json to-csv users.json -o users.csv

# Pipe workflows
curl https://api.example.com/data | sarra data json format

`qr` - QR Code Generation

QR code generation utilities for creating scannable codes from text, URLs, and files.

📚 View detailed documentation

Commands

generate (gen) - Generate QR code from text
terminal (term) - Display QR code as ASCII art only (no file)
url - Generate QR code from a URL
file - Generate QR code from file content

Quick Examples

# Generate QR code
sarra qr generate "Hello World"

# Generate with terminal preview
sarra qr generate "Data" -t

# Quick ASCII preview (no file)
sarra qr terminal "Quick check"

# Generate from URL
sarra qr url https://github.com

# Generate from file
sarra qr file config.json

# Custom size and colors
sarra qr generate "Styled" -s 500 --dark '#FF0000' --light '#FFFF00'

# Save to file
sarra qr generate "Data" -o qrcode.png

# High error correction for damaged codes
sarra qr generate "Important" -e H -o code.png

Error Correction Levels

L - Low (7% recovery)
M - Medium (15% recovery) [default]
Q - Quartile (25% recovery)
H - High (30% recovery)

Size Recommendations

300px - Screen display, mobile sharing
400px - General purpose, web embedding
500-800px - Printing on paper, posters
1000px+ - Large format printing, banners

`time` - Date and Time Utilities

Date and time utilities for scripting, logging, and debugging.

📚 View detailed documentation

Commands

now - Print the current timestamp

Quick Examples

# Current timestamp (ISO 8601)
sarra time now

# Unix timestamp (seconds)
sarra time now --unix

# Unix timestamp (milliseconds)
sarra time now --ms

# Date only
sarra time now --format date

# Time only
sarra time now --format time

# Use in scripts
echo "Started at $(sarra time now)"

Output Formats

Default (ISO 8601): 2026-01-21T13:45:22.123Z
--unix: 1737468322
--ms: 1737468322123
--format date: 2026-01-21
--format time: 13:45:22.123

`ssl` - SSL Certificate Generation

SSL/TLS certificate generation for local development and production environments. Generate self-signed certificates instantly or obtain trusted certificates from Let's Encrypt.

📚 View detailed documentation

Commands

generate - Generate self-signed SSL certificates for local development
letsencrypt - Obtain trusted SSL certificates from Let's Encrypt for production

Quick Examples

# Generate self-signed certificate for localhost
sarra ssl generate

# Generate for custom local domain
sarra ssl generate --domain myapp.local

# Generate with custom validity period
sarra ssl generate --domain dev.example.com --validity 90

# Get Let's Encrypt certificate (standalone mode)
sarra ssl letsencrypt -d example.com -e admin@example.com --standalone

# Get Let's Encrypt certificate (with existing web server)
sarra ssl letsencrypt -d example.com -e admin@example.com --webroot /var/www/html

# Test Let's Encrypt setup first
sarra ssl letsencrypt -d example.com -e admin@example.com --standalone --staging

When to Use Each Command

ssl generate - Self-Signed Certificates

✅ Local development (https://localhost)
✅ Internal testing environments
✅ Development teams (share certificate)
❌ NOT for production websites
❌ NOT for public applications

ssl letsencrypt - Let's Encrypt Certificates

✅ Production websites
✅ Public-facing applications
✅ Any service requiring browser trust
❌ NOT for localhost development
❌ NOT for offline environments

Certificate Specifications (Self-Signed)

Key Algorithm: RSA 2048-bit
Signature Algorithm: SHA-256
Validity: Up to 365 days
Output: .crt and .key files in PEM format

Prerequisites for Let's Encrypt

Certbot installed:
- macOS: brew install certbot
- Ubuntu: sudo apt install certbot
- Windows: Download from https://certbot.eff.org
Domain ownership:
- Real domain (not localhost or .local)
- DNS points to your server's IP
- Verify: dig +short example.com
Network access:
- Port 80 open and accessible
- Firewall allows incoming connections

Making Self-Signed Certificates Trusted

To eliminate browser warnings during local development:

macOS:

sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain ./certs/localhost.crt

Windows (as Administrator):

certutil -addstore -f "ROOT" ./certs/localhost.crt

Linux:

sudo cp ./certs/localhost.crt /usr/local/share/ca-certificates/
sudo update-ca-certificates

Note: This only trusts the certificate on your machine. Other users will still see warnings.

Interactive Mode

Most commands support an interactive mode that prompts you before saving files:

📁 Save Location
   Current directory: /home/user/projects
   Default file: output.txt
   Full path: /home/user/projects/output.txt

Save to file? (Y/n/path):

Your options:

Press Enter or type y → Save to default location
Type n → Output to stdout (terminal)
Type a custom path → Save to specified location

Skip the prompt:

Use -y flag to output directly to stdout
Use -o <file> flag to save directly to a file

Examples:

# Interactive (will prompt)
sarra id uuid --count 5

# Skip prompt, output to stdout
sarra id uuid --count 5 -y

# Skip prompt, save to file
sarra id uuid --count 5 -o uuids.txt

# Custom nested path (auto-creates directories)
sarra qr generate "Data" -o ./output/qrcodes/code.png

Common Patterns

Piping and Workflows

# API response to formatted JSON
curl https://api.example.com/data | sarra data json format

# Hash pipeline
echo "data" | sarra crypto base64 | sarra crypto hash sha256

# Format then minify
sarra data json format ugly.json | sarra data json minify -o min.json

# Validate before processing
sarra data json validate data.json && sarra data json query "users" data.json

File Output

# Direct file output
sarra id uuid --count 100 -o uuids.txt
sarra crypto hash sha256 "data" -o hash.txt
sarra qr generate "https://example.com" -o qr.png
sarra ssl generate --domain myapp.local

# Nested directories (auto-created)
sarra id random --length 32 -o ./secrets/tokens/api-key.txt
sarra data json format data.json -o ./output/formatted/data.json

JSON Format Output

# Global format flag (before subcommand)
sarra id --format json uuid --count 5
sarra crypto --format json hash sha256 "data"

# Save JSON output
sarra id --format json uuid -o uuids.json
sarra crypto --format json base64 "data" -o encoded.json

Geolocation and IP Utilities

IP address and geolocation utilities for network information. Commands

my-ip - Get your current public IP address
lookup - Get geolocation information for an IP address
validate - Validate an IP address (IPv4 or IPv6)
local - Get local network interface information

Examples

Get your public IP

sarra geo my-ip

Get IPv4 only

sarra geo my-ip --ipv4

Lookup IP geolocation

sarra geo lookup 8.8.8.8

Lookup your own IP info

sarra geo lookup

Validate IP addresses

sarra geo validate 192.168.1.1
sarra geo validate 2001:0db8:85a3:0000:0000:8a2e:0370:7334

Show local network interfaces

sarra geo local

JSON output

sarra geo --format json my-ip
sarra geo --format json lookup 1.1.1.1

Options:

  -4, --ipv4    Show only IPv4 address
  -6, --ipv6    Show only IPv6 address

Arguments: ip IP address to validate

Notes

my-ip and lookup commands require internet connection
lookup uses ipapi.co free API (rate limited to 1000 requests/day)
validate and local work offline
Local command skips loopback interfaces
All commands support --format json for programmatic usage

Tips

Use --help on any command for detailed information
Use --version to see the current version
Global options like --format must appear before the subcommand
Many commands support reading from stdin for pipeline operations
Directories are automatically created when using -o/--out
Use -y flag to skip interactive prompts and output to stdout
Use -o flag to save directly to a file without prompts
SSL certificates are zero-dependency - no OpenSSL installation required

Documentation

Detailed documentation for each command group:

Examples by Use Case

Development

# Generate API key
sarra id random --length 32 -o api-key.txt

# Hash password
echo "mypassword" | sarra crypto hash sha256

# Format API response
curl https://api.example.com/users | sarra data json format

# Setup local HTTPS development
sarra ssl generate --domain localhost

Configuration

# Merge configs
sarra data json merge base.json env.json local.json -o config.json

# Validate config
sarra data json validate config.json

# Extract specific config
sarra data json query "database.host" config.json

QR Codes

# WiFi QR code
sarra qr generate "WIFI:T:WPA;S:MyNetwork;P:password;;" -o wifi.png

# URL sharing
sarra qr url https://myapp.com -s 500 -o share.png

# Contact info
sarra qr generate "BEGIN:VCARD..." -e H -o contact.png

Data Processing

# Extract users and convert to CSV
sarra data json query "users" data.json | sarra data json to-csv -o users.csv

# Format then validate
sarra data json format raw.json | sarra data json validate

SSL/TLS Setup

# Local development environment
sarra ssl generate --domain localhost
sarra ssl generate --domain myapp.local --validity 180

# Production website deployment
sarra ssl letsencrypt -d example.com -e admin@example.com --standalone

# Multiple environments
sarra ssl generate --domain dev.myapp.local
sarra ssl generate --domain staging.myapp.local
sarra ssl letsencrypt -d myapp.com -e ops@myapp.com --webroot /var/www/html

DevOps & CI/CD

# Generate unique deployment IDs
sarra id uuid --uuid-version v7 -y

# Hash artifact checksums
cat build.zip | sarra crypto hash sha256 -o checksum.txt

# Validate configuration files
sarra data json validate config.json && deploy.sh

# Generate QR codes for mobile app testing
sarra qr url "https://testflight.apple.com/join/abc123" -o testflight.png

# Timestamp build logs
echo "Build started: $(sarra time now)" >> build.log

Security Notes

Self-Signed Certificates

⚠️ Only for development - browsers will show warnings
⚠️ Not trusted by default - requires manual installation
⚠️ Never use in production - visitors will see security errors

Let's Encrypt Certificates

✅ Automatically trusted by all browsers and devices
✅ Free and automated - renews every 90 days
✅ Production-ready - industry-standard security
⚠️ Requires domain ownership - cannot be used for localhost
⚠️ Rate limited - 50 certificates per domain per week

Best Practices

Use ssl generate for local development
Test Let's Encrypt with --staging flag first
Never commit .key files to version control
Rotate certificates regularly
Keep certbot updated for security patches

Troubleshooting

SSL Certificate Issues

"Certbot not found"

Install certbot: brew install certbot (macOS) or sudo apt install certbot (Linux)

"Let's Encrypt doesn't work with localhost"

Use sarra ssl generate for local development instead

"Domain must point to this server's IP"

Verify DNS: dig +short example.com should show your server's IP

"Port 80 must be accessible"

Check firewall rules: sudo ufw status
Ensure no other service is using port 80

Other Common Issues

"Command not found"

Reinstall globally: npm install -g sarra
Check PATH: echo $PATH

"Permission denied" when saving files

Use sudo for system directories
Save to user-writable locations instead

JSON validation fails

Check for trailing commas
Verify quote types (must use double quotes)
Use sarra data json format to auto-fix formatting

SDK

Use Sarra's powerful utilities in your Node.js and React applications.

Usage

Import

// Import the entire SDK
import { sarra } from "sarra";

// Or import specific modules
import { id, crypto, geo } from "sarra";

API Reference

ID Generation

Generate UUIDs and cryptographically secure random tokens.

`sarra.id.uuid(options)`

Generate UUIDs (v4 or v7).

interface UUIDOptions {
  version?: "v4" | "v7"; // Default: 'v4'
  count?: number; // Default: 1
}

interface UUIDResult {
  version: string;
  uuids: string[];
}

Examples:

// Generate single UUID v4
const result = sarra.id.uuid();
console.log(result.uuids[0]); // 'f47ac10b-58cc-4372-a567-0e02b2c3d479'

// Generate 5 UUID v4s
const result = sarra.id.uuid({ count: 5 });
console.log(result.uuids); // Array of 5 UUIDs

// Generate UUID v7 (time-ordered)
const result = sarra.id.uuid({ version: "v7", count: 3 });
console.log(result.uuids); // Array of 3 time-ordered UUIDs

`sarra.id.random(options)`

Generate cryptographically secure random tokens.

interface RandomTokenOptions {
  length?: number; // Byte length, default: 16
  count?: number; // Default: 1
}

interface RandomTokenResult {
  tokens: string[];
  count: number;
  length: number;
  encoding: "hex";
}

Examples:

// Generate 16-byte token (32 hex characters)
const result = sarra.id.random();
console.log(result.tokens[0]); // '4f3d2e1c0b9a8f7e6d5c4b3a2f1e0d9c'

// Generate 32-byte token (64 hex characters)
const result = sarra.id.random({ length: 32 });
console.log(result.tokens[0]); // 64-character hex string

// Generate multiple tokens
const result = sarra.id.random({ length: 16, count: 5 });
console.log(result.tokens); // Array of 5 tokens

Cryptography

Hash, encode, encrypt, and decrypt data.

`sarra.crypto.hash(options)`

Generate cryptographic hashes.

interface HashOptions {
  algorithm: "md5" | "sha1" | "sha256" | "sha512";
  input: string;
}

Examples:

// SHA-256 hash
const hash = sarra.crypto.hash({
  algorithm: "sha256",
  input: "hello world",
});
console.log(hash); // 'b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9'

// MD5 hash
const md5 = sarra.crypto.hash({
  algorithm: "md5",
  input: "secret",
});

`sarra.crypto.base64(options)`

Base64 encode or decode strings.

interface Base64Options {
  input: string;
  decode?: boolean; // Default: false
}

Examples:

// Encode
const encoded = sarra.crypto.base64({ input: "hello world" });
console.log(encoded); // 'aGVsbG8gd29ybGQ='

// Decode
const decoded = sarra.crypto.base64({
  input: "aGVsbG8gd29ybGQ=",
  decode: true,
});
console.log(decoded); // 'hello world'

`sarra.crypto.aesEncrypt(options)`

Encrypt data using AES-256-GCM.

interface AESEncryptOptions {
  input: string;
  key?: string; // Optional 64-char hex string
}

interface AESEncryptResult {
  encrypted: string;
  iv: string;
  authTag: string;
  key: string;
}

Examples:

// Encrypt with auto-generated key
const result = sarra.crypto.aesEncrypt({
  input: "secret message",
});

console.log(result.encrypted); // Encrypted data (hex)
console.log(result.key); // 64-char hex key
console.log(result.iv); // 32-char hex IV
console.log(result.authTag); // 32-char hex auth tag

// Encrypt with custom key
const result = sarra.crypto.aesEncrypt({
  input: "secret message",
  key: "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
});

`sarra.crypto.aesDecrypt(options)`

Decrypt AES-256-GCM encrypted data.

interface AESDecryptOptions {
  encrypted: string;
  key: string;
  iv: string;
  authTag: string;
}

Examples:

// Decrypt data
const decrypted = sarra.crypto.aesDecrypt({
  encrypted: result.encrypted,
  key: result.key,
  iv: result.iv,
  authTag: result.authTag,
});

console.log(decrypted); // 'secret message'

`sarra.crypto.rsaKeygen(options)`

Generate RSA key pair.

interface RSAKeygenOptions {
  size?: 2048 | 3072 | 4096; // Default: 2048
}

interface RSAKeygenResult {
  publicKey: string; // PEM format
  privateKey: string; // PEM format
}

Examples:

// Generate 2048-bit key pair
const keys = sarra.crypto.rsaKeygen();
console.log(keys.publicKey); // '-----BEGIN PUBLIC KEY-----...'
console.log(keys.privateKey); // '-----BEGIN PRIVATE KEY-----...'

// Generate 4096-bit key pair
const keys = sarra.crypto.rsaKeygen({ size: 4096 });

`sarra.crypto.rsaEncrypt(options)`

Encrypt data using RSA public key.

interface RSAEncryptOptions {
  input: string;
  publicKey: string; // PEM format
}

Examples:

const keys = sarra.crypto.rsaKeygen();

const encrypted = sarra.crypto.rsaEncrypt({
  input: "secret message",
  publicKey: keys.publicKey,
});

console.log(encrypted); // Base64-encoded encrypted data

`sarra.crypto.rsaDecrypt(options)`

Decrypt data using RSA private key.

interface RSADecryptOptions {
  encrypted: string; // Base64 format
  privateKey: string; // PEM format
}

Examples:

const decrypted = sarra.crypto.rsaDecrypt({
  encrypted: encrypted,
  privateKey: keys.privateKey,
});

console.log(decrypted); // 'secret message'

Geolocation & IP

Get IP addresses, validate IPs, and lookup geolocation data.

`sarra.geo.myIp(ipv6?)`

Get your public IP address.

interface IpInfo {
  ip: string;
}

Examples:

// Get IPv4 address
const result = await sarra.geo.myIp();
console.log(result.ip); // '203.0.113.42'

// Get IPv6 address
const result = await sarra.geo.myIp(true);
console.log(result.ip); // '2001:0db8:85a3::8a2e:0370:7334'

`sarra.geo.lookup(ip?)`

Get geolocation information for an IP address.

interface GeolocationData {
  ip: string;
  city?: string;
  region?: string;
  country_name?: string;
  country_code?: string;
  timezone?: string;
  org?: string;
  postal?: string;
  latitude?: number;
  longitude?: number;
}

Examples:

// Lookup specific IP
const data = await sarra.geo.lookup("8.8.8.8");
console.log(data.city); // 'Mountain View'
console.log(data.country_name); // 'United States'
console.log(data.org); // 'Google LLC'

// Lookup your own IP
const data = await sarra.geo.lookup();
console.log(data.city, data.country_name);

`sarra.geo.validate(ip)`

Validate an IP address (IPv4 or IPv6).

interface IpValidation {
  ip: string;
  valid: boolean;
  type: "IPv4" | "IPv6" | null;
}

Examples:

// Validate IPv4
const result = sarra.geo.validate("192.168.1.1");
console.log(result.valid); // true
console.log(result.type); // 'IPv4'

// Validate IPv6
const result = sarra.geo.validate("2001:0db8:85a3::8a2e:0370:7334");
console.log(result.valid); // true
console.log(result.type); // 'IPv6'

// Invalid IP
const result = sarra.geo.validate("999.999.999.999");
console.log(result.valid); // false
console.log(result.type); // null

React Examples

UUID Generator Component

import { useState } from "react";
import { sarra } from "sarra";

function UUIDGenerator() {
  const [uuids, setUuids] = useState<string[]>([]);

  const generateUUIDs = () => {
    const result = sarra.id.uuid({ version: "v4", count: 5 });
    setUuids(result.uuids);
  };

  return (
    <div>
      <button onClick={generateUUIDs}>Generate UUIDs</button>
      <ul>
        {uuids.map((uuid) => (
          <li key={uuid}>{uuid}</li>
        ))}
      </ul>
    </div>
  );
}

Hash Generator

import { useState } from "react";
import { sarra } from "sarra";

function HashGenerator() {
  const [input, setInput] = useState("");
  const [hash, setHash] = useState("");

  const generateHash = () => {
    const result = sarra.crypto.hash({
      algorithm: "sha256",
      input,
    });
    setHash(result);
  };

  return (
    <div>
      <input
        value={input}
        onChange={(e) => setInput(e.target.value)}
        placeholder="Enter text to hash"
      />
      <button onClick={generateHash}>Generate SHA-256</button>
      {hash && <code>{hash}</code>}
    </div>
  );
}

IP Lookup Component

import { useState } from "react";
import { sarra } from "sarra";

function IPLookup() {
  const [ip, setIp] = useState("");
  const [data, setData] = useState(null);
  const [loading, setLoading] = useState(false);

  const lookup = async () => {
    setLoading(true);
    try {
      const result = await sarra.geo.lookup(ip || undefined);
      setData(result);
    } catch (error) {
      console.error("Lookup failed:", error);
    } finally {
      setLoading(false);
    }
  };

  return (
    <div>
      <input
        value={ip}
        onChange={(e) => setIp(e.target.value)}
        placeholder="Enter IP (or leave empty for your IP)"
      />
      <button onClick={lookup} disabled={loading}>
        {loading ? "Looking up..." : "Lookup"}
      </button>

      {data && (
        <div>
          <p>IP: {data.ip}</p>
          <p>City: {data.city}</p>
          <p>Country: {data.country_name}</p>
          <p>ISP: {data.org}</p>
        </div>
      )}
    </div>
  );
}

Encryption Example

import { useState } from "react";
import { sarra } from "sarra";

function Encryptor() {
  const [message, setMessage] = useState("");
  const [encrypted, setEncrypted] = useState(null);
  const [decrypted, setDecrypted] = useState("");

  const encrypt = () => {
    const result = sarra.crypto.aesEncrypt({ input: message });
    setEncrypted(result);
  };

  const decrypt = () => {
    if (!encrypted) return;
    const result = sarra.crypto.aesDecrypt({
      encrypted: encrypted.encrypted,
      key: encrypted.key,
      iv: encrypted.iv,
      authTag: encrypted.authTag,
    });
    setDecrypted(result);
  };

  return (
    <div>
      <input
        value={message}
        onChange={(e) => setMessage(e.target.value)}
        placeholder="Enter message"
      />
      <button onClick={encrypt}>Encrypt</button>

      {encrypted && (
        <>
          <div>
            <p>Encrypted: {encrypted.encrypted.slice(0, 50)}...</p>
            <p>Key: {encrypted.key.slice(0, 20)}...</p>
          </div>
          <button onClick={decrypt}>Decrypt</button>
          {decrypted && <p>Decrypted: {decrypted}</p>}
        </>
      )}
    </div>
  );
}

TypeScript Support

Sarra is written in TypeScript and includes full type definitions.

import { sarra, UUIDOptions, GeolocationData } from "sarra";

const options: UUIDOptions = {
  version: "v4",
  count: 5,
};

const result = sarra.id.uuid(options);

const data: GeolocationData = await sarra.geo.lookup("8.8.8.8");

Notes

Crypto Module

All cryptographic operations use Node.js built-in crypto module
AES keys must be exactly 32 bytes (64 hexadecimal characters)
RSA is suitable for encrypting small amounts of data
For large files, use RSA to encrypt an AES key, then use AES for the data

Geo Module

myIp() and lookup() require internet connection
lookup() uses ipapi.co free tier (rate limited to 1000 requests/day)
validate() works offline (no API calls)
All API calls use HTTPS for secure communication

License

See the LICENSE file for details.

Changelog

See CHANGELOG for version history and updates.

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

Contributors

_{Simeon Jordanov}

Roadmap

Planned features for future releases:

📊 More data format conversions (YAML, TOML, XML)
🌐 DNS utilities and domain validation
🔑 SSH key generation and management
📦 Archive utilities (zip, tar)
🎨 Image processing and optimization
🔍 File search and text processing

Name		Name	Last commit message	Last commit date
Latest commit History 44 Commits
.github/workflows		.github/workflows
dist		dist
docs		docs
src		src
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README-VHS.md		README-VHS.md
README.md		README.md
demo.gif		demo.gif
demo.mp4		demo.mp4
package-lock.json		package-lock.json
package.json		package.json
sarra-cli-demo.tape		sarra-cli-demo.tape
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

Sarra CLI

Installation

For CLI Usage (Global)

For App/Library Usage (Local)

Demo

Quick Start

Command Groups

id - Identifiers, Tokens, and UUIDs

Commands

Quick Examples

Interactive Mode

crypto - Cryptography Utilities

Commands

Global Options

Examples

Hashing

Base64

AES Encryption

RSA Keys

Output Options

Supported Algorithms

Command Reference

hash

base64

aes-encrypt

aes-decrypt

rsa-keygen

rsa-encrypt

rsa-decrypt

Security Notes

data - Data Encoding and Formatting

Commands

Quick Examples

qr - QR Code Generation

Commands

Quick Examples

Error Correction Levels

Size Recommendations

time - Date and Time Utilities

Commands

Quick Examples

Output Formats

ssl - SSL Certificate Generation

Commands

Quick Examples

When to Use Each Command

Certificate Specifications (Self-Signed)

Prerequisites for Let's Encrypt

Making Self-Signed Certificates Trusted

Interactive Mode

Common Patterns

Piping and Workflows

File Output

JSON Format Output

Geolocation and IP Utilities

Examples

Get your public IP

Get IPv4 only

Lookup IP geolocation

Lookup your own IP info

Validate IP addresses

Show local network interfaces

JSON output

Notes

Tips

Documentation

Examples by Use Case

Development

Configuration

QR Codes

Data Processing

SSL/TLS Setup

DevOps & CI/CD

Security Notes

Self-Signed Certificates

Let's Encrypt Certificates

`id` - Identifiers, Tokens, and UUIDs

`crypto` - Cryptography Utilities

`hash`

`base64`

`aes-encrypt`

`aes-decrypt`

`rsa-keygen`

`rsa-encrypt`

`rsa-decrypt`

`data` - Data Encoding and Formatting

`qr` - QR Code Generation

`time` - Date and Time Utilities

`ssl` - SSL Certificate Generation

`sarra.id.uuid(options)`

`sarra.id.random(options)`

`sarra.crypto.hash(options)`

`sarra.crypto.base64(options)`

`sarra.crypto.aesEncrypt(options)`

`sarra.crypto.aesDecrypt(options)`

`sarra.crypto.rsaKeygen(options)`

`sarra.crypto.rsaEncrypt(options)`

`sarra.crypto.rsaDecrypt(options)`

`sarra.geo.myIp(ipv6?)`

`sarra.geo.lookup(ip?)`

`sarra.geo.validate(ip)`

Packages