Setup commands
Commands that set up a repo pair, log in, check the setup and take it off this machine.
Setting up a repo pair, logging in, checking that everything works, keeping the overlay current, and removing the pair again. Each card shows the command’s own help: ghostbranch <command> --help prints the same. Every command also takes the global flags.
ghostbranch init [<owner/repo>] [flags]init creates <owner/repo>-shadow as a private repo (or adopts an existing one with --adopt), mirrors the public repo's branches and tags into it, and creates the "ghostbranch" overlay branch, which holds .ghostbranch.yml and is the shadow repo's default branch. It never writes to the public repo. Running it again resumes a partial setup. Run by a person at a terminal with an answer missing, it asks: the public repo (from origin), a login if there is none, the shadow repo, the push guard (in a clone of the public repo) and scheduled sync. It shows the --plan preview, then runs init, guard install and doctor, and ends with how to start a first feature. Flags answer the questions; --json, --non-interactive and --yes never ask.
| Flag | Value | Default | Description |
|---|---|---|---|
| --adopt | — | — | take over an existing, empty or mirror-only, private repo |
| --guard | — | — | install the push guard in this checkout, a clone of the public repo, after init |
| --no-guard | — | — | don't install the push guard, and don't ask |
| --no-sync | — | — | leave scheduled sync off, and don't ask |
| --plan | — | — | preview exactly what would change, and change nothing (same as --dry-run) |
| --shadow | <string> | — | shadow repo name (default <owner/repo>-shadow) |
| --sync | — | — | turn on scheduled sync in the new overlay (sync.schedule "23 */6 * * *", about 120 Actions minutes a month) |
| --yes | — | — | never ask: use the flags given and the defaults |
More in Set up a repo.
upgrade
Section titled “upgrade”ghostbranch upgrade [flags]upgrade compares the overlay branch's managed files (today the opt-in sync workflow) with this version's templates and .ghostbranch.yml, then adds, updates or removes them in one overlay commit. Turning scheduled sync on or off is: edit sync.schedule, then run upgrade. A file someone edited by hand is replaced; --plan shows that first. It writes only the shadow repo's overlay branch, then runs the audit.
| Flag | Value | Default | Description |
|---|---|---|---|
| --plan | — | — | preview exactly what would change, and change nothing (same as --dry-run) |
| --yes | — | — | accepted for consistency; upgrade never asks |
More in Setting up CI.
ghostbranch auditaudit reads the workflows the shadow repo's CI runs and reports repo guards (jobs that skip in the shadow repo), referenced secrets and which are missing (when the token may list them), workflows a sync starts in the shadow repo and the guard that stops them, billed Actions minutes, and whether Ghostbranch's managed overlay files are current. It changes nothing.
More in Setting up CI.
doctor
Section titled “doctor”ghostbranch doctordoctor runs six checks, in order: tools (git and this binary), token (its source, account, expiry, whether it can publish, and the permissions each command group needs), pair (both repos, the overlay and its config, shadow main, the managed files), guard (the pre-push hook in this checkout), state (this machine's records) and ci (the audit's summary). Each is ok, warn, fail or skipped, and names the command that fixes it. It changes nothing in your repos, records or keychain and never prompts; it fetches into its local copy of the pair (making it if needed) and refreshes the update check's cache. It isn't ledgered. In a checkout of a pair it checks that pair; --repo names another; with neither it skips the checks that need a pair. It exits 0 unless a check fails (DOCTOR_FAILED, details.failed).
More in ghostbranch doctor.
ghostbranch login [flags]login runs GitHub's device flow for the Ghostbranch GitHub App: it shows a code and a URL on the console, opens the browser when it can, and waits while you approve. The token reaches only the repos you install the app on, refreshes itself, and is kept in the OS keychain (never in a file). With --with-token it reads one token from stdin instead (never from an argument, so it stays out of shell history), checks it with GitHub, and stores it. GHOSTBRANCH_TOKEN, when set, still wins over the stored login.
| Flag | Value | Default | Description |
|---|---|---|---|
| --with-token | — | — | read a token from stdin and store it |
More in Log in.
logout
Section titled “logout”ghostbranch logoutlogout removes the login that ghostbranch login stored in the OS keychain, a corrupt one included. It can't revoke the token at GitHub (that needs the app's client secret, which Ghostbranch doesn't ship); for a GitHub App login it gives the page where you revoke the app's access. Environment tokens (GHOSTBRANCH_TOKEN, GH_TOKEN, GITHUB_TOKEN) are untouched.
More in Log in.
auth status
Section titled “auth status”ghostbranch auth statusauth status shows where the token comes from (GHOSTBRANCH_TOKEN, the stored login, GH_TOKEN, GITHUB_TOKEN or gh), its account and kind, whether it can publish to this checkout's pair (or --repo), and the stored login. Offline, it still shows the stored login. With GHOSTBRANCH_TOKEN set it doesn't read the keychain at all. A stored login near expiry is refreshed first, as any command would.
More in Log in.
remove
Section titled “remove”ghostbranch remove [flags]remove takes the pair off this machine: it revokes the pair's agent grants and waivers, deletes its plan files and its local mirror, and drops it from the workspace. Nothing on GitHub changes: the shadow repo, its branches and features stay, and the ledger keeps its history. Because it drops grants and waivers, a person confirms by typing a code at the console; --plan shows what would go. It needs no GitHub token.
| Flag | Value | Default | Description |
|---|---|---|---|
| --plan | — | — | preview exactly what would change, and change nothing (same as --dry-run) |
More in Removing a repo.
version
Section titled “version”ghostbranch versionversion prints this binary's module version and VCS commit, and the JSON contract version it speaks. ghostbranch --version does the same.
More in Upgrading Ghostbranch.