Google Workspace CLI: authenticate gws and verify one Drive query

Use the repository's release or installation instructions. The npm route needs Node.js 18 or later:

npm install -g @googleworkspace/cli
gws --help
gws drive files list --help
gws schema drive.files.list

The CLI builds its interface from Google Discovery documents. Inspect the schema for the installed version rather than assuming a copied command remains valid forever. The project is actively developed before 1.0 and warns about breaking changes. Record the installed version when you save a working procedure.

The documented gws auth setup route uses gcloud to help configure a project and APIs. It can change Google Cloud configuration; it is not just a local check. If you already have an approved project, follow the manual OAuth Desktop-client path in the authentication guide instead.

For a manual setup, configure the OAuth app and test user where applicable, download the Desktop client's JSON to the documented configuration location, then start with the Drive service:

gws auth login -s drive

Inspect the requested scopes before consenting and select the minimum read access suitable for your task. The service selector is not itself a guarantee of read-only access. An organization administrator may restrict consent. Do not grant every service simply because a narrower setup fails.

In a POSIX shell, first inspect the request with dry-run, then issue it once:

gws drive files list --params '{"pageSize":5,"fields":"files(id,name),nextPageToken"}' --dry-run
gws drive files list --params '{"pageSize":5,"fields":"files(id,name),nextPageToken"}'

Dry-run is request inspection, not evidence that OAuth, API access or the query will succeed. The examples and flags follow the CLI documentation. Windows shell quoting differs; use a supported shell and check the rendered parameters before an actual call.

Compare a returned file ID and name with the intended account's Drive. Five results are only a page, not a full inventory; a next-page token means more may exist. Do not interpret an empty page as proof that the account has no files.

The repository includes a Drive skill that refers to the shared gws instructions. If you copy that skill, include and review its shared dependency too. Copying a single SKILL.md without its referenced files can leave an agent with incomplete instructions.

For an initial agent task, ask it to explain the already-returned JSON and identify the account or permission assumptions. If you then allow a live query, specify one read-only call, the expected fields and no sharing or write operations. Inspect both the proposed command and the result. A natural-language instruction is not an OAuth restriction.

For a denied request, separate API enablement, OAuth scope, organization policy and access to the particular resource. Check the structured error before changing permissions. For throttling, respect the API's retry guidance and avoid immediate repeated calls. An invalid parameter should send you back to gws schema, not to broader authorization.

Keep credentials and downloaded OAuth files out of repositories and chat. Follow the project's storage and authentication documentation for the machine you use. A local command transcript should contain the result you need, not a raw token dump.

gws is Apache-2.0-licensed and explicitly not an officially supported Google product. That is separate from the support, subscription requirements and quotas of the underlying Google services. Google Workspace, Cloud resources and an agent's model usage can each have their own terms or costs. Repository notice and license

Stop the first trial after one verified read. A next step might be a report over a chosen folder, with pagination and a known expected count. Do not jump directly to bulk edits, Gmail sends or sharing changes. For a reusable procedure, package only the verified steps using the SKILL.md guide.