内容
# gsheet-cli
> **一款适用于 Google Sheets 的快速 CLI，支持本地 DuckDB 缓存和 MCP 服务器**
## 功能
- **完整的 Sheets API** - 读取、写入、格式化单元格和范围，支持 A1 表示法
- **14 种图表类型** - 线形图、柱形图、饼图、散点图、气泡图、蜡烛图等
- **数据透视表** - 以编程方式创建、更新和刷新数据透视表
- **应用脚本** - 管理脚本项目、版本、部署和执行
- **本地缓存** - 使用 DuckDB 支持的离线访问，双向同步
- **双重身份验证** - OAuth 2.0 交互式流程或自动化服务账户
- **MCP 服务器** - 为 Claude 和其他 AI 助手公开工具
- **多种输出** - 表格、JSON 或 CSV 输出格式
- **配置文件** - 命名电子表格配置文件，快速切换
- **Shell 补全** - 支持 Bash、Zsh、Fish 和 PowerShell
## 安装
### 快速安装
```bash
curl -fsSL https://raw.githubusercontent.com/dipankar/gsheet-cli/main/install.sh | bash
```
或使用选项：
```bash
./install.sh --prefix ~/.local --completions
```
### 从源码编译
```bash
git clone https://github.com/dipankar/gsheet-cli.git
cd gsheet-cli
cargo build --release
cp target/release/gsheet ~/.local/bin/
```
## 快速入门
### 1. 身份验证
```bash
# 交互式 OAuth（打开浏览器）
gsheet auth login
# 或使用服务账户
gsheet auth login --service-account /path/to/key.json
```
### 2. 设置配置文件
```bash
gsheet config profile add mysheet --spreadsheet "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms"
```
### 3. 开始使用
```bash
# 列出工作表
gsheet -p mysheet sheet list
# 读取范围
gsheet -p mysheet range get "Sheet1!A1:D10"
# 写入值
gsheet -p mysheet cell set "A1" "Hello, World!"
```
## 使用示例
### 处理数据
```bash
# 获取单元格值
gsheet -s SPREADSHEET_ID cell get "B2"
# 从 JSON 设置范围
gsheet -s SPREADSHEET_ID range set "A1:B2" --json '[["Name","Age"],["Alice",30]]'
# 追加行到工作表
gsheet -s SPREADSHEET_ID cell append "Sheet1" "John" "Doe" "john@example.com"
# 查找匹配模式的单元格
gsheet -s SPREADSHEET_ID range find "A1:Z100" --pattern "error|warning"
```
### 工作表管理
```bash
# 创建新的工作表
gsheet -s SPREADSHEET_ID sheet create "Q1 Report"
# 复制工作表
gsheet -s SPREADSHEET_ID sheet duplicate "Template" "January"
# 冻结表头行
gsheet -s SPREADSHEET_ID sheet freeze --sheet "Data" --rows 1
# 设置选项卡颜色
gsheet -s SPREADSHEET_ID sheet tab-color "Important" --color "#FF0000"
```
### 格式化
```bash
# 粗体表头
gsheet -s SPREADSHEET_ID format bold "A1:Z1"
# 设置背景颜色
gsheet -s SPREADSHEET_ID format color "A1:D1" --bg "#4285F4" --fg "#FFFFFF"
# 应用边框
gsheet -s SPREADSHEET_ID format border "A1:D10" --style solid --color "#000000"
# 合并单元格
gsheet -s SPREADSHEET_ID format merge "A1:D1"
# 数字格式
gsheet -s SPREADSHEET_ID format number "B2:B100" --pattern "#,##0.00"
```
### 图表
```bash
# 创建柱形图
gsheet -s SPREADSHEET_ID chart create --type column --data "A1:B10" --title "Sales"
# 创建饼图
gsheet -s SPREADSHEET_ID chart create --type pie --data "A1:B5" --title "Distribution"
# 创建气泡图
gsheet -s SPREADSHEET_ID chart bubble --x-data "A1:A10" --y-data "B1:B10" --sizes "C1:C10"
```
### 数据透视表
```bash
# 创建数据透视表
gsheet -s SPREADSHEET_ID pivot create \
--source "Data!A1:E1000" \
--anchor "Pivot!A1" \
--rows "0" \
--values "2:SUM,3:AVERAGE"
# 刷新数据透视表
gsheet -s SPREADSHEET_ID pivot refresh "Pivot!A1"
```
### 应用脚本
```bash
# 运行函数
gsheet script run SCRIPT_ID "myFunction" --args '["param1", 42]'
# 创建和部署
gsheet script create --title "My Script" --parent-id SPREADSHEET_ID
gsheet script version create SCRIPT_ID --description "Initial release"
gsheet script deploy create SCRIPT_ID --version 1
```
## 配置
配置存储在 `~/.config/gsheet-cli/config.toml` 中：
```toml
[auth]
method = "oauth"
token_cache_path = "~/.config/gsheet-cli/tokens"
[cache]
enabled = true
ttl_seconds = 300
auto_sync = true
[output]
format = "table"
color = "auto"
[spreadsheets.mysheet]
id = "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms"
description = "My main spreadsheet"
```
### 全局标志
| 标志 | 描述 |
|------|-------------|
| `-s, --spreadsheet <ID>` | 电子表格 ID |
| `-p, --profile <NAME>` | 使用命名配置文件 |
| `-o, --output <FORMAT>` | 输出格式：table、json、csv |
| `-c, --config <PATH>` | 自定义配置文件 |
| `--no-cache` | 绕过缓存 |
| `-q, --quiet` | 抑制输出 |
| `-v, -vv, -vvv` | 增加详细程度 |
## MCP 服务器
启动用于 AI 助手集成的 MCP 服务器：
```bash
# stdio 传输（默认）
gsheet mcp
# HTTP 传输
gsheet mcp --transport http --port 8080
```
### 可用的 MCP 工具
| 工具 | 描述 |
|------|-------------|
| `read_range` | 从范围中读取值 |
| `write_range` | 向范围中写入值 |
| `list_sheets` | 列出所有工作表 |
| `create_sheet` | 创建新的工作表 |
| `format_range` | 应用格式化 |
| `run_macro` | 执行应用脚本函数 |
### Claude 桌面集成
添加到 `~/.config/claude/claude_desktop_config.json`：
```json
{
"mcpServers": {
"gsheet": {
"command": "gsheet",
"args": ["mcp"]
}
}
}
```
## 命令参考
| 命令 | 描述 |
|---------|-------------|
| `auth` | 身份验证管理 |
| `sheet` | 工作表/选项卡操作 |
| `cell` | 单个单元格操作 |
| `range` | 范围操作 |
| `format` | 单元格格式化 |
| `chart` | 图表操作 |
| `pivot` | 数据透视表操作 |
| `script` | 应用脚本管理 |
| `cache` | 缓存管理 |
| `config` | 配置管理 |
| `mcp` | 启动 MCP 服务器 |
| `completions` | 生成 shell 补全 |
运行 `gsheet <command> --help` 获取详细用法。
## Shell 补全
```bash
# Bash
gsheet completions bash > ~/.local/share/bash-completion/completions/gsheet
# Zsh
gsheet completions zsh > ~/.zfunc/_gsheet
# Fish
gsheet completions fish > ~/.config/fish/completions/gsheet.fish
# PowerShell
gsheet completions powershell > $PROFILE.CurrentUserAllHosts
```
## 开发
### 依赖项
- Rust 1.70+
- Google Cloud 项目，启用 Sheets API
- OAuth 2.0 凭证或服务账户密钥
### 编译
```bash
cargo build
cargo test
cargo clippy
```
### 运行测试
```bash
# 单元测试
cargo test
# 启用日志
RUST_LOG=debug cargo test
```
### 项目结构
```
src/
├── api/ # Google Sheets API 客户端
├── auth/ # OAuth 和服务账户身份验证
├── cache/ # DuckDB 缓存层
├── cli/ # 命令行界面
├── config/ # 配置管理
├── mcp/ # MCP 服务器实现
├── error.rs # 错误类型
├── lib.rs # 库入口点
└── main.rs # CLI 入口点
```
## 贡献
1. 分叉仓库
2. 创建功能分支 (`git checkout -b feature/amazing`)
3. 提交更改 (`git commit -m 'Add amazing feature'`)
4. 推送到分支 (`git push origin feature/amazing`)
5. 打开拉取请求
## 许可证
MIT 许可证 - 参见 [LICENSE](LICENSE) 获取详细信息。
---
由 [Dipankar](https://github.com/dipankar) 使用 Rust 制作。
