mcpField
T
toggl-cli

toggl-cli

github.com/correctroadh生产力1573 次安装13 周前更新
代码仓库

关于 toggl-cli

toggl-cli 是用于管理 Toggl 时间记录的命令行工具，面向需要在终端记录工时和查看报告的用户。它支持条目、项目、标签等资源管理，并可使用官方 API 或 OpenToggl。

主要功能

  1. 01启动、停止和编辑计时条目
  2. 02按条件搜索与列出记录
  3. 03管理项目、任务、标签和工作区
  4. 04查看汇总、详细及周报
  5. 05支持 JSON 输出与 OpenToggl

适用场景

  1. 01为当前工作启动并停止计时
  2. 02查找指定日期或项目的历史记录
  3. 03批量修改同一工作区的条目
  4. 04按周或项目查看工时报告

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/correctroadh/toggl-cli --skill toggl-cli

安装后在 Claude Code 中输入/toggl-cli确认已加载。

详细介绍

Toggl CLI 技能

  • 安装：npm install -g @correctroadh/toggl-cli
  • 身份验证：toggl auth login [TOKEN] [--api-type official|opentoggl] [--api-url URL]
  • 身份验证（OpenToggl）：toggl auth login <TOKEN> --api-type opentoggl --api-url https://your-server.com

命令形式

时间记录：

  • toggl entry start [-d DESCRIPTION] [-p PROJECT] [--task TASK] [-t TAG...] [-b] [--start DATETIME] [--end DATETIME] [-j]
  • toggl entry stop [-j]
  • toggl entry continue [-i] [-j]
  • toggl entry running [-j]
  • toggl entry show [ID] [--current] [-j]
  • toggl entry edit [ID] [--current] [-d DESCRIPTION] [--billable true|false] [-p PROJECT] [--task TASK] [-t TAG...] [--start DATETIME] [--end DATETIME|""] [-j]
  • toggl entry delete [ID] [--current] [-j]
  • toggl entry bulk-edit <ID...> --json '<JSON_PATCH>'
  • toggl entry list [--since DATETIME] [--until DATETIME] [-n NUMBER] [-j]
  • toggl entry search [QUERY] [-p PROJECT|--no-project] [-t TAG...|--no-tag] [--since DATE] [--until DATE] [-n NUMBER] [--order-by date|duration|description|last_update|user] [--order-dir ASC|DESC] [-j]

资源：

  • toggl project list [-j]
  • toggl project create <name> [--color HEX]
  • toggl project rename <old_name> <new_name>
  • toggl project delete <name>
  • toggl tag list [-j]
  • toggl tag create <name>
  • toggl tag rename <old_name> <new_name>
  • toggl tag delete <name>
  • toggl client list [-j]
  • toggl client create <name>
  • toggl client rename <old_name> <new_name>
  • toggl client delete <name>
  • toggl task list [-j]
  • toggl task create -p PROJECT <name> [--active true|false] [--estimated-seconds N] [--user-id ID]
  • toggl task update -p PROJECT <name> [--new-name NAME] [--active true|false] [--estimated-seconds N] [--user-id ID]
  • toggl task rename -p PROJECT <old_name> <new_name>
  • toggl task delete -p PROJECT <name>
  • toggl workspace list [-j]
  • toggl workspace create <organization_id> <name>
  • toggl workspace rename <old_name> <new_name>
  • toggl org list [-j]
  • toggl org show <id> [-j]
  • toggl auth login [TOKEN] [--api-type official|opentoggl] [--api-url URL]
  • toggl auth status [-j]
  • toggl me [-j]
  • toggl preferences read
  • toggl preferences update '<json>'
  • toggl config init|active|-e|-p|-d

报告（--since/--until 为可选参数，默认值为 this_week/today）：

  • toggl report summary [--since DATE] [--until DATE] [-j] [--group-by projects|clients|users] [--sub-group-by time_entries|tasks|projects|users]
  • toggl report detailed [--since DATE] [--until DATE] [-j] [-n NUMBER] [--order-by date|user|duration|description] [--order-dir ASC|DESC]
  • toggl report weekly [--since DATE] [--until DATE] [-j]

使用技巧

  • 使用 entry search 查找历史条目：通过 Reports API v3 在服务端搜索。筛选条件按 AND 组合：位置参数 QUERY 匹配描述（子字符串）；-p NAME|ID 限定项目（也可用 --no-project 查找缺少项目的条目）；-t NAME 限定标签（可重复使用，也可用 --no-tag 查找无标签的条目）。--no-project/--no-tag 与 -p/-t 互斥。项目和标签名称会在默认工作区中解析为 ID；传入数字 ID 可跳过查询。默认日期范围为最近 365 天；使用 --since 2024-01-01 可查找更早的记录。搜索历史时优先使用此命令，而非 entry list | grep。
  • 重要：始终为 entry list 指定范围，使用 --since 或 -n，避免输出 90 天的条目。使用 --since today、--since this_week 或 -n 10。切勿直接运行 toggl entry list——输出可能包含数百个条目，浪费令牌。
  • 自然语言日期：除 YYYY-MM-DD 和完整日期时间格式外，--since 和 --until 还接受 today、yesterday、now、this_week、last_week。entry list 和所有 report 命令均适用。
  • 所有变更操作均支持 JSON：entry start、entry stop、entry edit、entry continue 均支持 -j/--json，并返回包含真实 ID、已补全项目和 "running" 布尔值的完整条目。
  • entry running --json 在没有正在运行的条目时返回 {"running": false}（而非 null）。空闲时，entry stop --json 也一样。
  • 报告默认值：不带参数的 toggl report summary 默认使用当前周（this_week 至 today）。无需指定日期标志。
  • 按名称指定项目：-p "ProjectName" 会先按名称解析，再按数字 ID 解析。不存在的名称会显示可用项目。停止任何正在运行的计时器前，会先验证项目。
  • 条目列表输出：人类可读模式显示 ID DATE HH:MM–HH:MM [duration] – description @project。跨日条目会显示结束日期（例如 23:35–03-29 12:01）。条目按开始时间排序。可直接使用 ID 调用 entry show、entry edit、entry delete。
  • 名称中包含空格：在所有命令中用引号括起包含空格的名称：toggl tag create "2 象限"、toggl project create "My Project"、-p "My Project"、-d "Fix login bug"。不加引号时，每个单词都会被视为单独的参数。
  • 多个标签：向 -t 传入多个值，例如 -t dev review；如果要指定两个独立标签，不要写成一个带引号的字符串，如 -t "dev review"。
  • 更新时清除标签：使用 toggl entry edit [ID] -t ""。
  • 更新时移除项目或任务：使用 -p "" 或 --task ""。
  • 如果 entry start 同时收到 --start 和 --end，则会创建一条已结束的历史条目，不会停止当前正在运行的条目。
  • 如果 entry start 未指定 --end，则会先停止当前正在运行的条目。
  • --end 必须与 --start 一起使用，且结束时间必须晚于开始时间。
  • entry edit --current 无需指定 ID，即可编辑当前正在运行的条目。
  • 如果 entry edit 未指定字段标志（-d、-p、-t 等），则会以状态码 1 退出，并显示列出有效标志的提示信息。
  • 批量编辑：entry bulk-edit 接受多个 ID，并支持使用 JSON Patch 数组的 --json 标志。所有条目必须属于同一工作区。示例：toggl entry bulk-edit 123 456 789 --json '[{"op":"replace","path":"/description","value":"standup"}]'。
  • entry start 在省略标志时会使用配置默认值，包括默认项目、任务、标签和计费状态。
  • 对于 entry list，仅包含日期的 --since YYYY-MM-DD 表示该日期开始时的本地时间 00:00:00。
  • 对于 entry list，仅包含日期的 --until YYYY-MM-DD 会将次日的本地时间 00:00:00 作为不包含在内的上限，从而包含当天全天。
  • 无结果时：人类可读模式会将 "No entries found." 输出到 stderr；JSON 模式返回 []。
  • 性能：只读 API 响应会缓存在磁盘上（各端点 TTL 不同，例如时间条目为 15s，项目为 60s）。可通过 TOGGL_DISABLE_HTTP_CACHE=1 禁用缓存。

最简示例

# Time entries
toggl entry start -d "Feature work" -p "App" -t dev review -b
toggl entry start -d "Backfill" --start "2026-03-05 09:00" --end "2026-03-05 10:30"
toggl entry start -d "Quick meeting" --start 09:00 --end 10:00
toggl entry start -d "Task" -p "App" --json   # returns real ID in JSON
toggl entry stop --json                        # returns stopped entry as JSON
toggl entry running --json                     # check if running, get entry data
toggl entry edit --current -d "Updated" -p "" -t ""
toggl entry list --since today
toggl entry list --since yesterday --until today
toggl entry list --since this_week --json | jq '.[].description'
toggl entry list --since last_week --until yesterday
toggl entry search "login bug"                          # description search, last 365 days
toggl entry search --no-project --since last_week       # untriaged entries from last week
toggl entry search "standup" -p "Work" -t daily         # combine description + project + tag
toggl entry search --no-tag --since 2025-01-01 -j       # JSON, all untagged entries this year
toggl entry search --order-by duration --order-dir DESC -n 20  # longest entries in the last year
toggl entry bulk-edit 123 456 --json '[{"op":"replace","path":"/description","value":"standup"}]'

# Reports (no args = current week)
toggl report summary
toggl report summary --since today --until today
toggl report summary --since last_week --until yesterday --json
toggl report weekly --since this_week --until today
toggl report detailed --since 2026-03-01 --until 2026-03-27 -n 50

# Resources (quote names with spaces)
toggl project list -j
toggl project create "My Project" --color "#06aaf5"
toggl tag create "2 象限"
toggl entry start -d "Fix login bug" -p "My Project" -t urgent
toggl me --json

输出与时间

  • 时间条目列表格式：ID DATE HH:MM–HH:MM [$] [HH:MM:SS]* – description @Project #[tag1, tag2]
  • 起止时间范围会内联显示。跨日条目会显示结束日期（例如：23:35–03-29 12:01）。
  • 正在运行的条目会以 HH:MM–… 显示结束时间。
  • $ 表示可计费；* 表示当前正在运行。
  • 单条 JSON 输出包含 "running": true/false 和已填充数据的 "project" 对象。
  • --start、--end、--since、--until 接受的日期时间输入：
    • 自然语言：today、yesterday、now、this_week、last_week
    • RFC3339：2026-03-05T09:00:00+08:00
    • 本地日期时间：2026-03-05 09:00 或 2026-03-05T09:00:00
    • 仅日期：2026-03-05，表示本地时间 00:00:00
    • 仅时间：09:00 或 14:30:00，表示本地时区今天的对应时间
  • entry edit 仅输入时间时的解析方式：使用仅含时间的值（例如 18:30）通过 --start 或 --end 编辑时，日期会根据条目现有的开始日期推断，而不是今天。若要指定其他日期，请使用完整日期时间。

评论

支持 Markdown