The problem

user.name / user.email are not auth.
gh auth switch is global.
HTTPS credentials are host-scoped by default.
SSH agents offer every key unless you force IdentitiesOnly.

Cross a directory boundary and you can silently push as the wrong person.

Official gh documents that automatic switching by directory is out of scope.
acct owns that gap.

The invariant

One GitHub account + one git identity + one directory tree.
Local supersedes global. Outside a bound directory, that account does not exist for acct-managed operations. When constraints fail and enforcement is on — block.

Install

npm install -g acct-sh

Install prints next steps when scripts are visible (--foreground-scripts). Otherwise run acct after install for the same tip sheet. Skip with ACCT_SKIP_POSTINSTALL=1.

Also on GitHub Packages as @abdull-ah-med/acct-sh (same bins).

Quick start

# In this folder: step-by-step (echoes each field, confirms at the end)
acct
# or: acct init

# Shell hook (zsh)
eval "$(acct hook zsh)"

# Inside the bound tree
cd ~/Work/some-repo
acct status
acct whoami
acct doctor          # conflict scan — run this first when something feels off

Walk into ~/Work → work account.
Walk out → that identity is gone.

Trust check: acct doctor / acct status

When something is off (token: missing, LEAK RISK, identity mismatch, wrong gh active account), acct status and acct doctor explain:

1. What's wrong — the specific cause, not a generic guess
2. Commands to run (cause-specific: cd into a repo, git config --local --unset-all user.*, acct install, gh auth switch --hostname … --user …, gh auth refresh --hostname …, …)
3. Whether commit / push will go through — and whether they would use the wrong GitHub account

Standing in a binding directory that is not a git repo is not an identity error (includeIf gitdir only matches inside repos). acct does not run gh auth switch (that is global). Status prints gh active from stored gh config separately from the profile principal; use acct exec / the shell hook, or switch only if you want raw gh to follow that account everywhere.

In strict mode a missing profile token or a mismatched gh principal blocks push. A commit still uses includeIf user.name / user.email (not gh), so it will not pick up the other GitHub login. Raw gh without acct exec can still be the wrong user — that's the leak risk.

acct status            # cwd dump + diagnosis when unhealthy (exit 1)
acct doctor            # helper/keychain scan + the same cwd diagnosis
acct doctor --online   # also verify ambient GH_TOKEN vs cwd profile via gh api

Doctor also reports credential-helper competition, missing install blocks, orphan bindings, sticky GH_TOKEN, enforce fallthrough, and whether the native keyring backend loads on this machine. Exit code 1 if any error findings.

What it wires

| Plane | What acct does | |-------|------------------| | Identity | includeIf git config — user.name / user.email per directory | | HTTPS | git-credential-acct returns this profile’s token; quit=true on strict failure | | SSH | core.sshCommand with IdentitiesOnly=yes | | gh | Injects GH_TOKEN from the OS keychain — no gh auth switch | | Enforce | pre-commit / pre-push hooks in strict mode |

Resolution order

1. CLI --profile (explicit; gh plane / status)
2. Repo-local .acct
3. Longest matching directory binding
4. Unbound

Local always beats global. Ambient ACCT_PROFILE does not override git credential helper or hooks — directory wins.

Commands

Full reference (every command, flag, and example): acct-web.vercel.app/docs

acct --help

| Command | Purpose | |---------|---------| | acct init | Profile + binding + install | | acct profile add\|list\|show\|remove\|token\|ssh-key | Profiles | | acct bind / unbind | Directory → profile | | acct status / whoami | Current resolution; status explains problems + fix + commit/push impact | | acct doctor | Conflict / keychain scan + cwd diagnosis when unhealthy | | acct exec -- <cmd> | Run with correct GH_TOKEN | | acct clone <url> | Clone under current profile env | | acct enforce strict\|warn\|off | Enforcement mode | | acct hook bash\|zsh\|fish\|powershell | Shell integration | | acct install / uninstall | Wire / remove git includeIf + hooks |

Platforms & OS keychain

Tokens are stored via @napi-rs/keyring (native bindings). Behavior differs by OS:

| OS | Backend | Notes | |----|---------|--------| | macOS | Keychain | Primary test target. CI: macos-latest (unit + e2e). | | Linux | Secret Service via libsecret (GNOME Keyring / KWallet) | Unit + e2e in CI (ubuntu-latest) use ACCT_SECRET_BACKEND=file. Headless/CI hosts often lack a session keyring — prefer the file backend there, or unlock a Secret Service session for keyring mode. | | Windows | Credential Manager | Unit tests in CI (windows-latest). Keychain UX differs from macOS; run acct doctor after install. |

Tested in CI: Node 20 + 22 × Ubuntu / macOS / Windows (lint, unit, package). Security regression + directory e2e on Ubuntu and macOS with ACCT_SECRET_BACKEND=file. Live keychain writes are exercised on developer macOS; treat Linux/Windows keyring paths as supported via the native module but less battle-tested in the wild.

Explicit opt-in for plaintext storage (CI / locked-down hosts):

export ACCT_SECRET_BACKEND=file   # → ~/.config/acct/secrets.json (0600)

Security

• Tokens live in the OS keychain by default — never in config.yaml. HTTPS and acct exec follow gh auth token --hostname --user for that profile (no gh auth switch), so gh auth refresh is enough; you do not need to re-run acct profile token --import-gh. A PAT stored with --stdin is not overwritten (followGh: false). Set ACCT_FOLLOW_GH=0 to disable.
• Credential helper rejects empty / non-allowlisted hosts
• Bound profiles reset competing helpers, then install acct only
• Shell hook rebinds from cwd (ignores sticky ACCT_PROFILE) and clears tokens when unbound

See threat model and invariants.

How it feels

~/Personal/blog     →  personal · commits as you@home
~/Work/api          →  work     · commits as you@company · work token only
~/Downloads         →  unbound  · acct does nothing / strict blocks managed ops

No global flip. No “forgot to switch.” No silent wrong-account push.

Agent / contributors

For coding agents discovering this package: start at the website LLM index —

• https://acct-web.vercel.app/llms.txt
• https://acct-web.vercel.app/llms-full.txt
• https://acct-web.vercel.app/agents.md

Read AGENTS.md in the repo.
Verify primary docs in SOURCE_OF_TRUTH.md before changing auth behavior.
How we test: docs/testing.md.

License

MIT