0.2.0 • Published yesterdayCLI

arbella

Licence

AGPL-3.0-only

Version

0.2.0

Deps

Size

1.2 MB

Vulns

Weekly

Stars

Summary Dependency Versions

Arbella

Set up your AI coding tools once. Rebuild that setup on any machine.

Backup and migration for your Claude Code, Codex, Cursor, opencode, Copilot CLI, Kilo Code, and Antigravity setup — skills, subagents, plugins, hooks, settings, memories — into a private Git repo you own.

Quick start · Commands · How sign-in works · Secrets

The problem

You've spent months tuning Claude Code or Codex — custom skills, a stack of subagents, plugins, hooks, your CLAUDE.md. Then you get a new laptop and do it all again from scratch.

Arbella saves that whole setup into a private Git repo and puts it back on another machine with one command. Linux, macOS, Windows.

Quick start

arbella setup       # install what arbella leans on (git, gh, the tool CLIs)
arbella init        # point it at a private repo, pick your options
arbella push        # snapshot your setup and push it

# later, on another machine:
arbella pull https://github.com/you/your-setup

Install

Needs Node 18+.

npm install -g arbella
arbella --help
arbella update   # later: update arbella itself

What it does

  push   ~/.claude · ~/.codex · Cursor   ──▶   strip · template   ──▶   private repo
  pull   private repo                  ──▶   install · place    ──▶   tools + Cursor User data

push reads the parts of your setup that matter, strips anything secret, swaps machine-specific paths for placeholders, and pushes the result to your repo. pull does the reverse: installs the CLIs you don't have, drops files back with this machine's paths, reinstalls plugins and skills, and wires shared Claude/Codex instructions back into CLAUDE.md and AGENTS.md.

Two things it deliberately won't do:

Never commits secrets. API keys, OAuth tokens, auth.json, .credentials.json — all excluded, no exceptions. You sign back in after a pull, or carry them yourself with arbella secrets.
Doesn't copy what it can reinstall. Plugins and registry skills are saved as a list and pulled fresh, so the repo stays small and never goes stale.

Supported today: Claude Code, Codex, Cursor (IDE + the cursor-agent CLI), opencode, GitHub Copilot CLI, Kilo Code, and Google Antigravity. Cursor support covers global MCP config, user settings, keybindings, snippets, local skills, skills.sh symlinks, the cursor-agent CLI config + global commands, and extension IDs; runtime state and credentials stay out. opencode, Copilot CLI, and Kilo are config-dir CLIs — Arbella captures each one's config dir (the JSON/JSONC config, custom agents/commands, MCP config), strips token-shaped values, and skips machine-local state, plugin install artifacts, and reinstallable skills (regenerated from the config on first run). Antigravity spans three roots — its VS Code-style User settings, the ~/.antigravity extension list, and the shared ~/.gemini agent config (global rules, MCP servers, skills) — while its Google OAuth tokens never leave your machine.

Commands

Command	What it does
`arbella setup`	Install git, the provider CLIs, and the AI tool CLIs
`arbella init`	One-time wiring: pick a repo and your options
`arbella push`	Snapshot your setup and push it — the everyday one
`arbella pull <url>`	Rebuild your setup on a fresh machine
`arbella status`	Show what a push would change — read-only
`arbella update`	Update arbella itself through npm
`arbella auth`	Sign in to your repo host
`arbella secrets`	Move credentials between machines, off Git

Every prompt has a flag, so anything interactive can be scripted. --dry-run works wherever it makes sense.

`arbella setup`

Checks what's installed and offers to fill the gaps — a checklist, so you tick what you actually use.

arbella setup                   # interactive checklist
arbella setup --all             # everything, no prompts
arbella setup --deps git,gh -y  # just these

Covers git (required), gh / glab (handle sign-in for you), and the AI CLIs (claude, codex, cursor, opencode, copilot, kilo).
Installs through your system's package manager: apt, dnf, or pacman on Linux, Homebrew on macOS, winget on Windows.
init and pull also install on demand — if something's missing when you run them, Arbella stops and asks first.

`arbella init`

The one-time wiring. Pick a host (GitHub, GitLab, or a plain Git URL); if the repo doesn't exist yet, Arbella creates it private for you.

arbella init
arbella init --provider github --repo you/your-setup --auto-push daily -y

Saves your preferences:

which tools Arbella should manage
who wins a conflict — your machine or the repo
auto-push cadence — off, once per session, or daily
whether secrets are allowed into the repo (off by default), and whether to include memories (also off)

`arbella push`

The one you'll run most. Captures your current setup, sanitizes it, commits, and pushes. Run it whenever you've changed something worth keeping, or let the auto-push hook do it in the background.

arbella push
arbella push --dry-run   # show exactly what goes in (and what's skipped), write nothing

Worth a --dry-run before your first real push, so there are no surprises.

`arbella pull`

The reason the whole thing exists.

arbella pull https://github.com/you/your-setup
arbella pull <url> --dry-run

First copies your current ~/.claude and ~/.codex to a timestamped safety folder, so a pull can't quietly wreck what's already there.
Installs any missing CLIs — reaching for sudo only when the global npm folder actually needs root.
Writes files with this machine's paths, then reinstalls your plugins and skills from the manifest.
Deploys your shared instructions to CLAUDE.md and AGENTS.md.
Reminds you to sign back in at the end, since no credentials came along for the ride.

`arbella status`

Read-only. It answers one question: if you ran push right now, what would change?

arbella status
arbella status --json   # pipe it somewhere

New and modified files, plugin drift, the secrets it would skip. Writes nothing, installs nothing.

`arbella update`

Updates the Arbella CLI package itself. It does not touch your backed-up Claude, Codex, or Cursor setup.

arbella update                  # npm install -g arbella@latest
arbella update --version 0.1.2  # pin a specific release
arbella update --dry-run        # show the npm command only

`arbella auth`

Handles sign-in to your repo host. You rarely call it yourself — push and pull sign in on their own when they hit a private repo. It's here for when you'd rather log in ahead of time, or check where you stand.

arbella auth login
arbella auth status
arbella auth login --provider gitlab
arbella auth login --device-flow   # skip gh/glab, use Arbella's own flow

`arbella secrets`

For the credentials that never belong in the repo. Git is never involved — you carry the blob between your own machines yourself.

arbella secrets export   # encrypted, passphrase-protected blob (AES-256-GCM)
arbella secrets import   # unpack it on the other machine

Short version: gh and glab are preferred, not required. They're the smoothest route, and the one I'd point you to — but Arbella works without them.

Situation	What Arbella does
CLI installed and signed in	Uses it directly. gh/glab already do OAuth properly and configure Git's credentials, so nothing sensitive passes through Arbella.
CLI installed, signed out	Runs its `auth login` for you — prints a URL and a code you type into your browser.
CLI missing	Offers to install it, or falls back to its own path: an OAuth device flow, or a pasted token kept in a local `0600` file.

For the device flow, point Arbella at your own registered OAuth app with ARBELLA_GITHUB_CLIENT_ID (or ARBELLA_GITLAB_CLIENT_ID). There's no sensible default to ship — the client ID is public but tied to your account — so with none set, Arbella skips the device flow and asks for a token instead. SSH and file:// remotes are left alone, so those keep working however your Git already has them.

Secrets

This is the part I most wanted to get right.

Whole credential files (auth.json, .credentials.json, and the like) sit on a hard denylist and are never read into the repo.
Everything that does get committed runs through a sanitizer that redacts token-shaped values.
Any token Arbella holds for itself lives in one local file with 0600 permissions — not in the repo, not in a logged command, not baked into a Git remote.
A test fails the build if a credential can reach the repo. This isn't on the honor system.

Putting secrets in the repo is opt-in, and the default is off. It's your private repo and your call — but I'd leave it there.

Cross-platform notes

Paths get templated, so a setup captured on a Mac under /Users/you restores correctly on Linux under /home/you, or on Windows. The one place the machine matters is global npm installs: on a system Node the folder is root-owned, so Arbella elevates with sudo and tells you it's doing so; on nvm, Homebrew, or Windows it's already yours, so it skips sudo. It checks first instead of guessing.

Why "Arbella"

The Arbella was the flagship of the 1630 Winthrop Fleet — a few hundred settlers, their livestock, and the colony's founding charter, carried across the Atlantic to start over somewhere new. That's the idea here: pack up the things that make your environment yours, carry them across, and unpack on the other side.