gws: Every Google Workspace service behind one command line
gws is a free program you download once and then talk to in the command window, to work with every Google service — files, mail, calendar, spreadsheets, documents, chats. Its value is that you do not learn a separate way for each service: you always type "gws", then which service you want, then what you want to do inside it. You do not have to memorise the details either, because the program itself asks Google, at the moment you run it, which options each action accepts, and shows them to you. Its answers are not pictures or prose for reading but structured records with labels, which a person can read and a program can process. It is open source, has no subscription, and is not an officially supported Google product.

What it does
Think of Drive the way you know it: open the browser, click with the mouse, look with your eyes, download a file. gws does the same jobs, but you write them as text, from the command window — the shell, that is, the window where you type commands and press Enter. The difference is not cosmetic. Anything written as text can run again tomorrow, on its own, with nobody in front of the screen.
One example shows its strongest point right away. You want to see what parameters the action that lists your Drive files accepts. You do not hunt through manuals. You type:
gws schema drive.files.list
The tool answers with the shape of that method: what it does, that it sends a read request, and every parameter one by one. Nobody wrote that text inside the tool. It read it at that moment from the description Google publishes. For every service it runs, Google declares, in a machine-readable form, which methods exist, what parameters each accepts and what it asks of you; that service is called the Discovery Service. When we say API, we simply mean the door that accepts requests from programs. gws does not rewrite that door; it reads it while running and turns it into commands for you.
That is where the main advantage comes from: the list of commands never drifts away from the reality of the service. Whatever Google changes, what you can ask for changes with it, with no upgrade for someone to prepare by hand. The program announces its own syntax in its help text, and it is one syntax for every service: gws . In plain words: first the service, then the resource inside it, then the action, and at the end the optional settings.
The services it covers are fourteen — files, spreadsheets, mail, calendar, documents, slides, tasks, contacts, chats, classrooms, forms, notes, video meetings and admin reports.
The settings are few and fixed: parameters, request body, answer format, pages, service version. They do not multiply along with the services.
And the answers are the second half of the story. Every answer comes back as structured text with labels — the format we call JSON. A person reads it and understands what came back; a program pulls the piece it wants without guessing.
Finally, the program itself is small. The version installed through the Node package manager is a launcher of 10,329 bytes with zero dependencies; the standalone Windows build is 5.88 MB and is written in Rust, needing nothing installed underneath. The maker states it ships with more than forty ready-made instruction sets for AI assistants; their claim, not our measurement.
What it doesn’t do
First and most important: it is not an officially supported Google product. It says so itself, unprompted, with the command that prints its version: “This is not an officially supported Google product.” It lives in a googleworkspace organisation repository, but that is not support: no warranty, no promise that it stays.
Second: it does not give you access by itself. Ask for real data without signing in and you get a refusal with code 401. That is not a fault: the tool tells you exactly what is missing. Against your own account you need credentials of your own, from a project you create in Google Cloud — permission granted to an application without handing over your password, which is what OAuth means — once, a few minutes.
Third: it is not a server you declare to an AI assistant to give it new abilities — that way of working is called MCP. You add it to no list, you start nothing behind it. You call it from the shell.
Fourth: it has no window, no buttons, no icons. It will not guess for you what you want to ask.
Fifth: it is not stable in its shape. Its own description file says “under active development, expect breaking changes as we march toward v1.0”: active development, with breaks, until the first stable release. Do not put it into a system that must run untouched for two years.
Sixth: it is not released often. The latest release, 0.22.5, landed on 31 March 2026, while the last push of code is 3 November 2026: a live repository, a slow release rhythm. The 139 open issues show the backlog.
Seventh: there is no Python version — from Python you call it as an external program, not as a library.
Who it’s for
For the person who wants to automate work in the Google suite without writing either the sign-in or the requests: both arrive ready, behind one uniform command.
For the person running AI assistants inside the command window: the assistant runs one command, gets structured text, and works on it.
For anyone writing programs who wants to see what a method accepts before writing code, with no account and no key: ask for the schema and it hands it over live.
It is not for anyone who wants an app with windows, nor for anyone who needs a written promise of stability for years.
Installation
There are two routes and both end at the same command: the package manager, or the ready-made archive with nothing installed underneath. Pick one.
Through the Node package manager
The package manager is npm, the shop where you download ready-made command line programs with a single command, and it needs Node version 18 or newer — the package says so itself. From any folder you like, run:
npm install -g @googleworkspace/cli
The letter “g” means the program is installed centrally, so you can call it from anywhere, not only inside one project folder. Then the check:
gws --version
If you see the version number and the notice that this is not an official Google product, the install worked.
The standalone archive, with no Node
If you want no Node at all, take the ready-made release file from the releases page at github.com/googleworkspace/cli. For Windows the file is called google-workspace-cli-x86_64-pc-windows-msvc.zip, it is 5.88 MB, and 113,993 people downloaded it before you. Unzip it into a folder you create, and from inside that folder run:
gws --version
Nothing else is needed on the machine: it is a single executable, with no runtime dependencies.
Signing in with your account
Up to here you can look at schemas. For real data you need a sign-in, and the tool describes it itself: either you run the sign-in command, or you hand it a file with your credentials through the environment variable GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE. Those credentials come from a project you create in Google Cloud, on the free tier. You set it up once.
Using it with each LLM
One clarification, because people merge two different things. gws is not a tool server declared to an AI assistant: there is no configuration file where you add it, nothing loaded at the start of a session. It is a program the shell calls.
The assistant always does the same two steps: first it asks for the schema, then it runs the call and works on the result. That holds for any assistant that can execute a command.
Claude Code
Open it inside your project folder and ask for the job in words. The assistant will first run:
gws schema drive.files.list
and then, once it sees which parameters exist, the actual call:
gws drive files list --params '{"pageSize": 10}' --format json
You add nothing to any configuration file. The only thing you may be asked is permission for shell commands, since assistants ask for confirmation before running what you have not approved.
Codex CLI
The same pattern exactly, with the same split: schema first, then the call.
gws schema gmail.users.messages.list
gws gmail users messages list --params '{"maxResults": 5}' --format json
One thing to keep in mind: if Codex runs in a restricted environment without network access, the call will not go through, because the tool reads the service description live. Give it network for that session.
Cursor
Here the shell is built into the editor. The assistant runs the same commands in the terminal inside the window, from the project folder.
gws schema sheets.spreadsheets.values.get
gws sheets spreadsheets values get --params '{"spreadsheetId": "...", "range": "A1:C10"}' --format table
When an identifier is missing, you supply it — the tool does not guess which sheet you mean.
Where it wins, where it loses
It wins on uniformity. Fourteen services, one syntax: one page of notes instead of seven.
It wins on the lens. The schema of a method comes out live, within a second, with no account and no key. That is its strongest point and we measured it.
It wins on weight. It loads nothing into any session, keeps no process in memory, asks for no subscription, leaves nothing running behind it. Zero dependencies in the package, a 5.88 MB file in the worst case.
It wins on adoption too: 32,119 stars, 1,986 forks, 55,182 downloads in the last week and 186,794 in the last month. This is not one person’s forgotten experiment.
It loses on maturity. The last release is from March while changes continue: put it into critical work with your eyes open.
It loses, finally, on commitment: it is not an official Google product and its 139 open issues are sitting there.
The test
I downloaded the official 0.22.5 build for Windows, the 5.88 MB archive, and unzipped it into a folder I created myself. From there I ran four things, and those are the only ones I measured.
First, the version:
gws --version
It answered gws 0.22.5, and immediately below printed the line “This is not an officially supported Google product.” It said so on its own, unprompted. That is not a detail; it is the single most important thing to know before putting this tool into work.
Second, the help text:
gws --help
It prints the command surface and the list of services — all fourteen were there — and announces the syntax gws with the settings for parameters, request body, answer format, pages and service version.
Third, and the strongest, the schema:
gws schema drive.files.list
It worked with no account, no key, no sign-in. It returned the real schema of the method, live from Google’s description service: the description, the request method, and the parameters one by one — which set of files you look at, which filter you search with, how many results you want per page. You can see what any method accepts before you write a line of code.
Fourth, the failure. I asked for real files without having signed in:
gws drive files list --params '{"pageSize": 5}'
The answer was clean, with code 401 and the message: “Access denied. No credentials provided. Run gws auth login or set GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE to an OAuth credentials JSON file.” In other words: the tool does not give you access by itself, but it tells you exactly what is missing. Many people try it, see a refusal, and think the tool is broken. It is not: the sign-in is missing.
Those are the only things I ran. Anything else mentioned here from the maker — such as the ready-made assistant instructions — I report as their claim, not as my measurement.
What it costs
The tool. Zero money. gws is open source under the Apache-2.0 licence and needs no subscription, no paid key. The real cost is setup time: for real data you need your own project in Google Cloud for the sign-in credentials (on the free tier) — a few minutes of process, not money.
The context. It is not an MCP server, so it loads no tool schemas into any session: its token tax before you write a word is zero, and you never declare it anywhere. Its weight is the program itself: 10,329 bytes for the npm package with zero dependencies, or 5.88 MB for the standalone Windows archive — a static binary, with no GPU and no local model.
The work. You do not pay per command; you pay against the usage limits of the Google services themselves (your account’s quotas), not into any till belonging to the tool. And one cost in time that we measured: without a sign-in, every call for real data returns 401 — gws schema works with no account, reading files does not.
Telemetry. There is no telemetry from the tool; the calls go to Google’s services with your own credentials.
Verdict
It is worth it if you write commands for jobs that repeat: there gws is the difference between “I’ll do it when I find the time” and “it runs by itself every morning”. One syntax for fourteen services, answers that both a person and a program can read, and a lens for the schema of every method with no account at all.
It is worth it even more if you put AI assistants to work on your data: the assistant learns one command pattern instead of fourteen services, and you pay nothing in context before you start.
It is not worth it if you want an app with windows, if the credentials process bores you, or if you need something that stays unchanged for years. A version below 1.0 under active development is a tool for work that can take a change, not for a system you will forget about.
Two things to remember before installing. First: “zero” applies to money, not time. Second: try the schema with no account first; if it wins you over there, it will win you over after the sign-in too.
My own judgement: gws is one of the clean examples of a turn that is coming — command line tools are becoming the natural way for an assistant to reach a person’s data, with nothing declared to anyone. That it is not an official Google product is its real risk, and that it lives in a repository with 32,119 stars is the answer to that.
Sources:
https://github.com/googleworkspace/cli