This article was last modified on . Some content may be outdated. Feel free to ask the author if you have questions.
AI TranslationSimplified ChineseEnglish
Summary:
gas (Grok Account Switch) is a lightweight CLI for managing multiple Grok CLI logins on a single machine. It snapshots ~/.grok/auth.json into numbered profiles and lets you switch with a single command like gas sw or gas to, similar in concept to Claude Code's ccs.
gas (Grok Account Switch) is an open-source command-line tool for managing multiple Grok CLI logins on the same machine. Grok writes the current session to ~/.grok/auth.json; gas snapshots that file into numbered accounts and lets you switch with a single command—work account, personal account, experimental account—no more repeated logout / login.
The reason is specific: I use Grok for both personal projects and everyday agent sessions, and I have more than one account. Grok CLI pins the session to that single file at ~/.grok/auth.json—to switch accounts, you have to logout and then login, go through device authorization in the browser, and you risk messing up running sessions along the way.
Claude Code already has ccs, a local multi-account switcher with a clean philosophy: don't meddle with login, just manage "which credentials are active." Grok had no equivalent tool at the time, so I built gas following the same product pattern.
I deliberately kept the scope tight:
Don't touch the login flow—login still goes through the official grok login, gas only handles snapshots and switching
Credentials stay local—all files live in ~/.grok-switch/, no uploads, no relays
Leave room for agents—fixed install path, gas exec uses an isolated GROK_HOME so multiple agents don't fight over the same live auth
Switching is revertible—locking, atomic writes, failure recovery. Only then would I trust it for daily back-and-forth switching.
I built it together with Grok, then added tests and an install script. For me it's first and foremost a tool that solves my own pain point; open-sourcing it is a hope that other people juggling multiple Grok CLI accounts won't have to reinvent the wheel.
Why You Need It
Grok CLI only maintains one "current login" by default. Multi-account scenarios are common:
You need both a work account and a personal account
Different projects want isolated usage or permissions
When writing scripts or running agents, you want to execute with a specific account without changing the global session
Manually switching accounts is costly: log out → log back in → switch again. gas turns that into:
BASH
gas sw # Rotate to the next account
gas to work # Jump to the configuration named work
gas to 2 # Switch by index number
Grok hot-reloads auth.json, so in most cases you don't need to restart the TUI after switching.
What It Does and Doesn't Do
Does:
Capture current logged-in session (gas add), save it to a local archive
List, rotate, and switch accounts by number, email, or alias
Optional: directory → account mapping (auto-switch when entering a project directory)
Optional: run commands with an isolated GROK_HOME, leaving the global session untouched (gas exec)
Status check, usage stats, dry run (gas -n sw)
Doesn't do:
Won't handle the login flow—login still goes through the official grok login
Won't upload tokens to any server; all archives stay local at ~/.grok-switch/
Not an xAI official tool; if Grok CLI's auth format changes, adaptation may be needed
Note
The command name is gas, not gss. Many shells treat gss as an alias for git status -s.
How It Works (Simplified)
Directory responsibilities are roughly as follows:
TEXT
~/.grok/auth.json # The current active Grok session
~/.grok-switch/
sequence.json # Account index, rotation order, statistics
accounts/<n>/auth.json # A backup of each account
dir-accounts.json # Optional path-to-account mapping
isolated/ # Isolated home used by gas exec
Each time you switch, gas does:
Acquire an exclusive lock (.switch.lock) to prevent concurrent writes from corrupting state
Use your current live email to locate your slot in the archive
If the current login isn't in the managed list yet, refuse to switch (run gas add first)
Write the live token back to the current slot, then atomically write the target slot back to auth.json (permissions 600)
Update stats; on failure, roll back live auth and sequence
In other words: switching is a local file operation of "back up current → restore target," no third parties involved.
Installation
Requires Python 3.9+. Grok CLI is only needed when you log in; gas itself doesn't depend on it to run.
git clone https://github.com/pintaste/gas.git
cd gas
./install.sh
Installed by default to ~/.local/bin/gas, make sure that directory is in your PATH. Minimum acceptance test for coding agents:
BASH
curl -fsSL https://raw.githubusercontent.com/pintaste/gas/main/install.sh | bash
export PATH="${HOME}/.local/bin:${PATH}"
command -v gas && gas version # Expected output: gas 0.1.0
Warning
Do not print or commit token files from ~/.grok/ or ~/.grok-switch/. Archives are session credentials.
Quick Start
When Grok is already logged in:gas add (captures the current session only, won't log you out)
Log in to a second account:grok logout && grok login
Run again:gas add
Switch anytime after that:
BASH
gas sw # Rotate to the next account
gas to 1 # By index number
gas to you@email.com # By email
gas to work # By custom alias
Give accounts memorable names:
BASH
gas profile 1 work
gas profile 2 personal
gas ls # * / (active) marks the current account
Command Reference
Command
Description
gas add
Add or refresh current login
gas ls
List managed accounts
gas sw
Rotate to the next account
gas to <id>
Switch by number, email, or alias
gas profile <id> <name>
Set a friendly name
gas rm <id>
Remove a saved account (doesn't affect live auth)
gas dir [path] <id>
Map a directory to an account
gas auto
Switch based on current directory mapping
gas exec <id> -- <cmd>
Execute a command isolated under that account
gas config-dir <id>
Materialize an isolated home, prints export GROK_HOME=...
gas check
Verify backups, permissions, JSON
gas status / gas whoami
Current account and token status
gas stats
Switch count / usage time per account
gas -n sw
Dry run — shows who you'd switch to
Old aliases still work: gas save, gas use, gas list.
Advanced: Auto-Switch by Project, Parallel Sessions Without Conflicts
Directory mapping is ideal for "use the work account when you enter this repo":
BASH
gas dir ~/work/acme 1
cd ~/work/acme
gas auto
Isolated execution is suited for agent/CI/parallel tasks—it doesn't touch the global auth.json:
BASH
gas exec 2 -- Example: grok -p "hello"
# Or get the isolated home and then export it as:
eval "$(gas config-dir 2 | tail -1)"
Environment Variables (optional):
Variable
Default
Description
GAS_HOME / GSS_HOME
~/.grok-switch
Archive location
GROK_HOME / GROK_DIR
~/.grok
Grok config directory
GAS_SILENT=1
—
Quiet mode for scripts
NO_COLOR
—
Disable ANSI colors
Security & Uninstallation
Archives and live auth are both local files; if backup drives, sync drives, or cloud storage clients scan ~/.grok-switch, they'd be syncing login credentials
gas rm only removes the archive slot, won't log you out of current Grok
Uninstall the binary:rm -f ~/.local/bin/gas; to also clear session archives: then rm -rf ~/.grok-switch
Tests use a temporary directory and won't touch real accounts:
BASH
python3 -m unittest discover -s tests -v
FAQ
What's the difference between gas and editing auth.json directly?
Editing the file directly has no indexing, no locking, no rollback. gas maintains numbered archives, rotation order, failure rollback, and exec isolated paths—designed for daily back-and-forth switching.
Grok didn't switch accounts after using gas?
First run gas whoami / gas status to check if the live email changed. In rare cases you may need to restart the TUI; the docs note that Grok usually hot-reloads auth.json.
Prompt says "current login not managed"?
You just ran grok login into a new session but haven't run gas add yet. Capture it first, then switch.
Can this be used with coding agents?
Yes. The install path is fixed at ~/.local/bin/gas; for parallel tasks, prefer gas exec <id> -- ... to prevent multiple agents from fighting over the same live auth.json.
How does this relate to ccs?
The product shapes are similar: both are "local multi-account switchers." ccs targets Claude Code, gas targets Grok CLI; they're independent of each other.
Summary
If you already use Grok CLI with multiple accounts, gas condenses "log out then log back in" into a few local commands, plus directory mapping and isolated execution. One curl to install, run gas add twice, then jump with gas to, and that's usually enough.
gas (Grok Account Switch) is an open-source command-line tool for managing multiple Grok CLI logins on the same machine. Grok writes the current session to ~/.grok/auth.json; gas snapshots that file into numbered accounts and lets you switch with a single command—work account, personal account, experimental account—no more repeated logout / login.
Repo: github.com/pintaste/gas (MIT). Inspired by ccs / cc-account-switcher on the Claude Code side.
Why I Built This Tool
The reason is specific: I use Grok for both personal projects and everyday agent sessions, and I have more than one account. Grok CLI pins the session to that single file at ~/.grok/auth.json—to switch accounts, you have to logout and then login, go through device authorization in the browser, and you risk messing up running sessions along the way.
Claude Code already has ccs, a local multi-account switcher with a clean philosophy: don't meddle with login, just manage "which credentials are active." Grok had no equivalent tool at the time, so I built gas following the same product pattern.
I deliberately kept the scope tight:
I built it together with Grok, then added tests and an install script. For me it's first and foremost a tool that solves my own pain point; open-sourcing it is a hope that other people juggling multiple Grok CLI accounts won't have to reinvent the wheel.
Why You Need It
Grok CLI only maintains one "current login" by default. Multi-account scenarios are common:
Manually switching accounts is costly: log out → log back in → switch again. gas turns that into:
Grok hot-reloads auth.json, so in most cases you don't need to restart the TUI after switching.
What It Does and Doesn't Do
Does:
Doesn't do:
The command name is gas, not gss. Many shells treat gss as an alias for git status -s.
How It Works (Simplified)
Directory responsibilities are roughly as follows:
Each time you switch, gas does:
In other words: switching is a local file operation of "back up current → restore target," no third parties involved.
Installation
Requires Python 3.9+. Grok CLI is only needed when you log in; gas itself doesn't depend on it to run.
Or from source:
Installed by default to ~/.local/bin/gas, make sure that directory is in your PATH. Minimum acceptance test for coding agents:
Do not print or commit token files from ~/.grok/ or ~/.grok-switch/. Archives are session credentials.
Quick Start
Give accounts memorable names:
Command Reference
Old aliases still work: gas save, gas use, gas list.
Advanced: Auto-Switch by Project, Parallel Sessions Without Conflicts
Directory mapping is ideal for "use the work account when you enter this repo":
Isolated execution is suited for agent/CI/parallel tasks—it doesn't touch the global auth.json:
Environment Variables (optional):
Security & Uninstallation
Tests use a temporary directory and won't touch real accounts:
FAQ
What's the difference between gas and editing auth.json directly?
Editing the file directly has no indexing, no locking, no rollback. gas maintains numbered archives, rotation order, failure rollback, and exec isolated paths—designed for daily back-and-forth switching.
Grok didn't switch accounts after using gas?
First run gas whoami / gas status to check if the live email changed. In rare cases you may need to restart the TUI; the docs note that Grok usually hot-reloads auth.json.
Prompt says "current login not managed"?
You just ran grok login into a new session but haven't run gas add yet. Capture it first, then switch.
Can this be used with coding agents?
Yes. The install path is fixed at ~/.local/bin/gas; for parallel tasks, prefer gas exec <id> -- ... to prevent multiple agents from fighting over the same live auth.json.
How does this relate to ccs?
The product shapes are similar: both are "local multi-account switchers." ccs targets Claude Code, gas targets Grok CLI; they're independent of each other.
Summary
If you already use Grok CLI with multiple accounts, gas condenses "log out then log back in" into a few local commands, plus directory mapping and isolated execution. One curl to install, run gas add twice, then jump with gas to, and that's usually enough.