@mydatagit/cli (mdgit)

Git-like, end-to-end encrypted synchronization and version control for sensitive project state that Git deliberately ignores.

Manage .env files, API keys, SSL certificates, credentials, and private configs with full cryptographic version history, multi-environment branching (dev, staging, prod), and 3-way conflict resolution—without ever sending plaintext secrets to any cloud server.

⚡ The Problem MyDataGit Solves

1. The .gitignore Dilemma: Sensitive environment files (.env, *.key, *.pem) must be excluded from Git to prevent leaks, forcing teams into dangerous manual sharing via Slack, Email, or stale copy-pasting.
2. Accidental Leaks: One mistaken git add . or bad commit can leak production API keys and database credentials into public or team Git history forever.
3. Environment Drift: Teammates work on different or outdated versions of environment variables, leading to broken builds and production outages.

MyDataGit treats secrets like code: versioned, branched, diffed, and synchronized—backed by strict client-side authenticated encryption (AES-256-GCM + HMAC-SHA256).

🔒 Security Invariants

Local Plaintext Files (.env, certs/, secrets/)
                    ↓
Client-Side AES-256-GCM Encrypted (96-bit fresh nonces)
HMAC-SHA256 Content Fingerprint (bound to PDK generation)
                    ↓
Opaque Ciphertext Payload
                    ↓
Cloudflare D1 (Metadata & RBAC) + Backblaze B2 (Encrypted Object Blobs)

• Zero-Plaintext Server Rule: Plaintext file contents, Project Data Keys (PDKs), and 24-word Recovery Key mnemonics never leave your device.
• X25519 ECIES Device Key Grants: Team members request access with their local device public keys. Project Owners/Admins approve requests by re-wrapping the PDK client-side.
• BIP-39 24-Word Disaster Recovery: A 24-word recovery phrase restores project access on fresh hardware even if all active devices are destroyed.
• Zero-Knowledge Secret Masking: Diff and comparison tools mask secret contents (.env, *.key, *.pem) by default.
• Snapshot CAS Concurrency Protection: Snapshot compare-and-swap prevents accidental overwrites (409 TARGET_MOVED / VERSION_CONFLICT).

📦 Installation & Updating

Install Globally

# Using npm
npm install -g @mydatagit/cli

# Using pnpm
pnpm add -g @mydatagit/cli

# Using yarn
yarn global add @mydatagit/cli

How to Update to the Latest Version

Keep your CLI updated with the latest cryptographic optimizations and features:

# Update with npm
npm install -g @mydatagit/cli@latest
# or
npm update -g @mydatagit/cli

# Update with pnpm
pnpm update -g @mydatagit/cli

# Verify installed CLI
mdgit --help

Or run directly without permanent installation via npx:

npx @mydatagit/cli <command>

🚀 Quickstart Walkthrough (4 Commands)

# 1. Sign up & create cryptographic device identity
mdgit auth signup --email [email protected] --password "StrongPassword123!"

# 2. Initialize tracking & specify secret files in .include
cd /path/to/my-project
mdgit init
echo ".env" >> .include

# 3. Create cloud vault (saves your 24-word recovery phrase)
mdgit project create my-app-vault

# 4. Encrypt and push ciphertext
mdgit push

🛠️ Complete CLI Command Reference

1. Authentication Commands (mdgit auth)

Manage your account credentials and local X25519 / Ed25519 cryptographic device key pair.

mdgit auth signup

Register a new MyDataGit account and initialize your local cryptographic device identity:

mdgit auth signup --email <email> --password <password> [--device-name <name>]

Options:

• --email (required): Account email address.
• --password (required): Account password (12+ characters, Argon2id memory-hardened).
• --device-name (optional): Friendly device name (e.g. MacBook-Pro, Work-Desktop).
• --profile (optional): Profile name (defaults to default).

mdgit auth login

Authenticate an existing account on this device and link your local device identity:

mdgit auth login --email <email> --password <password> [--device-name <name>]

mdgit auth token

Authenticate headless environments (CI/CD, Docker, scripts) using a Personal Access Token (PAT):

mdgit auth token --token <pat-token> [--device-name <name>]

mdgit auth status

Display the currently signed-in account, active profile, device ID, and server connection status:

mdgit auth status [--profile <name>]

mdgit auth logout

Revoke the local device session and remove stored access tokens:

mdgit auth logout [--profile <name>]

mdgit auth tokens

Manage Personal Access Tokens (PATs) for CI/CD and automation:

# List active PATs
mdgit auth tokens list

# Create a new scoped PAT (shown once)
mdgit auth tokens create "github-actions-deploy" [--expires-at <timestamp>]

# Revoke a PAT
mdgit auth tokens revoke <token-id>

2. Workspace & Tracking Commands (mdgit init, mdgit status)

mdgit init

Initialize a local MyDataGit workspace inside the current directory. Creates the .mydatagit/ metadata folder and generates a default .include allowlist file:

mdgit init

mdgit status

Inspect the status of tracked secret files, compare local files against the remote branch HEAD, and view unpushed modifications or deletions:

mdgit status

3. The .include Allowlist Specification

Unlike traditional Git which tracks everything by default and relies on .gitignore as a blocklist, MyDataGit uses an explicit, declarative allowlist in .include. Only files matching rules in .include are parsed and encrypted.

.include Syntax Example:

# Shared files tracked across ALL branches
[global]
docs/context.md
secrets/shared-keys.json
certs/

# Development branch secrets
[branch:dev]
type: development
.env
.env.local

# Staging branch secrets
[branch:staging]
type: staging
.env.staging

# Production branch secrets (guarded by promotion CAS)
[branch:prod]
type: production
.env.prod
certs/prod-private.key

.include Rules:

• POSIX Paths Only: Always use forward slashes / (e.g. secrets/api.json), even on Windows.
• Directory Recursion: Listing a folder (e.g. certs/ or config/) automatically crawls and tracks all nested files.
• Project Relative: Paths must be inside the project root. Absolute paths (/etc/..., C:\...) and traversal escapes (../) are strictly rejected.
• Protected Directories: .git and .mydatagit are permanently excluded.

4. Push & Pull Synchronization (mdgit push, mdgit pull)

mdgit push

Encrypts tracked files with the active Project Data Key (PDK) using AES-256-GCM (with fresh 96-bit nonces) and uploads ciphertext blobs to Backblaze B2 object storage:

mdgit push

If a file was removed from .include, mdgit push automatically pushes a tombstone record to remove it on teammates' machines while preserving historical version decryption.

mdgit pull

Downloads encrypted ciphertext blobs from remote storage, decrypts them client-side using your device's PDK grant, and updates local workspace files using 3-way merge logic:

mdgit pull

5. Project Vault & Disaster Recovery (mdgit project, mdgit clone)

mdgit project create

Create a new encrypted remote project vault. Generates and displays your 24-word BIP-39 Recovery Phrase:

mdgit project create <project-name>

⚠️ CRITICAL: Store the 24-word recovery phrase securely. It is displayed exactly once and cannot be recovered by the server.

mdgit project list

List all remote project vaults you own or are a member of, along with your role and project IDs:

mdgit project list

mdgit project clone (or mdgit clone)

Clone an existing project vault to a local directory:

mdgit project clone <project-name-or-id> [target-directory]
# or
mdgit clone <project-name-or-id> [target-directory]

mdgit project recover

Recover full decryption capability on a new or unapproved device using your 24-word recovery mnemonic:

mdgit project recover <project-name-or-id> "<24-word recovery phrase>"

mdgit project rotate-recovery-key

Rotate the 24-word recovery key for a project (Owner only):

mdgit project rotate-recovery-key <project-name-or-id>

mdgit remote add

Link an existing local initialized directory to a remote project:

mdgit remote add origin <project-id> [--profile <name>]

6. Team Collaboration & Device Approvals (mdgit device)

When joining a project from a new machine, your device generates a unique X25519 key pair and requests authorization.

mdgit device list (or mdgit device list-requests)

List pending device authorization requests awaiting Owner/Admin cryptographic approval:

mdgit device list [project-id]

mdgit device approve

Cryptographically approve a pending device request (unwraps the active PDK and re-wraps it for the requester's device public key):

mdgit device approve <request-id> [project-id]

mdgit device deny

Deny a pending device authorization request:

mdgit device deny <request-id> [project-id]

7. Environment Branching & Promotion (mdgit branch)

Manage multi-environment secrets (dev, staging, prod) and promote verified configs with compare-and-set (CAS) protection.

mdgit branch list

List all branches in the project and their environment types:

mdgit branch list

mdgit branch create

Create a new branch with an environment classification:

mdgit branch create <branch-name> [--type <development|staging|production>]

mdgit branch switch

Switch the active local workspace branch:

mdgit branch switch <branch-name>

mdgit branch compare

Compare file additions, modifications, and deletions between two branches (secret values are masked by default):

mdgit branch compare <source-branch> <target-branch>

mdgit branch promote

Promote verified changes from a source branch (e.g. dev) to a target branch (e.g. prod). Enforces target snapshot CAS verification (--yes required for production):

mdgit branch promote <source-branch> <target-branch> [--yes]

mdgit branch delete

Delete an empty, non-production branch:

mdgit branch delete <branch-name>

8. 3-Way Merge Conflict Resolution (mdgit resolve)

mdgit resolve

When remote and local changes conflict during mdgit pull, resolve the conflict markers:

# Keep local modifications
mdgit resolve <file-path> --choice local

# Accept remote modifications
mdgit resolve <file-path> --choice remote

9. Global Configuration (mdgit config)

Configure CLI defaults stored globally in ~/.mydatagit/config.json.

# Set a custom API Gateway URL
mdgit config set api-url https://mydatagit-api.vinothfootball123.workers.dev

# Read a configuration setting
mdgit config get api-url

# List all global configuration settings
mdgit config list

📋 Release Notes

v0.1.6

• Complete CLI Reference & Update Guides: Added comprehensive command references, flags, and update instructions to README and npm docs.
• Robust Multi-Platform Clone: mdgit clone <name|id> automatically creates parent directories recursively and supports lookup by name or ULID.
• Backblaze B2 Native Storage Engine: Cloudflare Worker API now uploads and downloads ciphertext payloads directly to Backblaze B2 storage with cached authorization.
• Web UI & Console Gateway: Connected login, signup, and project dashboard to live Cloudflare Worker gateway with cross-origin cookie session support.
• .include Allowlist Enhancements: Full support for [global], [branch:<name>], type: <env>, and recursive directory tracking.

💡 Best Practices

1. Commit .include to Git: Commit your .include file into Git so your team knows which secrets and config files are managed by MyDataGit.
2. Never Commit Plaintext Secrets: Always keep .env, .env.*, *.pem, *.key inside .gitignore.
3. Store Recovery Key Securely: Store your 24-word recovery phrase in an encrypted password manager or offline safe.
4. CI/CD Service Accounts: Use Service Account tokens scoped strictly to required branches (e.g. prod only).

📄 License

Distributed under the Apache-2.0 / MIT License.