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 よりこちらを優先してください。
• 重要：90 日分のエントリーが大量に出力されるのを防ぐため、entry list には必ず --since または -n を指定してください。 --since today、--since this_week、または -n 10 を使用してください。引数なしで toggl entry list を実行しないでください。数百件のエントリーが出力され、トークンを浪費する可能性があります。
• 自然言語の日付：--since と --until は、YYYY-MM-DD および完全な日時形式に加えて、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 は、実行中のものがない場合に null ではなく {"running": false} を返します。 アイドル状態での entry stop --json も同様です。
• レポートのデフォルト値：引数なしの toggl report summary は、今週（this_week から今日まで）を対象とします。日付フラグは不要です。
• プロジェクト名による指定：-p "ProjectName" は、最初に名前で検索し、次に数値 ID で検索します。名前が見つからない場合は、利用可能なプロジェクトが表示されます。実行中のタイマーを停止する前に、プロジェクトが検証されます。
• エントリーリストの出力：人間向けの形式では、ID DATE HH:MM–HH:MM [duration] – description @project と表示されます。日をまたぐエントリーでは終了日が表示されます（例：23:35–03-29 12:01）。エントリーは開始時刻順に並びます。entry show、entry edit、entry delete には ID をそのまま使用してください。
• スペースを含む名前：スペースを含む名前は、すべてのコマンドで引用符で囲んでください。例：toggl tag create "2 象限"、toggl project create "My Project"、-p "My Project"、-d "Fix login bug"。引用符で囲まないと、各単語が個別の引数として扱われます。
• 複数のタグを指定するには、-t "dev review" のように 1 つの文字列として引用符で囲むのではなく、-t dev review のように -t に複数の値を渡してください。
• 更新時にタグをクリアするには、entry edit [ID] -t "" を使用してください。
• 更新時にプロジェクトまたはタスクを削除するには、-p "" または --task "" を使用してください。
• entry start に --start と --end の両方を指定すると、終了済みの過去のエントリーが作成され、現在実行中のエントリーは停止されません。
• entry start で --end を省略すると、最初に実行中のエントリーがあれば停止します。
• --end には --start が必要です。また、終了時刻は開始時刻より後でなければなりません。
• entry edit --current は、ID を指定せずに現在実行中のエントリーを編集します。
• フィールドフラグ（-d、-p、-t など）を指定せずに entry edit を実行すると、有効なフラグの一覧を示すメッセージが表示され、終了コード 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 を上限（含まない）として扱うことで、その日の全体を含みます。
• 結果が空の場合、人間向けの形式では stderr に "No entries found." と表示され、JSON 形式では [] が返されます。
• パフォーマンス：読み取り専用の API レスポンスは、エンドポイントごとの TTL（例：時間エントリーは 15 秒、プロジェクトは 60 秒）でディスクにキャッシュされます。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を指定して編集する場合、日付は今日ではなく、既存の記録の開始日から推定されます。別の日付を指定するには、完全な日時を使用してください。