Know before your gcloud
session expires.

The dot tells you two different things

And it never lets you mistake one for the other.

Red is always a fact. It appears only after a real gcloud command has come back refusing the credential. A dropped network never turns the dot red, because "I could not reach Google" is not the same as "you are signed out", and a dot that cries wolf is a dot you learn to ignore.

The countdown is always an estimate, and the app says so everywhere it shows one. Google does not publish your session deadline to your machine, so there is nothing to read. It has to be learned.

How it works

Two mechanisms. The interface always says which one it is quoting.

Where the numbers come from

The moment a session ends is never observed exactly; it happens somewhere between the last check that succeeded and the first that failed. GCloud Dot records the midpoint of that interval rather than the failure, which halves the error instead of overstating every session by one full polling interval. As the predicted expiry approaches it also polls more often, so the measurement that trains the next estimate is the most accurate one it takes.

On the machine this was built against, eighteen observed sessions landed between 15.91h and 16.08h, converging, without being told, on Google's documented sixteen-hour default.

It reads your login history from gcloud's own logs

gcloud writes a log for every command it runs. GCloud Dot looks for completed gcloud auth login invocations to find when your current session began, and rescans once a minute, so signing in from any terminal, on any tab, resets the countdown within a minute without you telling the app anything.

It also watches the credential that actually breaks your code

Application default credentials expire on their own schedule.

The most confusing failure in local GCP development is the one where gcloud works perfectly and your program does not. That is almost always application default credentials, which are a separate credential with a separate lifetime and no visible indicator anywhere. GCloud Dot tracks them alongside your login and reports them separately, so the answer takes a glance instead of half an hour.

It will also tell you when a service account key file has been sitting unrotated for months, reported honestly as the file's age, since a downloaded key carries no creation date to read.

There is a command, too

The same engine, for prompts, scripts, and machines with no desktop.

$ gcloud-dot
🟢 signed in, about 14h 12m left (measured, n=18)
  account       nic@glazkov.com
  project       my-project
  configuration default
  last login    Fri Aug 8, 06:31 (2h ago)
  est. expiry   Fri 22:33, 14h 12m left
  session       16.1h (measured, n=18)

Exit codes are part of the interface (0 signed in, 1 signed out, 2 unknown), so a shell prompt or a CI step can branch on it without parsing anything. --json gives a stable document including estimate_is_measured, so anything consuming it can tell a measurement from a guess.

Updating is one command as well, and it picks the right route for how you installed it.

$ gcloud-dot upgrade
Upgraded from 1.1.10 to 1.1.11.

Questions