Google Drive

Everything runs through hatch_gws_cli drive .... Raw API calls are space-separated (<resource> <method>) and take a --params JSON object for query and path values, plus a --json body when creating or editing. Run hatch_gws_cli drive <command> --help for a command's flags, and hatch_gws_cli schema drive.files.list (and the like) for a raw method's --params and --json shape. Check the shape before an unfamiliar method.

Connecting

Drive needs a one-time connect before commands return data. Run hatch_gws_cli drive status. If it comes back not connected with a connect_url, post that exact URL as [Connect Google Drive](<connect_url>), then stop and wait for the user to tap it. If no URL is returned, report that connection is unavailable and stop; never invent one. Connecting is the user's step, so never open the sign-in, drive a browser to it, point the user to Settings or a Google account page, or ask for credentials. If status comes back unavailable, say Google Drive is not available on this device and stop.

Disconnect with hatch_gws_cli drive disconnect. Post [Disconnect Google Drive](<disconnect_url>) only when the command returns that URL. If status remains connected after the link was posted, re-post the same link and let the user finish in the browser; never send them to a Google account, security, or third-party-access page, and never loop on status. If no link is returned, rerun status once and report its state without inventing a link. If a later command reports an auth error, rerun status: post its connect link and wait when disconnected, retry the command once when connected, or report that Drive is unavailable when there is no usable link. Auth flows only through status and disconnect. Never hand-author credential files or run raw gws auth.

Most people have one Google account, and that is the default: run commands with no account flag. If the user names one of several linked Drives ("my work Drive"), list them with hatch_gws_cli drive accounts, match the user's words to exactly one display_name, and pass its account_id as --account <account_id>. If there is no exact match, ask which account rather than guessing or silently falling back to the default.

Common flows

Find and read

• See what is in Drive: drive files list --params '{"pageSize":20}'. To browse inside one folder, query by its id: drive files list --params "{\"q\":\"'<folder_id>' in parents and trashed=false\",\"pageSize\":50}".
• Search for a file: drive files list --params "{\"q\":\"name contains 'budget' and trashed=false\",\"pageSize\":20}". Drive query operands use single quotes; use fullText contains 'text' to search inside content.
• Get one file's details: drive files get --params '{"fileId":"<id>","fields":"id,name,mimeType,parents,webViewLink,modifiedTime,owners"}'.