@gitping/cli 0.0.1 → 0.1.0

package/README.md

@@ -0,0 +1,300 @@
+# ⚡ GitPing CLI
+
+> **Ping the people who build the internet.**
+
+Contact any developer using their GitHub identity, directly from your terminal.
+
+[![npm version](https://img.shields.io/npm/v/@gitping/cli?style=flat-square)](https://www.npmjs.com/package/@gitping/cli)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
+
+GitPing lets you send short messages called **pings** to any GitHub developer, accept conversations, and chat in real time without leaving the terminal.
+
+No email hunting.
+No LinkedIn messages.
+No awkward introductions.
+
+Just one developer reaching out to another.
+
+---
+
+# Why GitPing Exists
+
+In 1991, a Finnish computer science student named Linus Torvalds shared a small operating system he had been building as a hobby. That project eventually became Linux, which now runs much of the internet.
+
+Around the same time, Guido van Rossum created a programming language designed to make code easier to read. He called it Python. Today it powers startups, research labs, and global infrastructure.
+
+In 1995, Brendan Eich wrote JavaScript in just ten days. That language would go on to shape the modern web.
+
+Years later, Ryan Dahl introduced Node.js, changing how developers build servers. At Facebook, Jordan Walke created React, a library that reshaped modern interfaces.
+
+All of these stories started the same way.
+
+A developer built something interesting.
+Another developer discovered it.
+A conversation started.
+
+That is how open source has always worked.
+
+But today, something frustrating often happens.
+
+You find an amazing repository.
+You read the code.
+You understand the idea behind it.
+
+And you think:
+
+> "I wish I could talk to the person who built this."
+
+Maybe you want to collaborate.
+Maybe you want feedback.
+Maybe you simply want to say thank you.
+
+But reaching out to developers on GitHub is still harder than it should be.
+
+GitPing fixes that.
+
+GitPing lets you find the developers behind the code you admire and send them a simple ping.
+
+No cold emails.
+No LinkedIn messages.
+No complicated introductions.
+
+Just one developer reaching out to another.
+
+Because that is how the internet has always been built.
+
+GitPing helps those conversations happen.
+
+**One developer at a time.**
+
+---
+
+# Installation
+
+```bash
+npm install -g @gitping/cli
+```
+
+or
+
+```bash
+bun add -g @gitping/cli
+```
+
+After installing, the `gitping` binary is available globally.
+
+---
+
+# Quick Start
+
+```bash
+# Authenticate with GitHub
+gitping login
+
+# Send a ping
+gitping ping @torvalds "Hey! Would love to collaborate."
+
+# Check your inbox
+gitping inbox
+
+# Accept a ping
+gitping accept @someuser
+
+# Start chatting
+gitping chat @someuser
+```
+
+---
+
+# Authentication
+
+## `gitping login`
+
+Opens your browser for GitHub OAuth using PKCE.
+
+Your token is stored securely in the **OS keychain**, never in environment variables or dotfiles.
+
+```bash
+gitping login
+gitping login --json
+```
+
+---
+
+## `gitping logout`
+
+Clears stored credentials.
+
+```bash
+gitping logout
+```
+
+---
+
+## `gitping whoami`
+
+Shows your GitPing profile.
+
+```bash
+gitping whoami
+```
+
+Example:
+
+```
+@torvalds
+Rep score:    87  [HIGH]
+Availability: open-to-collab
+Status msg:   Open to kernel contributions
+```
+
+---
+
+# Pings
+
+A **ping** is a short message sent to another developer.
+
+Maximum length: **250 characters**.
+
+If the developer has not joined GitPing yet, the ping is **queued and delivered automatically when they sign up**.
+
+---
+
+## `gitping ping`
+
+```bash
+gitping ping @torvalds "Hi! Would love feedback on my kernel patch."
+gitping ping @torvalds "Hiring Rust engineers — interested?" --cat job
+gitping ping @gvanrossum "Collaborating on a Python tool?" --cat collab
+```
+
+### Categories
+
+| Category | Description                   |
+| -------- | ----------------------------- |
+| job      | recruiting or job opportunity |
+| collab   | project collaboration         |
+| oss      | open source contribution      |
+| feedback | asking for feedback           |
+
+---
+
+# Inbox
+
+## `gitping inbox`
+
+List received pings.
+
+```bash
+gitping inbox
+gitping inbox --unread
+gitping inbox --watch
+```
+
+Example:
+
+```
+⚡ GitPing Inbox (3 pings)
+
+a1b2c3d4  @somedev → @you  [collab]
+Hey! Would love to collaborate on your project.
+```
+
+---
+
+## Accept / Ignore / Block
+
+```bash
+gitping accept @user
+gitping ignore @user
+gitping block @spammer
+```
+
+Users blocked by **5 different developers within 24 hours are automatically suspended**.
+
+---
+
+# Chat
+
+Once a ping is accepted, you can start a real time conversation.
+
+```bash
+gitping chat @username
+```
+
+Example:
+
+```
+⚡ GitPing Chat with @somedev
+
+> Hey! Ready to sync up?
+You 10:32  Hey! Ready to sync up?
+Them 10:33 Absolutely, let's go!
+```
+
+---
+
+# Status
+
+Set your availability.
+
+```bash
+gitping status --set open-to-collab
+gitping status --set open-to-work
+gitping status --set selective
+gitping status --set heads-down
+```
+
+---
+
+# Discovery
+
+## Search
+
+```bash
+gitping search @torvalds
+```
+
+---
+
+## Leaderboard
+
+```bash
+gitping leaderboard
+gitping leaderboard --rising
+```
+
+Shows the **most pinged developers on GitPing**.
+
+---
+
+# Reputation Score
+
+Every user has a **0–100 reputation score** based on interactions.
+
+| Tier   | Score  |
+| ------ | ------ |
+| TOP    | 86–100 |
+| HIGH   | 66–85  |
+| MEDIUM | 41–65  |
+| LOW    | 0–40   |
+
+High reputation increases visibility.
+
+Spamming lowers it.
+
+---
+
+# How It Works
+
+1. Send a ping
+2. If the user is on GitPing, it is delivered instantly
+3. If not, it is queued until they join
+4. They can accept, ignore, or block
+5. Accepted pings unlock real time chat
+
+---
+
+# License
+
+MIT © GitPing