Show HN：Gdocs-CLI – 獲取 Google Docs 並轉換為 Markdown，供 AI 編碼代理使用

Navigation Menu

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

To see all available qualifiers, see our documentation.

Uh oh!

There was an error while loading. Please reload this page.

famasya/gdocs-cli

Folders and files

Latest commit

History

Repository files navigation

Google Docs CLI

A command-line tool to fetch Google Docs content and convert it to Markdown with YAML frontmatter.

Designed for AI Coding Agents: This tool is specifically built to help AI coding agents fetch Google Docs documentation and convert it to clean markdown for analysis, context gathering, or integration into AI workflows. The stdout-based output and --clean flag make it ideal for piping into AI systems.

📖 See AGENTS.md for a comprehensive guide on integrating this tool with AI coding agents (Claude Code, Aider, Cursor, MCP servers, etc.).

Features

Prerequisites

Installation

From Release Binaries

Prebuilt binaries for Linux, macOS, and Windows are available on the GitHub Releases page.

From Source

Using Go Install

Google Cloud Setup

Before using this tool, you need to set up OAuth2 credentials:

1. Create a Google Cloud Project

2. Create OAuth 2.0 Credentials

Important: Keep this file secure and never commit it to version control.

Usage

Initialize Authentication (Recommended First Step)

Before using the CLI for the first time, set up your credentials and initialize OAuth authentication:

Option 1: Use default config location (recommended for AI agents)

Option 2: Specify config path

This will:

After initialization, you can use the CLI without re-authenticating.

Basic Usage

Using default config location:

Specifying config path:

The tool will automatically use the cached token - no browser interaction needed.

Note: If --config is not provided, the tool looks for credentials at ~/.config/gdocs-cli/config.json by default. This makes it easy for AI agents to use the tool without specifying the config path every time.

Output to File

Piping to Other Commands

Clean Output (Suppress Logs)

Use the --clean flag to suppress all log output and only show the markdown:

This is useful when:

Example:

Print Integration Instructions

Use the --instruction flag to print instructions for integrating this tool with AI coding agents:

Quick Integration: Add this one-liner to your project's AGENTS.md, CLAUDE.md, or MCP config:

Supported Google Docs Features

Text Formatting

Document Structure

YAML Frontmatter

The tool adds YAML frontmatter with document metadata:

Note: The Google Docs API v1 doesn't provide author or date information. These fields may be empty unless fetched from Google Drive API.

Known Limitations

Troubleshooting

Error: Failed to read credentials file

Cause: The credentials file path is incorrect or the file doesn't exist.

Solution:

Error: Unable to access document

Possible causes:

Solutions:

Browser doesn't open during OAuth

Solution:
The authorization URL will be printed in the terminal. Copy and paste it into your browser manually.

Token expired or invalid

Solution:
Delete the cached token and re-authenticate using the --init flag:

Permission denied when creating config directory

Solution:
Ensure you have write permissions to ~/.config/. Try creating it manually:

Development

Project Structure

Building from Source

Running Tests

The project includes comprehensive unit tests for all core functionality:

Test Coverage:

Total: 45+ test cases covering both unit and integration testing. All tests pass successfully and ensure the reliability of the CLI tool.

Security Considerations

License

MIT License

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Credits

Built with:

About

Resources

Uh oh!

There was an error while loading. Please reload this page.

Stars

Watchers

Forks

Releases

  4

Packages

  0

Contributors

  2

Uh oh!

There was an error while loading. Please reload this page.

Languages

Footer

Footer navigation