griD CLI

Command-line interface for griD.dev - Decentralized code repository with Web3 ownership

Features

• 🔐 Wallet-based Authentication - Sign in with your Story Protocol wallet
• 🔒 End-to-End Encryption - AES-256-GCM encryption before upload
• 📦 IPFS Storage - Decentralized file storage via Pinata
• ⛓️ Story Protocol - On-chain IP asset registration on Story blockchain
• 🚀 Git-like Workflow - Familiar commands for developers

Network

Story Protocol Networks:

• Testnet: Story Aeneid (Iliad)
• RPC: https://testnet.storyrpc.io
• Chain ID: 1513 (testnet)
• Explorer: https://testnet.storyscan.xyz

Make sure your wallet (MetaMask) is connected to the Story network before signing messages.

Installation

Prerequisites

Install Node.js 14+ on your system:

• Windows: Download from nodejs.org or use winget install OpenJS.NodeJS
• macOS: brew install node or download from nodejs.org
• Linux:

  # Ubuntu/Debian
  curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
  sudo apt-get install -y nodejs
    
  # Fedora/RHEL
  sudo dnf install nodejs
    
  # Arch
  sudo pacman -S nodejs npm

Option 1: Install from npm (Recommended)

Once published to npm:

npm install -g @voidroot/grid-cli

Option 2: Install from Source

Clone and install:

# Clone repository
git clone https://github.com/SwayamTakkamore/griD.dev.git
cd griD.dev/grid-cli

# Install dependencies
npm install
cd auth-server
npm install
cd ..

# Link globally (makes 'grid' command available)
npm link

Verify installation:

grid --version

Platform-Specific Notes

Windows

• Run as Administrator for npm link
• Use PowerShell or Command Prompt
• If you get execution policy errors:

  Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

macOS

• May need sudo for global install:

  sudo npm install -g grid-cli

• On Apple Silicon (M1/M2), everything works natively

Linux

• May need sudo for global install
• Ensure node and npm are in PATH
• On WSL2, use Linux installation method

Uninstall

npm uninstall -g @voidroot/grid-cli

Or if installed from source:

npm unlink -g @voidroot/grid-cli

Publishing to npm (For Maintainers)

To make installation easier for users:

# 1. Login to npm
npm login

# 2. Update version in package.json
npm version patch  # or minor, or major

# 3. Publish
npm publish --access public

# Now users can install with: npm install -g @voidroot/grid-cli

Note: The CLI automatically manages the auth server - no manual setup required!

Quick Start

1. Login

Connect your wallet and authenticate:

grid login

How it works:

1. CLI prompts for your wallet address
2. Browser automatically opens to signing page
3. Connect your wallet (ensure you're on Story Aeneid testnet)
4. Click "Sign Message in MetaMask"
5. Approve the signature request
6. CLI automatically receives signature and completes login
7. Return to terminal - you're authenticated!

Note: Make sure MetaMask is connected to Story Protocol network before signing.

2. Initialize Repository

In your project directory:

grid init

This creates a .grid.json config file with your repository metadata.

3. Push Code

Upload your encrypted code to griD:

grid push -m "Initial commit"

Your code is:

• Zipped (respecting .gitignore)
• Encrypted locally with AES-256-GCM
• Uploaded to IPFS via backend
• Registered on Story Protocol

4. Pull Code

Download and decrypt code:

grid pull

Commands

Authentication

grid login

Connect wallet and authenticate with griD.dev

Example:

grid login

grid logout

Disconnect wallet and clear credentials

Example:

grid logout

grid whoami

Show current authenticated user

Example:

grid whoami

Repository Management

grid init

Initialize griD repository in current directory

Options:

• -v, --verbose - Verbose output

Example:

grid init

grid push

Encrypt and upload code to griD

Options:

• -m, --message <message> - Commit message
• --dry-run - Simulate push without uploading
• -v, --verbose - Verbose output

Example:

grid push -m "Add authentication feature"
grid push --dry-run  # Test without uploading

grid pull

Download and decrypt code from griD

Options:

• -v, --verbose - Verbose output

Example:

grid pull

grid repo info

Show repository information (local and remote)

Example:

grid repo info

Help

grid --help              # Show all commands
grid help <command>      # Show command help
grid push --help         # Command-specific help

Configuration

The CLI stores configuration in ~/.grid/config.json:

{
  "token": "eyJhbGc...",
  "walletAddress": "0x1234...",
  "username": "yourname",
  "email": "[email protected]"
}

⚠️ Never commit this file or share your token!

Security

Encryption

• Algorithm: AES-256-GCM
• Key Derivation: PBKDF2 (100,000 iterations)
• Key Storage: Encryption keys stored securely in backend
• No Plaintext: Code never leaves your machine unencrypted

Authentication

• Wallet Signature: Sign a nonce to prove wallet ownership
• JWT Tokens: 24-hour expiry
• No Private Keys: CLI never asks for or stores private keys

What's Encrypted

✅ Your source code ✅ File contents ✅ Directory structure

❌ Repository metadata (title, description, tags) ❌ IPFS CIDs ❌ On-chain data

Workflow Examples

Starting a New Project

# Create project
mkdir my-project
cd my-project
npm init -y

# Initialize griD
grid login
grid init

# Add code
echo "console.log('Hello griD');" > index.js

# Push to griD
grid push -m "Initial commit"

Cloning to Another Machine

# On new machine
mkdir my-project
cd my-project

# Login
grid login

# Pull from griD
grid pull

Checking Repository Status

grid repo info

Output:

📦 Repository Information

Local Configuration:
  Title:       my-project
  Description: My awesome project
  License:     open
  Tags:        javascript, web3
  Owner:       0x1234...
  Created:     1/13/2025, 10:30:00 AM

Remote Information:
  Repo ID:     abc123
  IP Asset ID: 0x5678...
  IPFS CID:    QmXy...
  Stars:       5
  Forks:       2
  Verified:    Yes

Environment Variables

# Backend URL (default: http://localhost:5000)
export GRID_BACKEND_URL=https://api.grid.dev

# Run commands
grid login

File Ignoring

The CLI respects .gitignore patterns and adds:

• node_modules/
• .git/
• .grid.json
• .env
• dist/
• build/

Troubleshooting

"Not authenticated" error

grid login

"Backend unreachable" error

Check backend is running:

curl http://localhost:5000/health

Set custom backend:

export GRID_BACKEND_URL=http://localhost:5000

"Not a griD repository" error

grid init

Pull overwrites local files

Always commit your work before pulling:

git add .
git commit -m "Save work"
grid pull

Development

Run from Source

git clone <repo>
cd grid-cli
npm install
npm link

# Now `grid` command is available globally
grid --help

Unlink

npm unlink -g grid-cli

Architecture

grid-cli/
├── bin/grid.js           # CLI entry point
├── commands/             # Command implementations
│   ├── login.js
│   ├── logout.js
│   ├── whoami.js
│   ├── init.js
│   ├── push.js
│   ├── pull.js
│   └── repo-info.js
├── utils/                # Utility modules
│   ├── config.js         # Config management
│   ├── auth.js           # Auth helpers
│   ├── wallet.js         # Wallet operations
│   ├── encrypt.js        # Encryption/decryption
│   ├── ipfs.js           # IPFS operations
│   └── api.js            # API client
└── package.json

Comparison with Git

| Feature | Git | griD CLI | |---------|-----|----------| | Auth | SSH/HTTPS | Wallet Signature | | Storage | Centralized Server | IPFS (Decentralized) | | Ownership | GitHub Account | Blockchain (Story Protocol) | | Encryption | Optional | Always (AES-256-GCM) | | History | Full Git History | Single Version (for now) | | Branching | Yes | Planned | | Access Control | Repo Settings | License-based |

Roadmap

• [ ] grid clone <repo> - Clone any public repository
• [ ] grid verify - Verify on-chain registration
• [ ] grid license list - View available licenses
• [ ] grid history - View commit history
• [ ] grid branch - Branch management
• [ ] Auto-update support
• [ ] GitHub integration
• [ ] Multi-version support

Support

• Documentation: https://grid.dev/docs
• Discord: https://discord.gg/grid
• Issues: https://github.com/grid-dev/grid-cli/issues

License

MIT License - see LICENSE file

Made with ⚡ by griD.dev