Home Docs API CLI GitHub Star on GitHub
Under Active Development — v1.1.1

The social network
for your terminal.

A decentralized, terminal-native SNS built on ed25519 elliptic curve cryptography. Every post is signed, every identity is your key — zero passwords, zero gatekeepers.

kb — Koshi Board CLI
$ kb register alice
✔ Registration successful!
$ kb post "Hello, koshi! 🌊"
✔ Post created!
$ kb feed --limit=5
📋 Koshi Board Feed (5 posts)
────────────────────────────
alice @alice
Hello, koshi! 🌊
$
1.1.1
Version
16
CLI Commands
21
API Endpoints
MIT
License
Features

Why Koshi?

💻

Terminal-Native

No browser bloat. Everything from posting to DMing is handled natively within your command line. Perfect with tmux or Zellij.

🔐

Cryptographic Identity

Your identity is your ed25519 public key. Secure authentication without passwords — every action is cryptographically signed.

Real-Time Feed

WebSocket-powered live updates. Connect to the stream and see posts, DMs, and presence changes as they happen.

📝

Signed Posts

Every post carries an ed25519 signature, ensuring authenticity. Verify authorship without trusting a central authority.

✉️

Direct Messages

Signed, authenticated DMs with real-time delivery via WebSocket. Every message is verifiable and tamper-proof.

💬

Real-Time Chat

Interactive DM chat mode with live WebSocket messaging. Connect to any user and chat in real-time with cryptographic signatures.

✏️

Profile Editing

Update your display name, bio, and avatar URL directly from the CLI with the kb edit-profile command.

🛠️

Admin Controls

Built-in admin system with user management, account deletion with cascade, and admin privilege grants via dedicated API endpoints.

☁️

Edge Deployed

Runs on Render.com + Neon.tech with Docker support. One-click deploy with automatic migrations on startup.

Quick Start

Get started in seconds

# Install Koshi globally
$ npm install -g @ryopc/koshi
# Register a new account (generates ed25519 keypair)
$ kb register alice
✔ Registration successful!
# Post to the koshi board
$ kb post "Hello, koshi! 🌊"
✔ Post created!
# View your feed
$ kb feed --limit=10
📋 Koshi Board Feed (3 posts)
# Connect to real-time stream
$ kb realtime
📡 Connecting to realtime feed...
✓ Connected! Waiting for new posts...
Architecture

How Koshi works

🔧

Stack

Runtime Node.js 20+
Framework Express.js
Database PostgreSQL 15
Auth ed25519 + JWT
Real-time WebSocket (ws)
CLI Chalk + Ora
📁

Project Structure

koshi/
├── bin/
├── cli.js # CLI entry point
└── server.js # Express + WS server
├── src/
├── api/ auth.js, users.js, posts.js, dms.js
├── auth/ ed25519.js, jwt.js, utils.js
├── db/ schema.sql, migrate.js, pool.js
├── ws/ index.js, handlers.js
└── middleware/ auth.js, rateLimit.js
├── Dockerfile
├── render.yaml # Render Blueprint
└── package.json
CLI

All Commands

CommandDescriptionAuth
kb register <username>Create a new account with ed25519 keypairNo
kb login <username>Authenticate using existing keypairNo
kb whoamiShow your profile informationYes
kb post <message>Create a new post on the boardYes
kb feed [--limit=N]Display your post feedOpt
kb follow <username>Follow a userYes
kb unfollow <username>Unfollow a userYes
kb dm <user> <msg>Send a direct messageYes
kb dms [--unread]View your direct messagesYes
kb chat <username>Interactive real-time DM chatYes
kb edit-profile <flags>Update your display name, bio, avatarYes
kb profile [username]View a user's profileOpt
kb search <query>Search users by usernameOpt
kb realtimeConnect to the live event streamYes
kb admin <cmd>Admin: users, delete-user, grant, revokeAdmin