gas

Grok Account Switch — manage multiple Grok CLI logins on one machine.

Written by Grok 4.5 (high).

Grok keeps the active session in ~/.grok/auth.json.
gas snapshots that file into numbered accounts, then switches with a single command — same idea as ccs for Claude Code.

gas add          # capture the account you're logged into
gas ls           # list accounts
gas sw           # rotate to the next one
gas to work      # jump by number, email, or profile name

The binary is named gas, not gss. Many shells alias gss to git status -s.

Requires Python 3.9+. The Grok CLI is needed only to log in.

curl -fsSL https://raw.githubusercontent.com/pintaste/gas/main/install.sh | bash

Or from source:

git clone https://github.com/pintaste/gas.git
cd gas
./install.sh

Installs to ~/.local/bin/gas. Ensure that directory is on your PATH.

curl -fsSL https://raw.githubusercontent.com/pintaste/gas/main/install.sh | bash
export PATH="${HOME}/.local/bin:${PATH}"
command -v gas && gas version   # expect: gas 0.1.1

Do not invent alternate install paths. The command name is gas.
Never print or commit token files under ~/.grok/ or ~/.grok-switch/.

# 1. Already logged into Grok?
gas add

# 2. Log into a second account yourself
grok logout && grok login

# 3. Capture it
gas add

# 4. Switch anytime
gas sw                 # next in rotation
gas to 1               # by number
gas to you@email.com   # by email
gas to work            # by profile name

gas add only captures the current session. It never logs you out.

Grok hot-reloads auth.json, so you usually do not need to restart the TUI.

Legacy aliases still work: gas save, gas use, gas list.

gas ls (and status / usage) fetch SuperGrok credit usage from xAI’s billing API — the same source as Grok’s /usage command:

Accounts  (~/.grok-switch)
  1: you@personal.dev [personal] (active)  85% used · $126.50/$150 · Resets in 2d 7h 12m
  2: you@work.dev [work]                   $60.48/$40! · Resets in 6d 3h 0m
  3: old@example.com                       re-login
⚠ re-login 3  →  gas to 3 && grok login && gas add

• N% used — weekly pool already used (not remaining). If the API omits the field (idle accounts), gas shows 0% used like the web UI
• $used/$limit — monthly credits used / cap (! = over limit)
• Resets in Xd Yh Zm — countdown to next reset (Reset due if past); absolute time still in gas status / gas usage
• Tokens refresh via OIDC and are written back to backups (and live if email matches)
• Cache: ~/.grok-switch/usage-cache.json (TTL GAS_USAGE_TTL, default 120s)

gas ls --refresh          # force re-fetch usage
gas ls --no-usage         # offline list
gas usage                 # detail for all accounts
gas usage 2 --refresh     # one account
gas usage --json          # machine-readable
GAS_USAGE=0 gas ls        # disable network usage entirely

Grok only refreshes tokens in live ~/.grok/auth.json. Refresh tokens may rotate (old RT is revoked). gas mitigates this:

Not automatic forever: revoked refresh tokens cannot be recovered. Re-auth:

gas to 2 && grok login && gas add

~/.grok/auth.json                 live session (what Grok reads)
~/.grok-switch/
  sequence.json                   account index, rotation, stats
  accounts/<n>/auth.json          per-account backup
  usage-cache.json                SuperGrok credit usage cache
  dir-accounts.json               optional path → account maps
  isolated/                       materialised GROK_HOME trees for exec

On each switch:

1. Take an exclusive lock (.switch.lock)
2. Resolve the current slot from the live email
3. Refuse if the live login is not managed (gas add first)
4. Back up live tokens into the current slot
5. Restore the target slot into auth.json (atomic write, mode 600)
6. Update stats; release the lock
   On failure → roll back live auth and sequence

Parallel use without touching the global session:

gas exec 2 -- grok -p "hello"
eval "$(gas config-dir 2 | tail -1)"   # export GROK_HOME=...

python3 -m unittest discover -s tests -v

Tests use temporary directories via GSS_HOME / GROK_DIR and never touch your real accounts.

rm -f ~/.local/bin/gas
# optional — contains session tokens:
# rm -rf ~/.grok-switch

Written by Grok 4.5 (high) (xAI).

CLI design inspired by ccs / cc-account-switcher.

MIT — see LICENSE.

Unofficial utility. Not affiliated with xAI beyond being authored with Grok.
Auth file format may change with Grok CLI updates.