google-calendar

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Google Calendar + Tasks Access

Google Calendar + Tasks 访问指南

Quick start

快速开始

Create a Google Cloud OAuth client (Desktop app) and save the credentials JSON to
```
~/.config/google-calendar/credentials.json
```
.

Install dependencies (venv recommended):

bash

python3 -m venv ~/.config/google-calendar/venv
~/.config/google-calendar/venv/bin/pip install -r <skill_dir>/scripts/requirements.txt

Authenticate and store a token:

Calendar only:
- ```
<skill_dir>/scripts/gcal-auth
```

Tasks only:

<skill_dir>/scripts/gcal-auth --scopes https://www.googleapis.com/auth/tasks

Calendar + Tasks (single token):

<skill_dir>/scripts/gcal-auth --scopes https://www.googleapis.com/auth/calendar https://www.googleapis.com/auth/tasks

Call the API:
- ```
<skill_dir>/scripts/gcal list-calendars
```

创建Google Cloud OAuth客户端（桌面应用），并将凭据JSON保存至
```
~/.config/google-calendar/credentials.json
```
。

安装依赖（推荐使用虚拟环境）：

bash

python3 -m venv ~/.config/google-calendar/venv
~/.config/google-calendar/venv/bin/pip install -r <skill_dir>/scripts/requirements.txt

认证并存储令牌：

仅日历：
- ```
<skill_dir>/scripts/gcal-auth
```

仅任务：

<skill_dir>/scripts/gcal-auth --scopes https://www.googleapis.com/auth/tasks

日历+任务（单令牌）：

<skill_dir>/scripts/gcal-auth --scopes https://www.googleapis.com/auth/calendar https://www.googleapis.com/auth/tasks

调用API：
- ```
<skill_dir>/scripts/gcal list-calendars
```

Credentials and tokens

凭据与令牌

Credentials are expected at

~/.config/google-calendar/credentials.json

by default.

Tokens are stored at
```
~/.config/google-calendar/token.json
```
by default.
Use
```
--token
```
or
```
GCAL_TOKEN_PATH
```
to switch accounts or isolate environments.

默认情况下，凭据需存储在

~/.config/google-calendar/credentials.json

。

令牌默认存储在
```
~/.config/google-calendar/token.json
```
。
可使用
```
--token
```
参数或
```
GCAL_TOKEN_PATH
```
环境变量切换账号或隔离环境。

Date/time rules

日期/时间规则

Use RFC3339 for timed events (e.g.,
```
2026-01-22T10:00:00-08:00
```
).
Use
```
YYYY-MM-DD
```
for all-day events and set
```
end
```
to the next day (exclusive).
Set
```
--time-zone
```
when the datetime has no offset.

定时事件需使用RFC3339格式（例如：
```
2026-01-22T10:00:00-08:00
```
）。
全天事件使用
```
YYYY-MM-DD
```
格式，并将
```
end
```
设置为次日（排他性）。
当日期时间无偏移量时，需设置
```
--time-zone
```
参数。

Common commands

常用命令

List calendars:
- ```
<skill_dir>/scripts/gcal list-calendars
```

List events:

<skill_dir>/scripts/gcal list-events --calendar-id primary --time-min 2026-01-22T00:00:00-08:00 --time-max 2026-01-22T23:59:59-08:00

Search events:

<skill_dir>/scripts/gcal list-events --calendar-id primary --q "standup" --time-min ... --time-max ...

Create event (simple):

<skill_dir>/scripts/gcal create-event --calendar-id primary --summary "Review" --start 2026-01-22T10:00:00-08:00 --end 2026-01-22T11:00:00-08:00

Update event (simple):

<skill_dir>/scripts/gcal update-event --calendar-id primary --event-id <id> --summary "New title"

Delete event:

<skill_dir>/scripts/gcal delete-event --calendar-id primary --event-id <id>

Free/busy:

<skill_dir>/scripts/gcal freebusy --calendars primary,team@company.com --time-min ... --time-max ...

List task lists:
- ```
<skill_dir>/scripts/gcal list-tasklists
```

List tasks:

<skill_dir>/scripts/gcal list-tasks --tasklist <tasklist_id>

Create task:

<skill_dir>/scripts/gcal create-task --tasklist <tasklist_id> --title "Buy milk" --due 2026-01-22T10:00:00-08:00

Update task:

<skill_dir>/scripts/gcal update-task --tasklist <tasklist_id> --task-id <id> --notes "Bring receipt"

Delete task:

<skill_dir>/scripts/gcal delete-task --tasklist <tasklist_id> --task-id <id>

列出日历：
- ```
<skill_dir>/scripts/gcal list-calendars
```

列出事件：

<skill_dir>/scripts/gcal list-events --calendar-id primary --time-min 2026-01-22T00:00:00-08:00 --time-max 2026-01-22T23:59:59-08:00

搜索事件：

<skill_dir>/scripts/gcal list-events --calendar-id primary --q "standup" --time-min ... --time-max ...

创建事件（简单版）：

<skill_dir>/scripts/gcal create-event --calendar-id primary --summary "Review" --start 2026-01-22T10:00:00-08:00 --end 2026-01-22T11:00:00-08:00

更新事件（简单版）：

<skill_dir>/scripts/gcal update-event --calendar-id primary --event-id <id> --summary "New title"

删除事件：

<skill_dir>/scripts/gcal delete-event --calendar-id primary --event-id <id>

空闲/忙碌查询：

<skill_dir>/scripts/gcal freebusy --calendars primary,team@company.com --time-min ... --time-max ...

列出任务列表：
- ```
<skill_dir>/scripts/gcal list-tasklists
```

列出任务：

<skill_dir>/scripts/gcal list-tasks --tasklist <tasklist_id>

创建任务：

<skill_dir>/scripts/gcal create-task --tasklist <tasklist_id> --title "Buy milk" --due 2026-01-22T10:00:00-08:00

更新任务：

<skill_dir>/scripts/gcal update-task --tasklist <tasklist_id> --task-id <id> --notes "Bring receipt"

删除任务：

<skill_dir>/scripts/gcal delete-task --tasklist <tasklist_id> --task-id <id>

Advanced usage

高级用法

Use

call

to hit any Calendar API endpoint:

<skill_dir>/scripts/gcal call GET /users/me/calendarList

<skill_dir>/scripts/gcal call POST /calendars/primary/events --body-file /path/to/event.json

Use
```
--body-file
```
or
```
--body
```
(JSON string) for complex payloads (attendees, recurrence, conferenceData).
Run multiple accounts by using different token files with
```
--token
```
.

使用

call

命令调用任意Calendar API端点：

<skill_dir>/scripts/gcal call GET /users/me/calendarList

<skill_dir>/scripts/gcal call POST /calendars/primary/events --body-file /path/to/event.json

对于复杂请求体（如参会者、重复规则、会议数据），可使用
```
--body-file
```
参数或
```
--body
```
参数（JSON字符串）。
通过
```
--token
```
参数使用不同的令牌文件，实现多账号管理。

Safety

安全注意事项

Confirm intent before creating, updating, or deleting events.
Keep OAuth credentials and token files out of git.

在创建、更新或删除事件前，请确认操作意图。
请勿将OAuth凭据和令牌文件提交至git仓库。