Quick Start Guide

Get up and running with cpm in 5 minutes.

Step 1: Initialize cpm

First, initialize cpm to create the necessary configuration:

cpm init

This creates:

  • Configuration file at ~/.cpm/config.yaml
  • SQLite database at ~/.cpm/cpm.db

Step 2: Add Your First Repository

Add a repository to cpm:

cpm repo add myproject https://github.com/username/myproject.git

You can also clone and add in one step:

cpm repo clone https://github.com/username/myproject.git ~/projects/myproject

Step 3: List Repositories

View all your repositories:

cpm repo list

Example output:

ID  Name        URL                                      Organization
1   myproject   https://github.com/username/myproject.git  username

Step 4: Work with Organizations

Create an organization to group your repositories:

cpm org create myorg --description "My Organization"

Add a repository to the organization:

cpm repo add orgproject https://github.com/myorg/project.git --org myorg

List organizations:

cpm org list

Step 5: Manage SSH Keys

Generate a new SSH key pair:

cpm ssh generate mykey --email "you@example.com"

List your SSH keys:

cpm ssh list

Deploy a key to a repository:

cpm ssh deploy mykey --repo myproject

Step 6: Add a Git Server

Add a Git server to sync with:

cpm server add github https://api.github.com --token YOUR_TOKEN

Sync repositories from the server:

cpm server sync github

Common Workflows

Workflow 1: Managing Multiple Projects

# Add multiple repositories
cpm repo add project1 https://github.com/user/project1.git
cpm repo add project2 https://github.com/user/project2.git
cpm repo add project3 https://github.com/user/project3.git

# List all repositories
cpm repo list

# Get repository details
cpm repo show project1

Workflow 2: Organization Management

# Create organizations
cpm org create frontend --description "Frontend Projects"
cpm org create backend --description "Backend Services"

# Add repositories to organizations
cpm repo add webapp https://github.com/myorg/webapp.git --org frontend
cpm repo add api https://github.com/myorg/api.git --org backend

# List repositories by organization
cpm repo list --org frontend

Workflow 3: SSH Key Deployment

# Generate a deployment key
cpm ssh generate deploy-key --type deploy

# List available keys
cpm ssh list

# Deploy to multiple repositories
cpm ssh deploy deploy-key --repo webapp
cpm ssh deploy deploy-key --repo api
cpm ssh deploy deploy-key --repo worker

# View deployed keys
cpm ssh list --deployed

Workflow 4: Server Synchronization

# Add multiple servers
cpm server add github https://api.github.com --token TOKEN1
cpm server add gitlab https://gitlab.com/api/v4 --token TOKEN2
cpm server add gitea https://git.mycompany.com --token TOKEN3

# Sync all servers
cpm server sync --all

# List synchronized repositories
cpm repo list

Configuration Tips

Set Default Organization

Edit ~/.cpm/config.yaml:

defaults:
  organization: myorg

Configure Git Settings

cpm config set git.default-branch main
cpm config set git.auto-push true

View All Configuration

cpm config list

Next Steps

Now that you're familiar with the basics:

Getting Help

For any command, use the --help flag:

cpm --help
cpm repo --help
cpm ssh --help

Common Issues

Repository Already Exists

If you see "repository already exists", use --force to update:

cpm repo add myproject URL --force

Permission Denied

Ensure you have proper SSH keys configured:

cpm ssh list
cpm ssh test mykey

Database Locked

If the database is locked, ensure no other cpm processes are running:

ps aux | grep cpm

See the Troubleshooting Guide for more help.