---
title: "Google Docs Tools"
description: >
  Upload Markdown as native Google Docs (md2gdoc),
  download Google Docs as Markdown (gdoc2md), and
  download Google Docs as Word files (gdoc2docx).
---

import {
  Tabs,
  TabItem,
  Steps,
} from '@astrojs/starlight/components';

## Overview

When working with CLI agents like Claude Code on
writing projects, the most natural generation format
is Markdown. But iterating on those docs via Google
Docs is painful -- uploading a Markdown file to
Google Drive with proper formatting requires multiple
manual steps.

`md2gdoc` reduces this to one command.
`gdoc2md` does the reverse.
`gdoc2docx` downloads Google Docs as Word (.docx)
files.

## Installation

These tools require additional dependencies. Install
with the `gdocs` extra:

```bash
uv tool install 'claude-code-tools[gdocs]'
```

## First-Time Google OAuth Setup

:::note
This setup is shared by all Google tools
(`md2gdoc`, `gdoc2md`, `gdoc2docx`, `csv2gsheet`,
`gsheet2csv`).
You only need to do it once per GCP project.
:::

<Steps>

1. Go to
   [Google Cloud Console](https://console.cloud.google.com/)

2. Create or select a project and enable the
   **Google Drive API** and the **Google Docs API**

3. Set up the **OAuth consent screen**:

   - Go to **APIs & Services** > **OAuth consent
     screen**
   - If prompted for user type, choose **Internal**
     (available for Google Workspace accounts) --
     this avoids needing Google verification
   - Fill in the required fields (app name, support
     email) and save
   - If your app is set to **External**, go to the
     **Audience** tab in the left sidebar and either
     click **Publish app** to make it available, or
     add your email under **Test users**

   :::caution
   If you skip this step, the OAuth flow will show an
   error saying the app is "blocked" or "being
   evaluated". Publishing the app (or switching to
   Internal) resolves this.
   :::

4. Go to **APIs & Services** > **Credentials** >
   **Create Credentials** > **OAuth client ID**

5. Choose **Desktop app**, then download the JSON
   file

6. Save it as `.gdoc-credentials.json` in your
   project directory

7. First run will open a browser for OAuth consent
   (one-time per project)

</Steps>

:::tip
Credentials are project-specific
(`.gdoc-credentials.json` and `.gdoc-token.json` in
the current directory), so different projects can use
different Google accounts.
:::

## Usage

<Tabs>
<TabItem label="md2gdoc (Upload)">

Upload Markdown files as native Google Docs:

```bash
# Upload to root of Drive
md2gdoc report.md

# Upload to a specific folder
md2gdoc report.md --folder "Perf/Reports"

# Upload with a custom name
md2gdoc report.md --name "Q4 Summary"
```

### Conflict Handling

If a file with the same name already exists,
`--on-existing` controls behavior:

- `ask` (default) -- prompt for action
- `version` -- auto-add suffix
  (`report-1`, `report-2`, etc.)
- `overwrite` -- replace existing file

```bash
md2gdoc report.md --on-existing overwrite
```

### Formatting

By default, Google's markdown converter picks the
font, size, and spacing. Use these flags to override
body text formatting after upload:

```bash
# 10pt Arial, double-spaced
md2gdoc report.md --font Arial --font-size 10 --line-spacing 2.0

# Just change the font
md2gdoc report.md --font "Times New Roman"

# 1.5x spacing, keep default font
md2gdoc report.md --line-spacing 1.5
```

- `--font` -- font family (e.g. `Arial`,
  `"Times New Roman"`)
- `--font-size` -- size in points (e.g. `10`, `12`)
- `--line-spacing` -- multiplier (`1.0` = single,
  `1.5`, `2.0` = double)

All flags are optional and can be combined. Heading
styles (H1, H2, etc.) and inline formatting (bold,
italic, etc.) are preserved -- only body text
paragraphs get the font/size override.

### Features

- Native markdown conversion (same quality as manual
  upload + "Open in Docs")
- **Image upload** -- local images referenced in
  markdown (e.g. `![alt](diagram.png)`) are uploaded
  to Drive at full resolution, then inserted into
  the Google Doc with proper sizing
- **Formatting** -- optional `--font`, `--font-size`,
  and `--line-spacing` flags to control body text
  appearance (see above)
- `--max-image-width` controls display width in
  inches (default: 6.5 = full page width)
- `--no-images` skips image processing entirely
- Follows Drive shortcuts to shared folders
- Creates folders if they do not exist

</TabItem>
<TabItem label="gdoc2md (Download)">

Download Google Docs as Markdown files:

```bash
# Download from root
gdoc2md "My Document"

# Download from a specific folder
gdoc2md "My Document" --folder "PNL/Reports"

# Save with a custom name
gdoc2md "My Document" -o report.md

# List docs in a folder
gdoc2md --list --folder PNL
```

### Image Handling

By default, embedded images are extracted to local
files (e.g. `report_001.png`, `report_002.png`)
alongside the markdown, with references rewritten
to use local paths.

- Default -- extract images to files
- `--no-images` -- strip images to placeholders
- `--keep-base64` -- keep base64 data inline

</TabItem>
<TabItem label="gdoc2docx (Word)">

Download Google Docs as Word (.docx) files:

```bash
# Download from root
gdoc2docx "My Document"

# Download from a specific folder
gdoc2docx "My Document" --folder "PNL/Reports"

# Save with a custom name
gdoc2docx "My Document" -o report.docx

# List docs in a folder
gdoc2docx --list --folder PNL
```

### Supported Source Formats

- **Google Docs** -- exported as DOCX via the Drive
  API
- **DOCX** -- downloaded directly (no conversion
  needed)
- **DOC / ODT** -- converted via a temporary Google
  Doc, then exported as DOCX

</TabItem>
</Tabs>

## See Also

- [Google Sheets Tools](../google-sheets/) -- upload
  CSV to Sheets and download Sheets as CSV, using
  the same OAuth credentials
