dorky

     __            __
 .--|  .-----.----|  |--.--.--.
 |  _  |  _  |   _|    <|  |  |
 |_____|_____|__| |__|__|___  |
                        |_____|

DevOps Records Keeper

&&

Overview

Manage sensitive project files like environment variables, configuration files, and API keys without committing them to public version control. dorky securely stores your sensitive files on AWS S3 or Google Drive, making them accessible to authorized team members.

Installation

npm install -g dorky

Or use with npx:

npx dorky --help

Prerequisites

AWS S3

Create an S3 bucket in your AWS account
Create an IAM user with programmatic access
Attach the following IAM policy to the user (replace your-bucket-name with your actual bucket name):

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "s3:PutObject",
                "s3:GetObject",
                "s3:DeleteObject",
                "s3:ListBucket"
            ],
            "Resource": [
                "arn:aws:s3:::your-bucket-name",
                "arn:aws:s3:::your-bucket-name/*"
            ]
        }
    ]
}

Generate AWS credentials (Access Key ID and Secret Access Key) for the IAM user
Set up environment variables:

export AWS_ACCESS_KEY="your-access-key"
export AWS_SECRET_KEY="your-secret-key"
export AWS_REGION="us-east-1"
export BUCKET_NAME="your-bucket-name"

Google Drive

Create a Google Cloud Project
Enable Google Drive API
Download OAuth 2.0 credentials
Save credentials as google-drive-credentials.json in your project root

Quick Start

AWS S3 Setup

# Navigate to your project
cd your-project

# Initialize dorky with AWS
dorky --init aws

# List files that can be added
dorky --list

# Add sensitive files
dorky --add .env config.yml

# Push to S3
dorky --push

Google Drive Setup

# Navigate to your project
cd your-project

# Initialize dorky with Google Drive
dorky --init google-drive

# Authenticate (browser window will open)
# Follow the OAuth flow

# List files that can be added
dorky --list

# Add sensitive files
dorky --add .env secrets.json

# Push to Google Drive
dorky --push

Usage

Initialize a Project (`-i`)

# For AWS S3
dorky --init aws

# For Google Drive
dorky --init google-drive

This creates:

.dorky/ folder with metadata and credentials
.dorkyignore file for exclusion patterns
Updates .gitignore to protect credentials

List Files (`-l`)

# List local files (shows what can be added)
dorky --list

# List remote files (shows what's in storage)
dorky --list remote

Add Files to Stage (`-a`)

# Add single file
dorky --add .env

# Add multiple files
dorky --add .env config.yml secrets.json

# Add files with specific patterns
dorky --add .env.production .env.staging

Remove Files from Stage (`-r`)

# Remove single file
dorky --rm .env

# Remove multiple files
dorky --rm .env config.yml

Push Files to Storage (`-ph`)

# Push all staged files
dorky --push

This command:

Uploads new files
Updates modified files (based on hash comparison)
Removes files from remote storage that were unstaged using dorky --rm
Skips unchanged files
Skips push entirely if the staged state already matches the latest commit

Pull Files from Storage (`-pl`)

# Pull all tracked files
dorky --pull

This command:

Downloads all tracked files from storage
Creates necessary directories
Overwrites local files

Show Push History (`-lg`)

dorky --log

Prints all past push commits in reverse chronological order, showing the commit ID, timestamp, and list of files included in each snapshot.

Checkout a Commit (`-co`)

# Restore files to a specific commit
dorky --checkout <commit-id>

Downloads the files as they were at the given commit from remote storage and stages them locally. Run dorky --push afterward to publish the restored state as a new commit. The commit ID can be found with --log. Prefix matching is supported (e.g. dorky --checkout a1b2 if the full ID is a1b2c3d4).

Destroy Project (`-d`)

# Destroy project locally and remotely
dorky --destroy

This command:

Deletes all tracked files from remote storage
Removes local .dorky/ directory and .dorkyignore file
Warning: This action is irreversible for remote files.

Configuration

.dorkyignore

Exclude files and directories from dorky scanning:

node_modules/
.git/
dist/
build/
*.log
coverage/

Directory Structure

After initialization:

your-project/
├── .dorky/
│   ├── credentials.json    # Storage credentials (auto-ignored by git)
│   ├── metadata.json       # Tracked files metadata
│   └── history.json        # Push commit history
├── .dorkyignore           # Exclusion patterns
└── .gitignore             # Updated automatically

Common Workflows

Workflow 1: Initial Setup for Team

# Team lead initializes and pushes files
dorky --init aws
dorky --add .env config/secrets.yml
dorky --push

# Team members pull files
git clone <repository>
cd <repository>
# Set up AWS credentials in environment
dorky --pull

Workflow 2: Update Sensitive Configuration

# Modify your .env file locally
vim .env

# Add updated file
dorky --add .env

# Push changes
dorky --push

Workflow 3: Clean Up Tracked Files

# Remove from staging
dorky --rm old-config.yml

# Push to remove from remote
dorky --push

Examples

Example 1: Managing Environment Files

# Initialize with AWS
dorky --init aws

# Add environment files for different stages
dorky --add .env.development .env.staging .env.production

# Check what will be uploaded
dorky --list

# Upload to S3
dorky --push

# View remote files
dorky --list remote

Example 2: Managing API Keys

# Initialize with Google Drive
dorky --init google-drive

# Add API key files
dorky --add config/api-keys.json secrets/tokens.yml

# Push to Google Drive
dorky --push

# On another machine, pull the files
dorky --pull

MCP Server (AI Agent Integration)

dorky ships a Model Context Protocol (MCP) server so AI coding assistants (Claude, Cursor, VS Code Copilot, etc.) can invoke dorky commands directly from within AI-assisted workflows.

Available MCP Tools

Tool	Description
`init`	Initialize a dorky project (`aws` or `google-drive`)
`list`	List local untracked/staged files or remote files
`add`	Stage files for upload
`remove`	Unstage files from tracking
`push`	Push staged files to remote storage
`pull`	Pull tracked files from remote storage
`log`	Show push history
`checkout`	Restore files from a history commit
`destroy`	Destroy the project locally and remotely

Running the MCP Server

npx dorky-mcp

Or, if installed globally:

dorky-mcp

Configuring MCP Clients

Claude Desktop

Add the following to your claude_desktop_config.json (usually at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS or %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
    "mcpServers": {
        "dorky": {
            "command": "npx",
            "args": ["dorky-mcp"],
            "env": {
                "AWS_ACCESS_KEY": "your-access-key",
                "AWS_SECRET_KEY": "your-secret-key",
                "AWS_REGION": "us-east-1",
                "BUCKET_NAME": "your-bucket-name"
            }
        }
    }
}

VS Code (GitHub Copilot)

Add to your VS Code settings.json:

{
    "mcp": {
        "servers": {
            "dorky": {
                "type": "stdio",
                "command": "npx",
                "args": ["dorky-mcp"],
                "env": {
                    "AWS_ACCESS_KEY": "your-access-key",
                    "AWS_SECRET_KEY": "your-secret-key",
                    "AWS_REGION": "us-east-1",
                    "BUCKET_NAME": "your-bucket-name"
                }
            }
        }
    }
}

Cursor

Add to your Cursor MCP config (.cursor/mcp.json in your project or ~/.cursor/mcp.json globally):

{
    "mcpServers": {
        "dorky": {
            "command": "npx",
            "args": ["dorky-mcp"],
            "env": {
                "AWS_ACCESS_KEY": "your-access-key",
                "AWS_SECRET_KEY": "your-secret-key",
                "AWS_REGION": "us-east-1",
                "BUCKET_NAME": "your-bucket-name"
            }
        }
    }
}

VS Code Extension

A graphical interface for dorky is available as a VS Code extension — manage staged and uploaded files directly from the sidebar without leaving your editor.

📦 dorky-extension on VS Code Marketplace
🐙 Extension source

Features

✅ AWS S3 storage integration
✅ Google Drive storage integration
✅ List remote files in dorky bucket
✅ Auto detect .env and .config files
✅ Automatic .gitignore updates to ignore credentials
✅ Handle reauthentication for Google Drive
✅ Token refresh for Google Drive authentication
✅ Ignore dorky files in dorky itself
✅ File hash validation to skip unchanged files
✅ Mime-type detection for file uploads
✅ Recursive folder creation on pull
✅ Destroy project and clean up remote files
✅ Auto-recovery of AWS credentials from environment variables
✅ Push history with versioned remote snapshots
✅ Restore files to any previous push commit
✅ MCP server for AI agent integration (Claude, Cursor, VS Code Copilot)

How It Works

Initialization: Creates .dorky/ folder with metadata, credentials, and history
File Tracking: Maintains a hash-based registry of files in metadata.json
Smart Uploads: Only uploads files that have changed (based on MD5 hash)
Auto-detection: Highlights .env and .config files during listing
Security: Automatically updates .gitignore to protect credentials
History: Each push saves a commit entry in history.json and uploads a versioned snapshot to <project>/.dorky-history/<commit-id>/ on remote storage, enabling point-in-time restore via --checkout

Security Best Practices

✅ Never commit .dorky/credentials.json to version control
✅ Use environment variables for AWS credentials
✅ Rotate access keys regularly
✅ Use IAM roles with minimal required permissions
✅ Review .dorkyignore before adding files
✅ Keep google-drive-credentials.json secure

Troubleshooting

AWS S3 Issues

Error: Missing credentials

# Set environment variables
export AWS_ACCESS_KEY="your-key"
export AWS_SECRET_KEY="your-secret"
export AWS_REGION="us-east-1"
export BUCKET_NAME="your-bucket"

Google Drive Issues

Error: Invalid credentials

# Re-authenticate
dorky --init google-drive

Error: Token expired

dorky automatically refreshes tokens
If issues persist, delete .dorky/credentials.json and re-authenticate

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

ISC License - see LICENSE file for details.

Name		Name	Last commit message	Last commit date
.dorky		.dorky
.github		.github
bin		bin
extension/dorky-extension		extension/dorky-extension
lib		lib
tests		tests
web-app		web-app
.c8rc.json		.c8rc.json
.dorkyignore		.dorkyignore
.gitignore		.gitignore
.mcp.json		.mcp.json
.npmignore		.npmignore
AGENTS.md		AGENTS.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
dorky-usage-aws.svg		dorky-usage-aws.svg
dorky-usage-google-drive.svg		dorky-usage-google-drive.svg
google-drive-credentials.json		google-drive-credentials.json
logo.svg		logo.svg
package-lock.json		package-lock.json
package.json		package.json
vitest.config.js		vitest.config.js

Latest commit

History

Folders and files

Repository files navigation

dorky

Overview

Installation

Prerequisites

AWS S3

Google Drive

Quick Start

AWS S3 Setup

Google Drive Setup

Usage

Initialize a Project (-i)

List Files (-l)

Add Files to Stage (-a)

Remove Files from Stage (-r)

Push Files to Storage (-ph)

Pull Files from Storage (-pl)

Show Push History (-lg)

Checkout a Commit (-co)

Destroy Project (-d)

Configuration

.dorkyignore

Directory Structure

Common Workflows

Workflow 1: Initial Setup for Team

Workflow 2: Update Sensitive Configuration

Workflow 3: Clean Up Tracked Files

Examples

Example 1: Managing Environment Files

Example 2: Managing API Keys

MCP Server (AI Agent Integration)

Available MCP Tools

Running the MCP Server

Configuring MCP Clients

Claude Desktop

VS Code (GitHub Copilot)

Cursor

VS Code Extension

Features

How It Works

Security Best Practices

Troubleshooting

AWS S3 Issues

Google Drive Issues

Contributing

License

Support

Roadmap

About

Resources

Code of conduct

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Initialize a Project (`-i`)

List Files (`-l`)

Add Files to Stage (`-a`)

Remove Files from Stage (`-r`)

Push Files to Storage (`-ph`)

Pull Files from Storage (`-pl`)

Show Push History (`-lg`)

Checkout a Commit (`-co`)

Destroy Project (`-d`)