All Your Base64

🚀 All Your Base64

A modern, efficient CLI utility to convert any input file into a base64 string with comprehensive output options.

🚀 Quick Start

All Your Base64 is a powerful CLI tool built with TypeScript. It can convert various input sources (files, stdin, strings) into base64 strings and offers multiple output formats. Here are some basic usage examples:

# Encode a file
ayb64 encode myfile.jpg

# Encode with wrapped output
ayb64 encode myfile.jpg --wrap 76

# Generate data URI
ayb64 encode image.png --data-uri

# Output to file with metadata
ayb64 encode document.pdf -o output.b64 --metadata

# Decode base64 back to file
ayb64 decode SGVsbG8sIFdvcmxkIQ== -o hello.txt

# Pipe from stdin
echo "Hello, World!" | ayb64 encode

# Get file information
ayb64 info myfile.jpg --json

✨ Features

• Modern & Fast: Built with TypeScript and optimized for performance.
• Smart Detection: Industry-leading MIME type detection via file-type + mime-types.
• Versatile Input: Supports files, stdin, and strings.
• Multiple Outputs: Offers raw, JSON, JS, TS, CSS, HTML, XML, YAML, Markdown output formats.
• Bidirectional: Supports both encoding and decoding.
• Robust: Comprehensive error handling and validation.
• Metadata: Provides file information, hashing, and processing stats.
• Data URIs: Can generate data URIs with proper MIME types.
• Cross-Platform: Works on macOS, Linux, Windows, Docker, and in the cloud.

📦 Installation

Global Installation (Recommended)

npm install -g ayb64

Local Installation

npm install ayb64

Using npx (No Installation)

npx ayb64 --help
# or use the shorter command
npx ayb64 --help

💻 Usage Examples

Basic Usage

ayb64 encode file.txt
# SGVsbG8sIFdvcmxkIQ==

Advanced Usage

Line Wrapping

ayb64 encode file.txt --wrap 64    # 64 characters per line
ayb64 encode file.txt --wrap 76    # RFC 2045 compliant

Processing Multiple Files

# Using shell globbing
for file in *.jpg; do
  ayb64 encode "$file" -o "${file}.b64"
done

# Using find
find . -name "*.png" -exec ayb64 encode {} -o {}.b64 \;

Piping and Redirection

# Pipe from curl
curl -s https://example.com/image.jpg | ayb64 encode --data-uri

# Chain operations
ayb64 encode file.txt | ayb64 decode -o restored.txt

# Use with other tools
base64 -d encoded.txt | ayb64 encode --format json

📚 Documentation

Commands

encode / e

Convert input to base64 format.

ayb64 encode [input] [options]

Arguments:

• input: Input file path (use - for stdin).

Options:

• -o, --output <path>: Output file path (default: stdout).
• -f, --format <format>: Output format: raw, json, js, ts, css, html, xml, yaml, md.
• -w, --wrap <columns>: Wrap base64 output at specified column width.
• -d, --data-uri: Generate data URI with MIME type.
• -m, --metadata: Include file metadata in output.
• --no-mime: Disable MIME type detection.
• --quiet: Suppress non-essential output.

decode / d

Decode base64 input back to original format.

ayb64 decode [input] [options]

Arguments:

• input: Input file path or base64 string (use - for stdin).

Options:

• -o, --output <path>: Output file path (default: stdout).
• -m, --metadata: Show metadata if available.
• --quiet: Suppress non-essential output.

info / i

Display file information and metadata without conversion.

ayb64 info <input> [options]

Arguments:

• input: Input file path.

Options:

• -j, --json: Output as JSON.

mcp

Start the Model Context Protocol server for AI agents.

ayb64 mcp

This command starts the MCP server which provides base64 conversion tools optimized for AI agents and coding workflows. The server includes memory, job recall, checksums, and specialized tools. No options: The MCP server runs as a standalone process communicating via stdio.

batch / b

Process multiple files in batch (coming soon).

ayb64 batch <pattern> [options]

Output Formats

Raw Format (default)

ayb64 encode file.txt
# SGVsbG8sIFdvcmxkIQ==

JSON Format

ayb64 encode file.txt --format json --metadata

{
  "data": "SGVsbG8sIFdvcmxkIQ==",
  "size": 22,
  "metadata": {
    "filename": "file.txt",
    "mimeType": "text/plain",
    "size": 13,
    "hash": "abc123...",
    "processingTime": 2
  }
}

JavaScript/TypeScript Module

ayb64 encode file.txt --format js --metadata

const base64Data = 'SGVsbG8sIFdvcmxkIQ==';

const metadata = {
  filename: 'file.txt',
  mimeType: 'text/plain',
  size: 13,
};

module.exports = { base64Data, metadata };

Data URI

ayb64 encode image.png --data-uri
# data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...

HTML Document

ayb64 encode file.txt --format html --metadata

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Base64 Data</title>
  </head>
  <body>
    <div class="base64-data" data-content="SGVsbG8sIFdvcmxkIQ=="></div>
    <div class="metadata">
      <h3>File Information</h3>
      <p><strong>Filename:</strong> file.txt</p>
      <p><strong>MIME Type:</strong> text/plain</p>
      <p><strong>Size:</strong> 13 bytes</p>
    </div>
  </body>
</html>

CSS Custom Properties

ayb64 encode file.txt --format css

.base64-data {
  --base64-content: 'SGVsbG8sIFdvcmxkIQ==';
}

.base64-data::before {
  content: var(--base64-content);
}

MCP Server for AI Agents

All Your Base64 includes a powerful Model Context Protocol (MCP) server optimized for AI agents and coding tasks.

MCP Server Features

• Smart Memory: LRU cache with job recall by ID.
• Change Detection: SHA256 checksums detect file modifications.
• AI Optimized: Tools designed for coding and development workflows.
• Job History: Track and recall previous encoding operations.
• Data URIs: Generate web-ready data URIs for images and assets.
• Performance: Lightweight, extensible, and robust.

MCP Server Tools

• encode: Encode files/data with format options and job tracking.
• decode: Decode base64 with auto-detection and file output.
• recall: Retrieve previous jobs by ID with full context.
• jobs: List recent operations with metadata.
• datauri: Generate data URIs optimized for web development.
• memory: Manage job cache (stats, clear).

Using the MCP Server

Start the MCP Server

# Using the CLI command (recommended)
ayb64 mcp

# Direct binary
ayb64-mcp

# Development mode
npm run mcp

# Or via npx with source
npx tsx src/mcp-server.ts

Configure in Your MCP Client

VS Code/Cursor/Cline (add to mcp.json):

{
  "mcpServers": {
    "ayb64": {
      "command": "ayb64",
      "args": ["mcp"]
    }
  }
}

Claude Desktop:

{
  "mcpServers": {
    "ayb64": {
      "command": "ayb64-mcp"
    }
  }
}

Example MCP Workflows

Encode an image for web use:

Tool: encode
Input: {
  "data": "/path/to/logo.png",
  "isFile": true,
  "format": "js",
  "dataUri": true
}
Output: Job ID + JavaScript const with data URI

Recall a previous job:

Tool: recall
Input: {"jobId": "job_1234567890_abc123"}
Output: Full original result with metadata

Generate data URI for CSS:

Tool: datauri
Input: {"input": "/path/to/background.jpg"}
Output: data:image/jpeg;base64,... (ready for CSS)

API Reference

File Information Output

When using --metadata, you'll get comprehensive file information:

{
  "filename": "example.jpg",
  "mimeType": "image/jpeg",
  "size": 153600,
  "created": "2023-01-01T00:00:00.000Z",
  "modified": "2023-01-02T00:00:00.000Z",
  "hash": "sha256:a1b2c3d4...",
  "processingTime": 15
}

Supported MIME Types

The tool automatically detects file types using the file-type package, supporting:

• Images: JPEG, PNG, GIF, WebP, SVG, BMP, TIFF, ICO.
• Documents: PDF, DOC, DOCX, XLS, XLSX, PPT, PPTX.
• Archives: ZIP, RAR, 7Z, TAR, GZIP, BZIP2.
• Media: MP4, AVI, MOV, MP3, WAV, OGG, FLAC.
• Text: Plain text, HTML, CSS, JavaScript, JSON, XML, YAML, Markdown.
• Fonts: TTF, OTF, WOFF, WOFF2, EOT.
• And many more...

🔧 Technical Details

Performance

Benchmarks

Benchmarks run on real hardware: MacBook Pro, 2.4 GHz 8 - Core Intel Core i9, 32GB DDR4, macOS 15.6.1

Performance Notes:

• Memory usage shows peak heap growth during encoding.
• Very memory-efficient base64 implementation.
• Processing time scales reasonably with file size.

Benchmarks run on real hardware using npm run benchmark

Optimization Tips

1. Use raw format for best performance.
2. Avoid metadata for simple conversions.
3. Use appropriate wrap settings for your use case.
4. Process files individually rather than in large batches.

Configuration

Environment Variables

• AYB64_MAX_MEMORY: Maximum memory usage threshold.
• AYB64_QUIET: Default quiet mode setting.

Config File

Create ~/.ayb64rc.json for default settings:

{
  "format": "raw",
  "wrap": 76,
  "metadata": false
}

Integration Examples

Node.js Scripts

const { spawn } = require('child_process');

function encodeFile(filePath) {
  return new Promise((resolve, reject) => {
    const child = spawn('ayb64', ['encode', filePath, '--format', 'json']);
    let output = '';

    child.stdout.on('data', (data) => {
      output += data.toString();
    });

    child.on('close', (code) => {
      if (code === 0) {
        resolve(JSON.parse(output));
      } else {
        reject(new Error(`Process exited with code ${code}`));
      }
    });
  });
}

Web Development

Generate data URIs for CSS:

ayb64 encode logo.png --data-uri > logo-data.css

Create JavaScript modules:

# Use shell globbing until batch command is implemented
for file in assets/*.png; do
  ayb64 encode "$file" --format js -o "${file%.png}.js"
done

CI/CD Pipelines

# GitHub Actions example
- name: Encode assets
  run: |
    for file in dist/assets/*; do
      ayb64 encode "$file" --format json --metadata > "$file.json"
    done

📄 License

MIT © Joe Peterson