Metadata-Version: 2.5
Name: gmdoc
Version: 0.2.0
Summary: Pull/push Google Docs as Markdown via the Drive API
Project-URL: Homepage, https://github.com/boscoh/gmdoc
Project-URL: Repository, https://github.com/boscoh/gmdoc
Project-URL: Issues, https://github.com/boscoh/gmdoc/issues
Author-email: boscoh <apposite@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: cli,docs,drive,gcloud,google-docs,markdown
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Text Processing :: Markup :: Markdown
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: cyclopts>=4.10.0
Description-Content-Type: text/markdown

# gmdoc

Pull and push Google Docs as Markdown. It borrows your `gcloud` access token,
so you need no Google Cloud project, OAuth client, or config file.

## Install

Log in to Google once:

```sh
brew install --cask gcloud-cli
gcloud auth login --enable-gdrive-access   # browser login, click Allow
```

Then run `gmdoc` with `uvx`. It always fetches the latest release:

```sh
uvx gmdoc@latest ls
```

To install it instead:

```sh
uv tool install gmdoc
```

You can also copy `gmdoc.py` and run it with `uv run gmdoc.py ...`. It declares
its own dependencies in a PEP 723 header.

## Usage

```sh
gmdoc ls [name]                    # list recent docs
gmdoc pull <doc-url|id> [out.md]   # download (default name: <title>.md)
gmdoc pull notes.md                # re-pull a linked file
gmdoc push notes.md                # upload only what changed
gmdoc new draft.md -t "My Doc"     # create a doc from markdown
gmdoc status [files...]            # in sync / local / remote / CONFLICT
gmdoc account [email] [--login]    # list or switch Google accounts
```

Each pulled file gets front matter that links it to its doc:

```yaml
---
gmdoc_id: 1AbC...
gmdoc_title: My Doc
gmdoc_modified: 2026-01-01T12:00:00.000Z
gmdoc_hash: 3f2a...
gmdoc_account: me@gmail.com
---
```

## Multiple accounts

- `gmdoc account` lists your gcloud accounts. It marks the active one with `*`
  and checks that each can reach Drive.
- `gmdoc account other@gmail.com` switches account. It logs in first if needed.
  Add `--login` to log in again (fixes "no Drive access").
- Each file remembers its account in `gmdoc_account`. `pull`, `push` and
  `status` use that account.
- `ls` and `new` use the active account. Add `--account/-a <email>` to any
  command to override it.

## Safety checks

- `push` refuses if the doc changed in Google after your last sync. It exports
  the doc and compares it to `gmdoc_hash`.
- `pull` refuses if the local file has unpushed edits.
- `--force` skips both checks.

## Troubleshooting

If Drive says the API isn't enabled for the project, set
`GMDOC_QUOTA_PROJECT=<project-id>`. Use a project that has the Drive API enabled.

## How push works

`push` edits the doc in place. It changes only the text and formatting you
changed. Comments, suggestions, colors, fonts, images and anything else
markdown can't express stay on the parts you didn't touch.

To find your changes, gmdoc has Drive convert the doc's current markdown and
your edited file into two throwaway docs. It deletes them right away, compares
them, and applies the difference with the Google Docs API. A push takes a few
seconds longer than a plain upload.

Some changes can't be made in place: adding, removing or reshaping a table, or
adding images and other non-text elements. Then push says so and **replaces the
whole doc body**, as `push --replace` does. Comments become detached, and
suggestions and formatting that markdown can't express are lost.

## Caveats

- If you change a list item's nesting or type, Google rebuilds that list with its
  standard bullets. The markdown may come back with `*` instead of `-`.
- After a push, gmdoc re-exports the file so it matches Google's markdown.
- gmdoc uses the `drive` scope so it can edit any doc you can access.

## License

MIT
