# bim-google

> Read and write Google Sheets and Docs from the command line. Pipe Revit schedules directly into shared trackers. No manual export, no copy-paste.

## Authentication

One-time browser sign-in. Your agent runs `bim google login`; bim-google opens the browser, you click Allow, credentials cached in `%APPDATA%\bim-google\token.json`. Every subsequent call refreshes the token silently.

```
bim google login          # interactive — opens browser
bim google logout         # delete stored credentials
bim google whoami         # {"ok":true,"result":{"signed_in":true,"email":"..."}}
bim google doctor --json  # check gws.exe present, client configured, signed in
```

Error when not signed in:
```json
{"ok":false,"error":{"kind":"auth_required","hint":"run `bim google login`","remediation":{"verb":"bim google login","interactive":true}}}
```

## Sheets verbs

```
bim google sheets read   --spreadsheet <id-or-url> [--range <r>] [--sheet <name>]
bim google sheets append --spreadsheet <id-or-url> [--sheet <name>] [--with-header]
bim google sheets write  --spreadsheet <id-or-url> --range <A1:Z100>
```

`--spreadsheet` accepts a spreadsheet ID or a full Google Sheets URL (ID extracted automatically).

`sheets read` — streams NDJSON to stdout; first row treated as column headers. Exit 0 = success.

`sheets append` — reads NDJSON from stdin. Keys of the first object determine column order. `--with-header` writes key names as first row before data.

`sheets write` — overwrites the exact range specified. Cells outside the range are untouched.

**Stdin formats:** NDJSON, JSON array of objects, or bim `{ok,result}` envelope (unwrapped automatically).

## Docs verbs

```
bim google docs read   --doc <id-or-url> [--raw]
bim google docs append --doc <id-or-url> [--text "..."]
```

`--doc` accepts a document ID or a full Google Docs URL.

`docs read` — returns `{"ok":true,"result":{"title":"...","text":"...","word_count":N,"char_count":N}}`.

`docs read --raw` — returns the full Google Docs API JSON.

`docs append` — inserts text at end of document body. Reads stdin if `--text` absent. No automatic paragraph break.

## Pipe compositions

```
# Push Revit sheet list to a shared tracker
bim revit schedule export Sheets | bim google sheets append --spreadsheet <id> --with-header

# Push model warnings to a Sheet for review
bim revit warnings list | bim google sheets append --spreadsheet <id> --with-header

# Read spec values from a shared Doc, push into Revit parameters
bim google docs read --doc <id> | bim revit param set --by Mark

# Read a Sheet, write matching params to Revit
bim google sheets read --spreadsheet <id> | bim revit param set --by Mark
```

## Gotchas

- Token has a 1-hour lifetime; refreshed automatically on next call if refresh token present.
- `sheets read` treats the first row as headers. A sheet with no header row will use the first data row as column names.
- `docs append` inserts at end-of-body with no automatic line break. Send `\n` + your text to avoid running text together.
- `sheets write` overwrites only the specified range; surrounding cells are untouched.
- Sheets API rate limit: 300 req/min/project. Prefer `sheets write` (single batchUpdate) over repeated appends for bulk changes.
- Scopes: `spreadsheets` + `documents` (both sensitive, basic verification, no CASA assessment required).