CLI DOCUMENTATION • v0.1.8

MyDataGit CLI Reference

mdgit is the command-line client for MyDataGit — a Git-like, end-to-end encrypted version control and synchronization system for .env files, API keys, certificates, and private configs.

All file content is encrypted on your local machine using AES-256-GCM (with a fresh 96-bit nonce per operation) and identified with an HMAC-SHA256 hash before any byte is transmitted to Cloudflare D1 and Backblaze B2.

The Zero-Plaintext Invariant Cloudflare Workers and Backblaze B2 only handle encrypted ciphertext blobs, wrapped keys, and version metadata. Plaintext secrets, Project Data Keys (PDKs), and BIP-39 recovery mnemonics never leave your device.

Installation & Setup

Install the CLI globally from npm, or run commands directly with npx:

Global Installation

$ npm install -g @mydatagit/cli

Installs the latest stable version of mdgit globally on your system.

Expected Output

+ @mydatagit/cli@0.1.8
added 1 package in 2.1s

Verify Installation

$ mdgit --help

Prints the CLI overview and available command groups.

Expected Output

MyDataGit — Git-like, end-to-end encrypted sync for project state.

Usage: mdgit <command>

Commands:
  auth       Sign in / manage CLI device session
  init       Create a local project (no server involved)
  status     Show local tracked state
  push       Push encrypted state to the remote
  pull       Pull and decrypt remote state
  project    Create / list / clone remote projects
  remote     Link this project to a remote project
  device     List and approve project device requests
  branch     List, create, switch, and promote branches
  config     Get or set global CLI configuration (e.g. api-url)

Run 'mdgit auth help' for auth subcommands.

Core Architectural Concepts

1. Project Data Key (PDK) Lifecycle

Every project vault has a symmetric 256-bit Project Data Key (PDK). New file contents are encrypted with the active PDK generation. When members leave or devices are revoked, the PDK is rotated to a new generation; historical PDK generations remain available for historical snapshot decryption.

2. Cryptographic Device Identities

Each machine where you run mdgit generates a unique X25519 ECIES key pair stored in ~/.mydatagit/. When joining a project, the device requests access by sending its public key. An Owner or Admin unwraps the PDK and re-wraps it for that device's public key.

3. 24-Word BIP-39 Disaster Recovery

When creating a project, an immutable recovery slot is generated using a 24-word BIP-39 mnemonic phrase. The mnemonic is displayed exactly once. If every authorized device is destroyed, the 24-word phrase can unwrap the PDK and grant access to a fresh machine.

TRACKING SPECIFICATION • .include

The `.include` Tracking Specification & Rules

In traditional Git, the repository tracks everything by default and relies on .gitignore as a blocklist. Because accidental secret leaks in Git are irreversible, MyDataGit adopts the inverse security model: an explicit, declarative allowlist defined in your root .include file.

Only files and directories explicitly matching rules in .include are parsed, fingerprinted with HMAC-SHA256, and encrypted with AES-256-GCM. Everything else in your project remains untouched.

Location & Format The file lives at the root of your project directory as .include. It uses clean INI-style section headers ([global] and [branch:<name>]) with POSIX relative paths.

1. File Structure & Syntax

A .include file organizes tracked paths into global and branch-scoped sections:

Annotated .include Syntax

# -------------------------------------------------------------
# 1. GLOBAL SECTION: Shared secrets synced across ALL branches
# -------------------------------------------------------------
[global]
docs/context.md
secrets/shared-api-keys.json
certs/company-ca.crt
config/common/

# -------------------------------------------------------------
# 2. DEVELOPMENT BRANCH: Local developer overrides
# -------------------------------------------------------------
[branch:dev]
type: development
.env
.env.local
secrets/dev-oauth.json

# -------------------------------------------------------------
# 3. STAGING BRANCH: Integration & pre-release credentials
# -------------------------------------------------------------
[branch:staging]
type: staging
.env.staging
secrets/staging-db.json

# -------------------------------------------------------------
# 4. PRODUCTION BRANCH: Production secrets (guarded by CAS)
# -------------------------------------------------------------
[branch:prod]
type: production
.env.prod
certs/prod-private.key
secrets/master-credentials.json

2. Section Types & Environment Metadata

Syntax Directive	Scope	Behavior & Guardrail
`[global]`	All branches	Files listed here are collected and decrypted on every branch (`dev`, `staging`, `prod`, etc.).
`[branch:<name>]`	Branch only	Files listed here are only collected and decrypted when switching to that specific branch.
`type: <env>`	Metadata	Declares the environment classification (`development`, `staging`, `production`, `testing`). Enables promotion mismatch warnings and confirmation guardrails (SEC-4.2).
`# comment`	Comment	Lines starting with `#` and blank lines are ignored by the parser.

3. Path Rules & Security Boundary Invariants

MyDataGit enforces strict filesystem boundary invariants (AGENTS §20) to prevent path traversal, symlink escapes, or host system exposure:

POSIX Format: Paths must always use forward slashes (/), even on Windows machines (e.g. secrets/dev.env). Backslashes are rejected.
Project-Relative Paths: Every path must be relative to the repository root. Absolute paths (/etc/secrets, C:\secrets) are rejected immediately.
No Path Traversal: .. (parent directory) and . inner segments that attempt to reach outside the project directory trigger an UnsafePathError.
Directory Recursion: Listing a directory (e.g. secrets/ or config) automatically crawls and tracks all nested files within that directory.
Project Root (.): A single dot . entry allows tracking the entire directory tree safely.
Protected VCS Directories: Internal management directories (.git and .mydatagit) are permanently excluded from tracking and can never be pushed as vault content.

4. File Processing & Synchronization Pipeline

When you run mdgit status or mdgit push, the CLI runs your project through an audited, multi-stage pipeline:

.include
  │
  ├──► IncludeParser       (Validates sections, branch types, and syntax rules)
  │
  ├──► PathResolver        (Enforces project boundary & POSIX path validation)
  │
  ├──► IncludeCollector    (Crawls declared files and recurses directories)
  │
  ├──► FileReader          (Reads raw on-disk bytes)
  │
  ├──► FileTypeDetector    (Detects text vs binary: .env, .json, .pem, .p12)
  │
  ├──► FileHasher          (Computes HMAC-SHA256 content_hash bound to PDK generation)
  │
  └──► AES-256-GCM         (Encrypts with 96-bit fresh nonce → Backblaze B2 ciphertext)

5. Adding Files & Common Workflow Recipes

Recipe: Track a Single Environment File

$ echo ".env" >> .include
mdgit status

Appends a file to the global section of your .include and verifies it appears as a tracked file.

Expected Output

On branch: main

New files:
  + .env

Run 'mdgit push' to encrypt and sync.

Recipe: Track an Entire Directory of Private Certificates

$ echo "certs/" >> .include
mdgit status

Recursively tracks every certificate, key, and bundle inside the certs/ directory.

Expected Output

On branch: main

New files:
  + certs/ca-root.crt
  + certs/app-private.key
  + certs/tls-bundle.p12

Recipe: Removing a File from Tracking (Tombstone Record)

$ # Remove 'secrets/old.json' from .include, then:
mdgit push

Removing a path from .include automatically propagates a tombstone record on remote branches so other teammates remove it on 'mdgit pull', while keeping historical snapshot decryption intact.

Expected Output

Propagating tombstone for 'secrets/old.json'...
✓ Pushed 1 deletion. Remote manifest updated.

Quickstart Workflow

A full end-to-end round trip in 4 straightforward commands:

Step 1: Sign up & create cryptographic device identity

$ mdgit auth signup --email dev@example.com --password "StrongPassword123!"

Registers your account and initializes your local X25519 device key pair.

Options & Flags

--email	Account email address
--password	Account password (Argon2id hashed server-side)
--device-name	Optional human-readable device name (e.g. 'MacBook-Pro')

Expected Output

Profile:        default
Account:        dev@example.com
Email verified: no
Device:         MacBook-Pro (01J5K...)
Signed in:      yes

Step 2: Initialize local tracking (.include)

$ mdgit init && echo ".env" >> .include

Initializes local .mydatagit metadata and specifies which files to track and encrypt.

Expected Output

Initialized empty MyDataGit project in D:\my-app\.mydatagit
Add files to track in D:\my-app\.include, then use 'mdgit status'.

Step 3: Create project vault & push encrypted files

$ mdgit project create my-app-vault && mdgit push

Creates the remote vault, shows your 24-word recovery phrase, and pushes ciphertext blobs.

Expected Output

Created project 'my-app-vault' (01J5X982...).

Recovery Key (shown once; store it securely):
abandon ability able about above absent absorb abstract absurd abuse access accident
account accuse achieve acid acoustic acquire across act action actor actress actual

Encrypting 1 file with PDK (AES-256-GCM)...
Uploading ciphertext blobs to Backblaze B2...
✓ Pushed 1 file.

1. Authentication Commands (`mdgit auth`)

Manage your account identity, active device session, and Personal Access Tokens (PATs).

mdgit auth login

$ mdgit auth login --email dev@example.com

Authenticates an existing account via password or Personal Access Token.

Options & Flags

--email	Account email
--password	Account password
--token	Login using a Personal Access Token (PAT)
--profile	Named profile (default: 'default')

Expected Output

Signed in as dev@example.com (profile 'default').

mdgit auth status

$ mdgit auth status

Displays the active account, verified status, and local cryptographic device ID.

Expected Output

Profile:        default
Account:        dev@example.com
Email verified: yes
Device:         dev-laptop (01J5KV09...)
Signed in:      yes

mdgit auth token create

$ mdgit auth token create --name ci-deploy-token --expires-at 90d

Generates a scoped Personal Access Token (PAT) for CI/CD automation or headless terminals.

Options & Flags

--name	Human-readable token name
--expires-at	Expiration duration (e.g. 30d, 90d, 1y)

Expected Output

mdg_pat_01J5K98F...

This token is shown once and will not be shown again. Store it securely.

2. Local Workspace Commands (`init`, `status`)

Inspect local directory changes, tracked files, and conflict states without network calls.

mdgit status

$ mdgit status

Compares current on-disk files against BASE state with zero-knowledge masking.

Expected Output

On branch: main
Linked remote: my-app-vault (01J5X9...)

Modified:
  ~ .env
New files:
  + secrets/stripe-key.pem

3. Remote Synchronization (`push`, `pull`)

Encrypt local state and push ciphertext blobs to Backblaze B2, or pull and decrypt locally.

mdgit push

$ mdgit push

Encrypts changed files with AES-256-GCM and pushes new immutable snapshots to remote storage.

Expected Output

Encrypting 2 files with PDK (AES-256-GCM)...
Uploading ciphertext to Backblaze B2...
✓ Pushed 2 files.

mdgit pull

$ mdgit pull

Pulls latest remote manifest, downloads ciphertext blobs, and decrypts locally using your device key.

Expected Output

Downloading manifest for branch 'main'...
Unwrapping PDK generation 1...
Decrypting 2 files...
✓ Pulled 2 files.

4. Project & Recovery Commands (`mdgit project`)

Create vaults, clone metadata to new workspaces, and redeem 24-word disaster recovery mnemonics.

mdgit project clone

$ mdgit project clone <project-id> [dir]

Clones project metadata into a directory and requests cryptographic device key approval.

Expected Output

Initialized empty MyDataGit project in /workspace/app/.mydatagit
Linked remote 'backend-vault' (01J5K98...).
Awaiting device approval. An Owner or Admin must approve this device before files can be decrypted.

mdgit project recover

$ mdgit project recover <project-id>

Restores vault access on a fresh computer using your 24-word BIP-39 recovery mnemonic.

Expected Output

Enter your 24-word recovery mnemonic:
abandon ability able about above absent absorb abstract absurd abuse access accident...

✓ Successfully recovered project '01J5K98...'. Key grant is now active on this device.
Run 'mdgit pull' to decrypt project files.

5. Multi-Device Approvals (`mdgit device`)

List and approve cryptographic key requests for team members and secondary laptops.

mdgit device list

$ mdgit device list

Lists all pending device key requests waiting for Owner/Admin approval.

Expected Output

REQ_ID      DEVICE_PUBLIC_KEY               REQUESTED
req_019a8   04a7f8... (MacBook-Air-M2)      requested 2026-08-29T10:15:00Z

mdgit device approve

$ mdgit device approve <request-id>

Unwraps the Project Data Key and re-wraps it with the target device's public key.

Expected Output

Unwrapping PDK generation 1...
Sealing PDK for device 04a7f8...
✓ Approved device request 'req_019a8'.

6. Branching & CAS Promotion (`mdgit branch`)

Compare environment differences with secret masking and promote snapshots with CAS guardrails.

mdgit branch compare

$ mdgit branch compare dev prod

Compares two branches without exposing sensitive secret plaintext.

Expected Output

Comparing 'dev' ➔ 'prod':

Added files:
  + .env.staging
Modified files:
  ~ .env

Branches have 2 differences.

mdgit branch promote

$ mdgit branch promote dev prod --yes

Promotes snapshots from source to target with optimistic concurrency (CAS) check.

Options & Flags

--yes

Mandatory confirmation flag when promoting to a 'prod' branch (SEC-4.2)

Expected Output

✓ Successfully promoted 'dev' ➔ 'prod' (new snapshot 01J5M429...).

7. Global Configuration (`mdgit config`)

Read and configure CLI global endpoints and defaults stored in ~/.mydatagit/config.json.

mdgit config set api-url

$ mdgit config set api-url https://mydatagit-api.vinothfootball123.workers.dev

Sets the global API gateway URL.

Expected Output

Set 'api-url' to 'https://mydatagit-api.vinothfootball123.workers.dev' in ~/.mydatagit/config.json

mdgit config list

$ mdgit config list

Prints all active global configuration settings.

Expected Output

Active Global Configuration (~/.mydatagit/config.json):
  api-url = https://mydatagit-api.vinothfootball123.workers.dev

Security Invariants & Guarantees

Zero Plaintext Storage: File contents and environment values are encrypted before leaving your computer.
Unique 96-bit AES-GCM Nonces: Fresh nonces are generated per file encryption operation; nonces are never reused.
HMAC Content Identity: Content hashes are derived with a key tied to the PDK generation.
Tamper-Proof Audit: Every promotion, device approval, role change, and recovery redemption is recorded in an immutable log.

MyDataGit CLI Reference

Installation & Setup

Core Architectural Concepts

1. Project Data Key (PDK) Lifecycle

2. Cryptographic Device Identities

3. 24-Word BIP-39 Disaster Recovery

The .include Tracking Specification & Rules

1. File Structure & Syntax

2. Section Types & Environment Metadata

3. Path Rules & Security Boundary Invariants

4. File Processing & Synchronization Pipeline

5. Adding Files & Common Workflow Recipes

Quickstart Workflow

1. Authentication Commands (mdgit auth)

2. Local Workspace Commands (init, status)

3. Remote Synchronization (push, pull)

4. Project & Recovery Commands (mdgit project)

5. Multi-Device Approvals (mdgit device)

6. Branching & CAS Promotion (mdgit branch)

7. Global Configuration (mdgit config)

Security Invariants & Guarantees

The `.include` Tracking Specification & Rules

1. Authentication Commands (`mdgit auth`)

2. Local Workspace Commands (`init`, `status`)

3. Remote Synchronization (`push`, `pull`)

4. Project & Recovery Commands (`mdgit project`)

5. Multi-Device Approvals (`mdgit device`)

6. Branching & CAS Promotion (`mdgit branch`)

7. Global Configuration (`mdgit config`)