ターミナルから Jira で時間管理する

atlassian-cli はコミュニティによる独立したオープンソースプロジェクトです。Atlassian と提携・関連しておらず、Atlassian による承認、推奨、後援のいずれも受けておらず、Atlassian が提供する公式 CLI（acli）でもありません。製品名は互換性を示す目的でのみ使用しています。

jira worklog CLI のワークフローをお探しですか。Jira の時間管理は、今日からターミナルで行えます。課題に原見積もりと残り見積もりを設定し、時間が記録されたすべての課題を JQL で見つけ、その結果を jq で週次レポートにまとめられます。このガイドでは atlassian-cli の具体的なコマンドを示し、CLI がどこまでを担い、どこから Jira の worklog REST エンドポイントに引き継ぐのかも率直に説明します。

このツールについて一言。atlassian-cli は MIT ライセンスの、コミュニティによる独立したオープンソースプロジェクトです。Atlassian と提携・関連しておらず、Atlassian による承認、推奨、後援、保守のいずれも受けていません。Atlassian が提供する公式 CLI（acli）でもありません。ベンダーによる一次サポートが必要であれば公式の acli を使ってください。Jira、Confluence、Bitbucket、JSM をカバーする単一の無料 Rust バイナリが欲しい場合は atlassian-cli を選んでください。

Jira が時間を扱う仕組み

Jira は「時間」を、関連しつつも異なる2つの概念に分けています。この違いを知っておくと、以下の CLI コマンドの意味がつかめます。

• 見積もり。 timetracking フィールドは、原見積もり（作業にどれくらいかかると考えているか）と残り見積もり（あとどれくらい残っているか）を保持します。これらは課題に書き込む値です。
• 作業ログ。 作業ログは1件ごとの記録です。ある人が特定の日付に N 分を記録し、必要ならコメントも添えます。Jira はそれらを合計して課題の作業時間にします。作業ログは追記専用の記録であり、編集できる単一のフィールドではありません。

この分け方が重要なのは、コマンドごとに触れる層が違うからです。見積もりの設定は通常のフィールド更新です。誰がいつ時間を記録したかで課題を選ぶのは JQL クエリです。各作業ログの正確な分数を読むのは、別の REST 呼び出しです。この記事の残りでは、それぞれの層を順に見ていきます。

Jira の作業ログを CLI で今できること

コマンドの前に、全体像を率直に示しておきます。atlassian-cli は課題を中心に据えており、見積もりの書き込みと、作業ログの条件による課題の選択が得意です。記録ごとの正確な分数は Jira の REST API に引き継ぎます。ここに架空のフラグはなく、コマンドリファレンスに記載されているものだけを扱います。

要するに、見積もりの維持と作業ログを起点としたレポートは CLI で最初から最後までカバーでき、「未対応」の2行だけ REST API に降ります。最後の節で、その橋渡しの方法を示します。

見積もりを設定して調整する

timetracking は Jira の標準フィールドなので、jira issue update の汎用的な脱出口である --field から書き込みます。このフラグは key=JSON を取り、Jira は 3d、4h、30m のような見積もり文字列を解釈します。

# Set the original and remaining estimate on an issue
atlassian-cli jira issue update DEV-42 \
  --field 'timetracking={"originalEstimate":"3d","remainingEstimate":"1d"}'

作業が進んだら、残り見積もりだけを書いてバーンダウンを正確に保ちます。1日の終わりに実行するか、コミットフックに組み込んでください。

# Knock the remaining estimate down as you make progress
atlassian-cli jira issue update DEV-42 \
  --field 'timetracking={"remainingEstimate":"4h"}'

同じ --field の仕組みで編集画面上のどのフィールドも設定できるため、見積もりの変更とカスタムフィールドの更新を1回の呼び出しにまとめられます。ただし、Jira の設定でその課題の編集画面に timetracking が含まれていることを確認してください。含まれていないと API が書き込みを拒否します。

単位についての補足です。Jira は見積もり文字列を w（週）、d（日）、h（時間）、m（分）として読み、「1日」はサイトの時間管理設定で定義された長さ（多くは8時間）になります。そのため設定次第で 1d と 8h が同じ意味になります。レポートが一定の倍率でずれている場合は、CLI を疑う前に稼働時間の設定を確認してください。

JQL で作業ログから課題を探す

Jira の JQL には、作業ログを扱うフィールドが3つあります。worklogDate、worklogAuthor、worklogComment です。jira issue search は JQL をそのまま渡すため、専用の worklog サブコマンドがなくても、誰がいつ時間を記録したかで課題を選べます。

今週自分が対応した課題は？

# Every issue you logged time on since Monday
atlassian-cli jira issue search \
  --jql "worklogAuthor = currentUser() AND worklogDate >= startOfWeek()" \
  --limit 100

currentUser() と startOfWeek() は JQL の組み込み関数なので、このクエリはプロファイルをまたいでそのまま使えます。worklogDate >= -7d で移動する期間に切り替えたり、worklogAuthor = "alex@example.com" で同僚を対象にしたりできます。

チーム全体がこのスプリントでプロジェクトに記録した内容は？

# All issues in DEV with worklog activity in the last 14 days
atlassian-cli jira issue search \
  --jql "project = DEV AND worklogDate >= -14d" \
  --limit 200

既定の表形式の出力は、ざっと見るには十分です。細かく切り分けたいときは --format json を付けてパイプします。それが次の節の内容です。

jq で週次レポートを作る

jira issue search が出力する JSON はフラットな配列です。各行は key、summary、status、assignee、issue_type を持ちます。これだけあれば、本当に役立つ活動レポートを作れます。どの課題に時間が記録されたかを、担当者ごとにまとめられます。

# Count issues worked on this week, grouped by assignee
atlassian-cli jira issue search \
  --jql "project = DEV AND worklogDate >= startOfWeek()" \
  --limit 200 --format json \
  | jq 'group_by(.assignee)
      | map({assignee: .[0].assignee, issues: length})
      | sort_by(-.issues)'

これで、朝会やスプリントの振り返りに使える活動の一覧が得られます。

[
  { "assignee": "Priya Menon", "issues": 7 },
  { "assignee": "Alex Doe", "issues": 5 },
  { "assignee": "Sam Lee", "issues": 2 }
]

.status でグループ化すれば、記録された作業が Done に到達しているのか In Progress に溜まっているのかがわかります。.issue_type でグループ化すれば、バグと機能で時間を分けられます。正直な注意点が1つあります。これは課題の件数であり、時間ではありません。「何に、誰が取り組んだか」に答えるもので、多くの週次レビューが実際に必要とするのはこちらです。正確な分数が必要な場合は、このまま読み進めてください。

出力をプログラムで解析するなら、グローバルな --envelope フラグを付けます。配列が {"data": [...], "count": N} で包まれるため、後続のスクリプトは一覧を走査し直さずに件数を読めます。その場合 jq のパスは .[] ではなく .data[] から始まります。ターミナルでの臨時のレポートなら、素の配列のほうがパイプしやすいです。

週次タイムシートをエクスポートしてスクリプト化する

表計算ソフトで誰かに渡せるタイムシートが必要なら、作業ログで絞り込んだ課題の集合をエクスポートします。search は CSV を直接書き出せ、jira bulk export はページネーションを伴う大きめの取得を扱えます。

# CSV of everything you touched this week, straight to a file
atlassian-cli jira issue search \
  --jql "worklogAuthor = currentUser() AND worklogDate >= startOfWeek()" \
  --format csv --output timesheet.csv

# Larger export: all worklog activity this month for a project
atlassian-cli jira bulk export \
  --jql "project = DEV AND worklogDate >= startOfMonth()" \
  --output worklog-month.json --format json

これらをつなげて、毎週金曜に実行する1つのスクリプトにします。次のスクリプトは、その週の活動を表示し、CSV を書き出し、担当者ごとの内訳を示します。

#!/bin/bash
# weekly-timesheet.sh, your Jira worklog activity for the week
set -euo pipefail

PROFILE="work"
PROJECT="DEV"

# 1. Issues you personally logged time on since Monday
atlassian-cli jira issue search --profile "$PROFILE" \
  --jql "worklogAuthor = currentUser() AND worklogDate >= startOfWeek()" \
  --format csv --output timesheet.csv

echo "Wrote timesheet.csv"

# 2. Team activity for the project, grouped by assignee
atlassian-cli jira issue search --profile "$PROFILE" \
  --jql "project = $PROJECT AND worklogDate >= startOfWeek()" \
  --limit 200 --format json \
  | jq 'group_by(.assignee)
      | map({assignee: .[0].assignee, issues: length})
      | sort_by(-.issues)'

echo "Weekly summary complete."

--profile フラグは特定の認証済みアカウントを対象にするため、同じスクリプトが個人用と業務用の Jira サイトの両方で使えます。このパターンを定期実行できる本番向けにしたものは、Jira スプリントレポートのランブックをご覧ください。

個々の作業ログを記録する

現時点で CLI の課題コマンドの外にあるものが2つあります。個々の作業ログの登録（火曜日に2時間、コメント付きで記録するなど）と、各記録の正確な分数の読み取りです。どちらも Jira の worklog REST エンドポイントで扱います。

• POST /rest/api/3/issue/{key}/worklog で、timeSpent、started、任意のコメントを含む記録を追加します。
• GET /rest/api/3/issue/{key}/worklog で、作成者、開始時刻、記録された秒数を含むすべての記録を読み取ります。

きれいなやり方は、選択を atlassian-cli に、記録を REST 呼び出しに任せることです。jira issue search で JQL から対象の課題キーを見つけ、それらをループして作業ログを登録または取得します。この「CLI で選び、API で実行する」橋渡しは コマンドラインから Jira API を使うで解説しています。作業ログのレポートをより広い課題のワークフローに組み込む場合は、CLI で行う Jira のタスク管理のガイドが、作業ログの紐づく課題のライフサイクルを扱っています。

よくある質問

関連リソース