How do I install acct?

Run `npm install -g acct-sh`, then `acct` for the command list. Create a profile with `acct init` (--id, --user, --email, --name, --bind). Add a shell hook with eval "$(acct hook zsh)".

Does acct replace gh auth switch?

Yes for directory-scoped work. acct injects GH_TOKEN from the OS keychain for the bound profile and does not call gh auth switch. Git HTTPS uses git-credential-acct; identity uses includeIf.

Where are tokens stored?

In the OS keychain via @napi-rs/keyring (macOS Keychain, Windows Credential Manager, Linux Secret Service / libsecret). CI hosts may set ACCT_SECRET_BACKEND=file for an explicit plaintext secrets.json opt-in.

How do I diagnose conflicts?

Run `acct doctor` (add --online to verify ambient GH_TOKEN against the cwd profile). It scans credential helpers, install blocks, orphan bindings, sticky tokens, and keyring availability.

acct

Switch GitHub accounts by folder. Automatically.

Bind a directory to a GitHub user, email, and token. Open that folder and you are that account. Leave it and that identity is gone. No global switch. No wrong-account pushes.

See how it works

$ cd ~/Work/api$ acct statuscwd: /Users/you/Work/api
reason: binding
enforce: strict
binding: /Users/you/Work
profile: work
github: your-work-user@github.com
identity: Your Name <you@company.com>
protocol: https
token: present (keychain)
auth principal: your-work-user

Install

Three steps to folder-scoped GitHub accounts.

Install the CLI, bind a folder to a profile, then add the shell hook so every new terminal picks up the right account from your current directory. Full command reference.

01 · Install
$ npm install -g acct-sh
$ acct

02 · Init + bind
$ acct init \
  --id work \
  --user your-work-user \
  --email you@company.com \
  --name "Your Name" \
  --bind ~/Work

03 · Hook + verify
$ eval "$(acct hook zsh)"
$ cd ~/Work/some-repo
$ acct status
$ acct whoami

The problem

Multiple GitHub accounts on one machine is easy to get wrong.

Work in ~/Work, personal in ~/Personal. Without folder-scoped identity, git and gh keep using the last account you switched to. That is how commits and pushes leak across jobs.

No manual account switching.No silent wrong-account push.

Git config is not login

Setting user.name and user.email only changes the commit stamp. Pushing still uses whatever credentials are active, so you can author as one person and authenticate as another.

gh auth switch is global

Switching accounts in the GitHub CLI affects your whole machine. Open a personal repo after a work day and you can still be on the wrong account.

Credentials ignore your folders

HTTPS helpers usually key off the host (github.com), not which project directory you are in. Two people on the same host look the same to git.

SSH offers every key

Your agent will try keys until one works. Without locking identity to a folder, the wrong key can win.

How it works

Enter a bound folder.
Your GitHub account switches with you.

Each path maps to one profile. Longer paths win. Leave the tree and that account stops applying.

cwd

~/Work/api

bound · local wins

profile

work

user.email → you@company.com

auth

GH_TOKEN · work · keychain

Inside ~/Work, the same tools use your work account instead. No manual switch.

$ cd ~/Work/api$ acct whoamiexpected=your-work-user actual=your-work-user email=you@company.com

What acct controls

Everything that can leak a GitHub identity across folders.

One tool keeps commit author, push credentials, SSH key, and gh aligned to the directory you are in.

Git identity

Sets the right name and email for commits inside each bound folder, so work and personal authorship stay separate.

HTTPS push / pull

Serves the token for this folder's GitHub account. If nothing matches, it refuses instead of falling back to the wrong credentials.

SSH

Uses only the SSH key for the active profile, so the agent cannot authenticate you as someone else.

GitHub CLI (gh)

Points gh at the same account as the folder. You do not need gh auth switch when you change directories.

Guards

Optional hooks stop commits and pushes when the email or GitHub user does not match the bound profile.

How it chooses

1. Explicit profile override
2. Repo-local .acct file
3. Longest matching folder bind
4. Unbound (no acct identity)

More specific paths always beat broader ones.

Releases

What shipped.

Live from the project changelog. Latest on npm is acct-sh@0.1.11.

all releases

v0.1.11latest

Aug 13, 2026

Added

HTTPS / GH_TOKEN follow gh auth token --hostname --user automatically (no gh auth switch). After gh auth refresh, acct status, the shell hook, and git HTTPS pick up the new token without acct profile token --import-gh. --stdin PATs set followGh: false so they are not overwritten. Disable with ACCT_FOLLOW_GH=0 or ACCT_SECRET_BACKEND=file. Tests force follow-gh on the file backend with ACCT_FOLLOW_GH=1. Cite: gh auth token.
Testing strategy: behavior tests spawn real bins against a fake gh on PATH; diagnosis flags are checked against tests/fixtures/gh-auth-flags.json (GitHub CLI manuals), not against src/. See docs/testing.md.

Fixed

Diagnosis fix commands match current gh flags: switch --hostname --user, refresh --hostname (no --user; active account only), login --hostname --web (no --user). Never gh auth login --user (gh auth login; switch; refresh).

Releases

FAQ

Common questions, plain answers.

Every flag is on the command reference. Deep rules: invariants and threat model.

Keep work and personal GitHub accounts
tied to the right folders.

Install once, bind your trees, and stop switching accounts by hand.

Install steps View on GitHub

acct

Three steps to folder-scoped GitHub accounts.

Multiple GitHub accounts on one machine is easy to get wrong.

Git config is not login

gh auth switch is global

Credentials ignore your folders

SSH offers every key

Enter a bound folder.Your GitHub account switches with you.

Everything that can leak a GitHub identity across folders.

Git identity

HTTPS push / pull

SSH

GitHub CLI (gh)

Guards

What shipped.

Common questions, plain answers.

What does acct actually do?

How is this different from gh auth switch?

Where are tokens stored?

What if I open a folder that is not bound?

Which shells work?

What does LEAK RISK / token missing mean?

Keep work and personal GitHub accounts tied to the right folders.

Enter a bound folder.Your GitHub account switches with you.

What shipped.

Enter a bound folder.
Your GitHub account switches with you.

Keep work and personal GitHub accounts
tied to the right folders.

Enter a bound folder.
Your GitHub account switches with you.