Building a GitHub Backed Pastebin CLI in Go

There is a particular kind of friction that appears when you are deep in a terminal and need to keep a JSON payload, command sequence, or debugging note. Opening a browser or heavyweight notes application breaks the flow. Sending proprietary text to an arbitrary paste service creates a different problem: you have lost control of where the data lives.

The useful constraints are more important than the implementation language: the tool must open instantly, work offline, recover unsaved edits, keep human-readable files, synchronize across machines, and avoid owning a new server.

A cache assumes the authoritative copy lives elsewhere. A local-first tool treats the local file as immediately useful and editable, then synchronizes when a remote is available. The local-first software paper describes broader ideals around offline work, ownership, longevity, and collaboration. A personal CLI needs only a focused subset, but the distinction still matters.

• Offline is normal. Creating, opening, editing, listing, and searching local snippets should not require GitHub.
• Files stay legible. A user can inspect, copy, back up, or version the data without the application.
• Sync is explicit. The tool clearly reports whether work is local-only, synchronized, diverged, or conflicted.
• Remote failure is contained. Authentication or network problems do not destroy the current draft.

One file cannot simultaneously represent the editor buffer, crash recovery, a user-approved version, and a synchronized remote state. Giving those promises separate layers makes failure behavior much easier to explain.

• Working file: the user-visible content that opens immediately and can remain local.
• Recovery snapshot: a short-lived, crash-safe copy written frequently while editing.
• Journal: compact metadata describing dirty files, recovery generations, last known remote revision, and pending operations.
• Git commit: an intentional durable version with a stable identity and history.
• Remote repository: an authenticated synchronization target and off-device copy.

Use the operating system’s application-data or configuration directory rather than inventing a path under the current working directory. Go exposes this boundary through os.UserConfigDir, with platform-specific behavior.

Autosave should protect the draft without creating a remote commit for every keystroke. A practical loop debounces edits, writes a temporary file in the same filesystem, flushes it when the platform supports that guarantee, and atomically renames it over the recovery snapshot.

func SaveRecovery(path string, body []byte) error {
    tmp := path + ".tmp"

    file, err := os.OpenFile(tmp, os.O_CREATE|os.O_TRUNC|os.O_WRONLY, 0o600)
    if err != nil {
        return err
    }

    if _, err = file.Write(body); err != nil {
        file.Close()
        return err
    }
    if err = file.Sync(); err != nil {
        file.Close()
        return err
    }
    if err = file.Close(); err != nil {
        return err
    }

    return os.Rename(tmp, path)
}

A local save confirms the contents the user wants to keep. A sync reconciles that version with the remote repository. Keeping those commands separate avoids coupling everyday editing to connectivity and makes it possible to describe failures precisely.

1. Create a stable local version. Write the working file, clear its accepted recovery snapshot, and create a commit only when content changed.
2. Fetch before integrating. Learn whether the remote advanced since the last synchronized revision.
3. Fast-forward when possible. If only one side changed, apply the unambiguous update.
4. Merge only from a clean baseline. Do not start reconciliation with unrelated uncommitted changes.
5. Push only a resolved history. Never hide a conflict behind a successful-looking sync message.

Git’s merge documentation explains the states created by a non-trivial merge. A CLI can wrap those states, but should not pretend they do not exist.

Two machines can edit the same snippet before either synchronizes. Automatic line merging is useful when changes do not overlap, but a personal text tool should prefer recoverability over cleverness when intent is ambiguous.

Delegating authentication to GitHub CLI avoids inventing token storage. The GitHub CLI authentication flow normally stores credentials in the system credential store and documents its fallback behavior. The Pastebin CLI should call gh auth status and fail with a specific setup instruction rather than copying tokens into its own configuration.

• Use restrictive local permissions. Create data, journal, and recovery files for the current user only.
• Avoid secrets in process arguments. Arguments can appear in shell history or process listings.
• Redact diagnostic output. Logs should identify paths and operations without printing snippet contents or credentials.
• Make repository visibility explicit. Verify the created remote is private and stop if its visibility changes unexpectedly.

A single Go binary is a strong fit for a personal CLI, but distribution still needs integrity, ownership, and rollback. Install into a user-owned binary directory, verify release checksums, and keep upgrades explicit or policy-driven.

set -euo pipefail

install_dir="${XDG_BIN_HOME:-$HOME/.local/bin}"
mkdir -p "$install_dir"

# Download the release and its published checksum to a temporary directory.
# Verify before replacing the currently installed binary.
sha256sum --check pb_SHA256SUMS
install -m 0755 pb "$install_dir/pb"

• Do not require administrator access. The tool owns only its user-level binary and application directories.
• Do not replace a working binary before verification. Stage and verify the new release, then rename it into place.
• Rate-limit update checks. Cache the last check and let users choose automatic, prompted, or manual upgrades.

The core sync function should return structured states rather than only printing Git output. That keeps the command interface honest about whether it synchronized, stayed local, or produced a conflict.

func Sync(ctx context.Context, entry JournalEntry) (SyncResult, error) {
    if err := repo.RequireCleanWorktree(ctx); err != nil {
        return SyncResult{}, err
    }

    remote, err := repo.Fetch(ctx)
    if err != nil {
        return SyncResult{State: LocalOnly}, err
    }

    relation := repo.Compare(entry.LastSyncedCommit, remote.Head)
    switch relation {
    case Unchanged:
        return SyncResult{State: Synchronized}, nil
    case LocalAhead:
        return repo.Push(ctx)
    case RemoteAhead:
        return repo.FastForward(ctx, remote.Head)
    case Diverged:
        conflictPath, err := repo.PreserveConflictCopy(entry.Path)
        if err != nil {
            return SyncResult{}, err
        }
        return repo.MergeWithConflictPath(ctx, remote.Head, conflictPath)
    default:
        return SyncResult{}, ErrUnknownHistory
    }
}

1. Test offline first. Every local command works when DNS, GitHub, or authentication is unavailable.
2. Interrupt every write. Kill the editor and process during snapshot, journal, commit, fetch, merge, and upgrade operations.
3. Simulate divergence. Edit the same file on two machines and verify that neither version disappears.
4. Protect path boundaries. Reject traversal, symlink escape, reserved names, and writes outside the managed root.
5. Verify permissions and redaction. Inspect created files, subprocess arguments, and diagnostic logs.
6. Make every state visible. Users can distinguish dirty, recovered, local-only, synchronized, and conflicted snippets.