Getting Started with cpm

Welcome to cpm — a minimal, self-hosted, distributed git repository management system. Think of it as a GitHub replacement without the web interface.

What is cpm?

cpm is not a replacement for git itself. Git handles version control — commits, branches, merges.

cpm replaces the hosting and collaboration layer that services like GitHub, GitLab, or Gitea provide:

git (unchanged) cpm (GitHub replacement)
Commits & history Repository hosting
Branches & merges User management
Local operations Organization management
Version control SSH key authentication
Server federation
Access control
Repository syncing

Why cpm?

cpm is designed for those who want:

  1. Self-Hosted Control — Your repositories on your servers, no third-party dependencies
  2. CLI-Only Interface — No web UI to maintain, secure, or update
  3. Distributed Architecture — Federate across multiple servers ("neighbors")
  4. Minimal Footprint — SQLite database, single binary, no complex stack
  5. SSH-Native — Authentication via SSH keys, just like git itself

Core Concepts

Servers

Machines that host git repositories. You register servers with cpm and can push/pull repositories to/from them.

Neighbors

Other cpm servers in your network. Enables peer-to-peer repository sharing without a central authority.

Organizations

Logical groupings for repositories and users. Similar to GitHub organizations.

Users

People who can access repositories. Each user has SSH keys for authentication.

Quick Example

# Initialize configuration
cpm config init

# Generate SSH key for authentication
cpm ssh-key generate mykey

# Register your main server
cpm servers add mainserver git@myserver.com --port 22

# Set it as the primary storage location
cpm servers set-main mainserver

# Create a new repository
cpm init myproject --org myteam

# Push to your server
cpm push myproject

# Add a user with their SSH key
cpm user add alice --email alice@example.com --key "ssh-ed25519 AAAA..."

# Discover neighboring cpm servers
cpm neighbors discover --network 192.168.1.0/24

# Sync a repo from a neighbor
cpm neighbors sync myproject --from neighbor1

Architecture Overview

┌─────────────────────────────────────────────────────────────┐
│                       YOUR NETWORK                          │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│   ┌─────────────┐         ┌─────────────┐                  │
│   │ Main Server │◄───────►│ Neighbor 1  │                  │
│   │ (your repos)│  sync   │ (peer repos)│                  │
│   └──────▲──────┘         └─────────────┘                  │
│          │                                                  │
│          │ push/pull                                        │
│          │                                                  │
│   ┌──────┴──────┐                                          │
│   │  cpm CLI   │  ◄── You are here                        │
│   │  (control)  │                                          │
│   └─────────────┘                                          │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Key Differences from GitHub

GitHub cpm
Centralized (github.com) Self-hosted & distributed
Web interface CLI only
Pull requests Direct push/pull
Actions/CI Bring your own CI
Issues/Projects Not included (use external)
Social features Not included
Vendor lock-in You own everything

What cpm Does NOT Replace

  • git — You still use git for commits, branches, merges
  • CI/CD — Use Jenkins, GitHub Actions, GitLab CI, etc.
  • Issue tracking — Use Jira, Linear, GitHub Issues, etc.
  • Code review — Use email patches, Gerrit, or direct collaboration

cpm focuses on one thing: repository hosting and distribution.

Next Steps

Getting Help

Source Code

cpm is hosted on cpm itself at cpm.town:

# Clone the cpm source
git clone git@cpm.town:cpm/cpm.git