Pipers CLI

The official command-line interface for Pipers - A modern GitHub alternative that makes version control simple and powerful.

🌐 Live Deployment

• Frontend: https://pipers.shivastra.in
• Backend API: https://api.pipers.shivastra.in
• CLI Package: npm install -g [email protected]
• Current Version: 1.2.0

🚀 Quick Start

Installation

Install Pipers CLI globally via npm:

npm install -g pipers-cli

First Time Setup

1. Login to Pipers:

   pipers login

   You'll need a Personal Access Token from your Pipers account.

2. Verify your login:

   pipers whoami

3. Start using Pipers:

   pipers clone username/repository

📋 Commands

Authentication

| Command | Description | | ------------------------------ | ---------------------------------- | | pipers login | Login with Personal Access Token | | pipers login --token <TOKEN> | Login with token (non-interactive) | | pipers logout | Clear authentication | | pipers whoami | Show current user info |

Repository Operations

| Command | Description | | -------------------------------- | ---------------------------------- | | pipers clone <username/repo> | Clone a repository | | pipers create <name> | Create a new repository | | pipers create <name> --private | Create a private repository | | pipers create <name> --init | Create repo and initialize locally |

Git Operations

| Command | Description | | ---------------------------- | ------------------------------- | | pipers init [directory] | Initialize a new git repository | | pipers add [files...] | Add files to staging area | | pipers add -A | Add all files to staging area | | pipers commit -m "message" | Commit changes | | pipers status | Show repository status | | pipers push | Push changes to remote | | pipers pull | Pull latest changes |

Branching & Merging

| Command | Description | | ----------------------------- | ------------------------------------ | | pipers branch | List branches | | pipers branch <name> | Create a new branch | | pipers branch -d <name> | Delete a branch | | pipers branch -a | List all branches (local and remote) | | pipers checkout <branch> | Switch to a branch | | pipers checkout -b <branch> | Create and switch to new branch | | pipers merge <branch> | Merge a branch into current branch |

Advanced Git Operations

| Command | Description | | -------------------------------- | ---------------------------------- | | pipers stash | Stash changes in working directory | | pipers stash pop | Apply latest stash | | pipers stash list | List all stashes | | pipers stash clear | Clear all stashes | | pipers log | View commit history | | pipers log --oneline | View commits in one line format | | pipers diff [source] [target] | Show differences | | pipers remote -v | List remote repositories | | pipers remote add <name> <url> | Add a remote repository |

Diagnostics & Help

| Command | Description | | ---------------- | ------------------------------- | | pipers doctor | Run diagnostics and health check | | pipers help | Show help information |

🔧 Configuration

Environment Variables

• PIPERS_BASE_URL - Override default server URL (default: https://api.pipers.shivastra.in)

Config File Location

Pipers CLI stores configuration in ~/.pipers/config.json

{
  "baseUrl": "https://api.pipers.shivastra.in",
  "token": "ghp_your_token_here",
  "user": {
    "id": "689f1bc1cf79b3cc41fc62dc",
    "username": "akansha",
    "email": "[email protected]",
    "fullName": "akansha"
  }
}

## 📖 Detailed Usage

### Login & Authentication

Generate a Personal Access Token from your Pipers account settings:

1. Go to `https://pipers.shivastra.in/settings/tokens`
2. Click "Generate new token"
3. Copy the token and use it:

```bash
# Interactive login
pipers login

# Or provide token directly
pipers login --token ghp_your_token_here

# Login to custom server
pipers login --url https://your-pipers-server.com

Creating Repositories

# Create a public repository
pipers create my-awesome-project

# Create a private repository with description
pipers create my-private-project --private --description "My secret project"

# Create and initialize locally
pipers create my-project --init
cd my-project
echo "# My Project" > README.md
pipers add .
pipers commit -m "Initial commit"
pipers push -u origin main

Cloning Repositories

# Clone with default name
pipers clone username/repository

# Clone to specific directory
pipers clone username/repository my-local-folder

# Shallow clone (faster for large repos)
pipers clone username/repository --depth 1

Working with Repositories

# Initialize a new repository
pipers init
pipers remote add origin https://pipers.shivastra.in/username/repo.git

# Check repository status
pipers status

# Add files to staging
pipers add .
pipers add file1.txt file2.txt
pipers add -A  # Add all files

# Commit changes
pipers commit -m "Your commit message"
pipers commit -a -m "Auto-stage and commit"

# Push changes
pipers push
pipers push -u origin main  # Set upstream
pipers push --force  # Force push (use with caution)

# Pull latest changes
pipers pull
pipers pull origin main

Branching Workflow

# List branches
pipers branch
pipers branch -a  # Include remote branches

# Create and switch to new branch
pipers checkout -b feature/new-feature
pipers checkout -b api/changes

# Switch between branches
pipers checkout main
pipers checkout feature/new-feature

# Merge branches
pipers checkout main
pipers merge feature/new-feature

# Delete branch
pipers branch -d feature/new-feature

Advanced Git Operations

# Stash operations
pipers stash  # Stash current changes
pipers stash -m "Work in progress"
pipers stash pop  # Apply latest stash
pipers stash list  # List all stashes
pipers stash clear  # Clear all stashes

# View history and differences
pipers log
pipers log --oneline
pipers log -n 10  # Last 10 commits
pipers diff
pipers diff main feature/branch
pipers diff HEAD~1 HEAD

# Remote management
pipers remote -v
pipers remote add upstream https://pipers.shivastra.in/original/repo.git
pipers remote remove origin

🆚 GitHub vs Pipers CLI Comparison

| GitHub CLI | Pipers CLI | Description | | -------------------------- | --------------------------- | ----------------- | | gh auth login | pipers login | Authenticate | | gh repo clone owner/repo | pipers clone owner/repo | Clone repository | | gh repo create | pipers create | Create repository | | git add . | pipers add . | Stage files | | git commit -m "msg" | pipers commit -m "msg" | Commit changes | | git push | pipers push | Push changes | | git pull | pipers pull | Pull changes | | git checkout -b branch | pipers checkout -b branch | Create branch | | git status | pipers status | Check status | | git log | pipers log | View history |

🔒 Security

• Tokens are stored in ~/.pipers/config.json
• All API calls use HTTPS encryption
• Tokens are validated on each request
• Never share your Personal Access Token
• Use pipers logout on shared machines
• Example token format: ghp_e45580f3cbe76266e4af5c8d7e47748327eb2103

🛠️ Development

Prerequisites

• Node.js 14 or higher
• Git installed and available in PATH
• Access to a Pipers server

Local Development

# Clone this repository
git clone https://github.com/pipers/pipers-cli.git
cd pipers-cli

# Install dependencies
npm install

# Link for local testing
npm link

# Now you can use the local version
pipers --version

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature-name
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

🏗️ Architecture & Technology Stack

Technology Used

• Language: Node.js (JavaScript)
• CLI Framework: Commander.js
• HTTP Client: Axios
• UI/UX: Chalk (colors), Ora (spinners), Boxen (boxes), Inquirer (prompts)
• Process Management: cross-spawn
• Package Manager: npm

How It Works

1. Authentication: Stores Personal Access Token in ~/.pipers/config.json
2. Git Integration: Executes actual git commands using cross-spawn
3. API Communication: Makes HTTP requests to Pipers server using Axios
4. Configuration: Manages settings in user's home directory
5. Cross-Platform: Works on Windows, macOS, and Linux

Code Structure

pipers-cli/
├── bin/
│   └── pipers.js          # Main CLI executable
├── scripts/
│   └── pre-publish.js     # Pre-publish validation
├── package.json           # Package configuration
├── README.md             # Documentation
├── LICENSE               # MIT License
└── .npmignore           # npm ignore rules

🌐 API Integration

Backend API Endpoints

The Pipers CLI connects to the backend API at https://api.pipers.shivastra.in

Authentication

POST /api/auth/validate-token
Content-Type: application/json

Request:
{
  "token": "ghp_your_token_here"
}

Response:
{
  "message": "Token valid",
  "user": {
    "id": "689f1bc1cf79b3cc41fc62dc",
    "username": "akansha",
    "email": "[email protected]",
    "fullName": "akansha"
  }
}

Repository Management

POST /api/user/repos
Headers: Authorization: Bearer <token>
Content-Type: application/json

Request:
{
  "name": "my-project",
  "description": "My awesome project",
  "private": true
}

Response:
{
  "name": "my-project",
  "html_url": "https://pipers.shivastra.in/username/my-project",
  "clone_url": "https://api.pipers.shivastra.in/repos/username/my-project.git",
  "private": true
}

Git Repository Access

Git operations work with URLs like:
https://api.pipers.shivastra.in/repos/username/repository.git

API Documentation

For complete API documentation, visit: https://pipers.shivastra.in/docs/api

📄 License

MIT License - see the LICENSE file for details.

🆘 Support & Troubleshooting

• 🔧 Troubleshooting: See TROUBLESHOOTING.md for common issues
• 🩺 Diagnostics: Run pipers doctor to check your setup
• 📚 Documentation: https://pipers.shivastra.in/docs
• 🐛 Issues: GitHub Issues
• 💬 Community: Pipers Discord

🚧 Roadmap

• [ ] OAuth device flow authentication
• [ ] GitHub Actions equivalent (Pipers Actions)
• [ ] Issue and PR management commands
• [ ] Keychain integration for secure token storage
• [ ] Shell completions (bash/zsh/fish)
• [ ] Desktop app integration
• [ ] VS Code extension
• [ ] GUI desktop application

🎯 VS Code Integration

Current Integration (Terminal)

Users can use Pipers CLI directly in VS Code terminal:

1. Open VS Code
2. Open integrated terminal (Ctrl + ` )
3. Install: npm install -g pipers-cli
4. Use: pipers login, pipers clone, etc.

Future VS Code Extension

We're planning a VS Code extension that will:

• Provide GUI for repository management
• Integrate with VS Code's source control panel
• Show repository tree view
• Enable one-click operations
• Use this CLI under the hood

Made with ❤️ by the Pipers team

🌐 Web Interface & Development

Live Web Interface

• Production: https://pipers.shivastra.in
• Token Management: https://pipers.shivastra.in/settings/tokens

Local Development

The src/ folder contains a React web application built with Vite, TypeScript, and Tailwind CSS.

1. Install dependencies:

   npm install

2. Start development server:

   npm run dev

   Opens at http://localhost:5173

3. Build for production:

   npm run build

📊 Current Status

• ✅ CLI Authentication: Working with API
• ✅ Token Validation: POST /api/auth/validate-token
• ✅ User Management: Login/logout/whoami commands
• ✅ Git Operations: All standard git commands
• ✅ Repository Management: Create/clone repositories
• ✅ NPM Package: Published as [email protected]
• 🔄 Repository Creation API: In development
• 🔄 Web Dashboard: Basic UI implemented