Open app
Open app
PersonalCloud VCS

PC CLI Documentation

This guide explains how PersonalCloud VCS works and how the PC CLI manages repositories, branches, and history.

1. Object model

Everything is content-addressed with SHA-256.

  • Blob = file contents (hashed)
  • Tree = folder listing of blobs/trees
  • Commit = pointer to a root tree + metadata + parent commits
  • Ref = branch pointer to a commit

2. Storage

MinIO stores objects; Firestore stores metadata and access control.

  • MinIO on the 2TB stores blobs, trees, and commit objects.
  • Firestore stores repo metadata, refs, and access control.
  • UI and API manage metadata while MinIO stores raw bytes.

3. Protocol (push/pull)

Clients send only missing objects to the server.

  • Client asks the server what it already has.
  • Client sends only missing objects (pack + manifest).
  • Server validates and updates refs if fast-forward.

4. CLI commands

The PersonalCloud CLI is named pc.

Common commands
pc init
pc add .
pc commit -m "message"
pc branch feature-x
pc checkout feature-x
pc push
pc pull
pc log
pc status
pc diff
pc merge feature-x

5. PC CLI setup

Install the CLI and configure your environment.

Windows (PowerShell)

Install + verify
PowerShell -ExecutionPolicy Bypass -File .\scripts\install-pc-cli.ps1
pc --help
Environment variables
$env:PC_API_BASE_URL="https://personalcloud.vercel.app"
$env:PC_TOKEN="YOUR_TOKEN"

macOS / Linux

Install + verify
chmod +x ./scripts/install-pc-cli.sh
./scripts/install-pc-cli.sh
pc --help
Environment variables
export PC_API_BASE_URL="https://personalcloud.vercel.app"
export PC_TOKEN="YOUR_TOKEN"

6. Branching

Branches are refs that point to commits.

  • Branch = a ref that points to a commit.
  • Checkout updates the working tree and .pc/index.

7. Merging

Start with manual or basic 3-way merge for MVP.

  • Start with manual or basic 3-way merge for MVP.
  • Automerge later.