pipers-cli/README.md

Official CLI tool for Pipers - A GitHub alternative for seamless git operations without sharing data with any LLM Engine like OPenAI

# Pipers CLI

[![npm version](https://badge.fury.io/js/pipers-cli.svg)](https://badge.fury.io/js/pipers-cli)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

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 pipers-cli@1.2.0`
- **Current Version**: 1.2.0

## 🚀 Quick Start

### Installation

Install Pipers CLI globally via npm:

```bash
npm install -g pipers-cli
```

### First Time Setup

1. **Login to Pipers:**

   ```bash
   pipers login
   ```

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

2. **Verify your login:**

   ```bash
   pipers whoami
   ```

3. **Start using Pipers:**
   ```bash
   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`

```json
{
  "baseUrl": "https://api.pipers.shivastra.in",
  "token": "ghp_your_token_here",
  "user": {
    "id": "689f1bc1cf79b3cc41fc62dc",
    "username": "akansha",
    "email": "akanshakhedia@gmail.com",
    "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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```http
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": "akanshakhedia@gmail.com",
    "fullName": "akansha"
  }
}
```

#### Repository Management

```http
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](https://pipers.shivastra.in/docs/api)

## 📄 License

MIT License - see the [LICENSE](LICENSE) file for details.

## 🆘 Support & Troubleshooting

- 🔧 **Troubleshooting**: See [TROUBLESHOOTING.md](TROUBLESHOOTING.md) for common issues
- 🩺 **Diagnostics**: Run `pipers doctor` to check your setup
- 📚 **Documentation**: [https://pipers.shivastra.in/docs](https://pipers.shivastra.in/docs)
- 🐛 **Issues**: [GitHub Issues](https://github.com/pipers/pipers-cli/issues)
- 💬 **Community**: [Pipers Discord](https://discord.gg/pipers)

## 🚧 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:**
   ```bash
   npm install
   ```

2. **Start development server:**
   ```bash
   npm run dev
   ```
   Opens at http://localhost:5173

3. **Build for production:**
   ```bash
   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 `pipers-cli@1.1.6`
- 🔄 **Repository Creation API**: In development
- 🔄 **Web Dashboard**: Basic UI implemented