ferry

Ferries your development setup across user accounts and machines.

---

ferry carries your development setup (dotfiles, agent setup, terminal config, and dependencies) across accounts and machines. Define your configuration once in a git repo; ferry reconciles any machine to match it, and pulls local changes back when you want to harmonise them everywhere.

Install

curl -fsSL https://raw.githubusercontent.com/REPPL/ferry/main/install.sh | bash

Installs the single ferry binary to ~/.local/bin. If that's not on your PATH, the installer prints the one line to add.

Verifying a download

Every released binary carries a signed build-provenance attestation, so you can confirm it was built by ferry's release workflow from this repository before you trust it. Download a binary from the Releases page, then verify it with the GitHub CLI:

gh attestation verify ferry-darwin-arm64 -R REPPL/ferry

A successful check prints the verified provenance; a missing or mismatched attestation fails the command, so a tampered or unofficial binary never passes.

Quickstart

# On a machine whose setup you want to capture:
ferry init            # first-run setup; starts a config repo at ~/.config/ferry/repo
ferry capture         # review local config and pull it into the repo
git -C <repo> push    # share it

# On another machine:
ferry init <repo-url> # clone your config repo over HTTPS, set this machine up
ferry apply           # reconcile this machine to the repo

See Getting started for the full happy path.

Documentation

The documentation follows Diátaxis; the map is in docs/README.md.

• Getting started: zero to a working setup
• Configuration: the manifest, scope, and the .local layer
• Commands: the command overview, backed by the generated per-command CLI reference
• The agents domain: one set of AI-agent instructions (CLAUDE.md, AGENTS.md, skills, hooks) carried across machines and coding CLIs — with how-tos to scaffold a repo and adopt existing agent config
• SSH: how ferry treats SSH (hands-off), and how to move keys yourself
• Compatibility: which surfaces are stable, the pre-1.0 rule, and how on-disk state is versioned
• Cutting a release: how releases are built, checksummed, attested, and pruned

Principles

• Declarative: a dependency manifest and config are the single source of truth; ferry reconciles the machine to match.
• Selective, both ways: a per-machine manifest declares what ferry manages, so off-scope things (a one-off font, an experimental colour scheme) are never synced. Machine-specific settings live in a gitignored .local layer that always wins, so deliberate per-machine differences are never overwritten.
• Reversible: every change is backed up first; ferry restore returns your managed files and terminal settings to their pre-ferry state. It keeps ferry's own backup store so the restore is itself reversible; ferry restore --purge-without-recovery additionally removes that store (irreversible). A fresh ferry init adopts your existing ~/.zshrc, and apply refuses to replace a substantial file with an empty or blank one without --force, so your config is never silently erased.
• No admin assumed: ferry installs to ~/.local/bin and never requires sudo or root, so it works on any account, including locked-down or managed machines. It never edits your shell on its own.
• Safe with secrets: ferry never touches ~/.ssh/. SSH keys and other secrets are handled out-of-band and never committed. See SSH.