jira-time-tracking

name	jira-time-tracking
description	Time tracking, worklogs, and time reports. TRIGGERS: 'log time', 'time spent on', 'log hours', 'log work', 'worklog', 'time tracking', 'timesheet', 'how much time', 'time logged', 'time report', 'export timesheet', 'set estimate', 'remaining estimate', 'original estimate'. Use for time-related queries and operations on issues. NOT FOR: SLA tracking (use jira-jsm), date-based issue searches (use jira-search), issue field updates unrelated to time (use jira-issue).
version	1.0.0
author	jira-assistant-skills
license	MIT
allowed-tools	["Bash","Read","Glob","Grep"]

JIRA Time Tracking Skill

Risk Levels

Operation	Risk	Notes
View worklogs	-	Read-only
View time tracking	-	Read-only
Generate reports	-	Read-only
Export timesheets	-	Read-only (local file)
Log time	-	Easily reversible (can delete)
Update worklog	!	Previous value lost
Set estimates	!	Can update again
Bulk log time	!	Creates multiple worklogs
Delete worklog	!!	Time data lost, can re-log

Risk Legend: - Safe, read-only | ! Caution, modifiable | !! Warning, destructive but recoverable | !!! Danger, irreversible

When to use this skill

Use the jira-time skill when you need to:

• Log time spent working on JIRA issues
• View, update, or delete work log entries
• Set or update time estimates (original and remaining)
• Generate time reports for billing, invoicing, or tracking
• Export timesheets to CSV or JSON format
• Bulk log time across multiple issues

What this skill does

IMPORTANT: Always use the jira-as CLI. Never run Python scripts directly.

The jira-time skill provides comprehensive time tracking and worklog management:

Worklog Management

• Add worklogs - Log time with optional comments and date/time
• View worklogs - List all time entries for an issue
• Update worklogs - Modify existing time entries
• Delete worklogs - Remove time entries with estimate adjustment

Time Estimates

• Set estimates - Configure original and remaining estimates
• View time tracking - See complete time tracking summary with progress

Reporting

• Time reports - Generate reports by user, project, or date range
• Export timesheets - Export to CSV/JSON for billing systems
• Bulk operations - Log time to multiple issues at once

Available Commands

Command	Description
jira-as time log	Add a time entry to an issue
jira-as time worklogs	List all worklogs for an issue
jira-as time update-worklog	Modify an existing worklog
jira-as time delete-worklog	Remove a worklog entry
jira-as time estimate	Set original/remaining time estimates
jira-as time tracking	View time tracking summary
jira-as time report	Generate time reports
jira-as time export	Export time data to CSV/JSON
jira-as time bulk-log	Log time to multiple issues

All commands support --help for full documentation.

Common Options

All commands support these common options:

Option	Description	Availability
-o/--output	Output format: text (default), json	log, worklogs, update-worklog, delete-worklog, tracking, bulk-log
-f/--format	Output format: text, json, csv	report (text/csv/json), export (csv/json only)
--help	Show help message with all available options	All commands

Worklog-specific options

Option	Description
-t/--time TIME	Time spent (e.g., 2h, 1d 4h, 30m)
-c/--comment TEXT	Description of work performed
-s/--started DATE	When work was started (default: now)
--adjust-estimate MODE	How to adjust remaining estimate: auto, leave, new, manual (see note below)
--new-estimate TIME	New remaining estimate (for adjust=new or adjust=manual)
--increase-by TIME	Amount to increase estimate (for adjust=manual with delete-worklog)
--visibility-type TYPE	Worklog visibility: role or group
--visibility-value TEXT	Role name or group name for visibility
-w/--worklog-id ID	Worklog ID (for update/delete operations)

Note: The manual mode (with --reduce-by or --increase-by) is only available for log and delete-worklog commands. The update-worklog command supports only auto, leave, and new modes.

Worklog filter options

Option	Description
-s/--since DATE	Start date for filtering worklogs
-u/--until DATE	End date for filtering worklogs
-a/--author USER	Filter by worklog author

Report-specific options

Option	Description
--period PERIOD	Time period: today, yesterday, this-week, last-week, this-month, last-month, or YYYY-MM format
-u/--user USER	Filter by user (use currentUser() for yourself)
-p/--project PROJECT	Filter by project key
-s/--since DATE	Start date for filtering
--until DATE	End date for filtering
-g/--group-by FIELD	Group results by: issue, day, or user

Export-specific options

Option	Description
-o/--output FILE	Output file path (e.g., timesheets.csv)
-f/--format FORMAT	File format: csv (default) or json

Bulk-log-specific options

Option	Description
-j/--jql JQL	JQL query to select issues
-i/--issues LIST	Comma-separated issue keys
-n/--dry-run	Preview without making changes
-f/--force	Skip confirmation prompt

Exit Codes

All commands return standard exit codes:

Code	Meaning
0	Success - operation completed successfully
1	Error - operation failed (check error message for details)
2	Invalid arguments - incorrect command-line usage

Examples

Log time to an issue

# Log 2 hours of work
jira-as time log PROJ-123 -t 2h

# Log time with a comment
jira-as time log PROJ-123 -t "1d 4h" -c "Debugging authentication issue"

# Log time for yesterday
jira-as time log PROJ-123 -t 2h -s yesterday

# Log time without adjusting estimate
jira-as time log PROJ-123 -t 2h --adjust-estimate leave

# Log time and set new remaining estimate
jira-as time log PROJ-123 -t 2h --adjust-estimate new --new-estimate 4h

# Log time with visibility restriction
jira-as time log PROJ-123 -t 2h --visibility-type role --visibility-value Developers

# Output as JSON
jira-as time log PROJ-123 -t 2h -o json

View worklogs

# List all worklogs for an issue
jira-as time worklogs PROJ-123

# Filter by author (-a is short for --author)
jira-as time worklogs PROJ-123 -a currentUser()
jira-as time worklogs PROJ-123 --author currentUser()

# Filter by date range (-s, -u are short forms)
jira-as time worklogs PROJ-123 -s 2026-01-01 -u 2026-01-31
jira-as time worklogs PROJ-123 --since 2026-01-01 --until 2026-01-31

# Output as JSON
jira-as time worklogs PROJ-123 -o json

Manage estimates

# Set original estimate
jira-as time estimate PROJ-123 --original 2d

# Set remaining estimate
jira-as time estimate PROJ-123 --remaining "1d 4h"

# Set both estimates together (recommended)
jira-as time estimate PROJ-123 --original 2d --remaining 1d

# View time tracking summary
jira-as time tracking PROJ-123

# View time tracking as JSON
jira-as time tracking PROJ-123 -o json

Update worklogs

# Update time on existing worklog
jira-as time update-worklog PROJ-123 -w 12345 -t 3h

# Update worklog comment
jira-as time update-worklog PROJ-123 -w 12345 -c "Updated description"

# Update worklog start time
jira-as time update-worklog PROJ-123 -w 12345 -s 2025-01-15

# Update with automatic estimate adjustment
jira-as time update-worklog PROJ-123 -w 12345 -t 4h --adjust-estimate auto

# Update and set new remaining estimate
jira-as time update-worklog PROJ-123 -w 12345 -t 4h --adjust-estimate new --new-estimate 2d

# Output as JSON
jira-as time update-worklog PROJ-123 -w 12345 -t 3h -o json

Generate reports

# My time for last week
jira-as time report -u currentUser() --period last-week

# Project time for this month
jira-as time report -p PROJ --period this-month

# Report for specific month using YYYY-MM format
jira-as time report -p PROJ --period 2025-01

# Export to CSV for billing
jira-as time report -p PROJ -s 2025-01-01 --until 2025-01-31 -f csv > timesheet.csv

# Group by day for daily summary
jira-as time report -p PROJ --period this-week -g day

# Group by user for team summary
jira-as time report -p PROJ --period this-month -g user -f json

# JSON output for scripting (pipe to jq for processing)
jira-as time report -p PROJ --period this-week -f json | jq ".worklogs[] | {user: .author, hours: .timeSpentSeconds/3600}"

Export timesheets

# Export last month's timesheets to CSV
jira-as time export -p PROJ --period last-month -o timesheets.csv

# Export specific month using YYYY-MM format
jira-as time export -p PROJ --period 2025-01 -o january.csv

# Export to JSON for integration
jira-as time export -p PROJ -s 2025-01-01 --until 2025-01-31 -f json -o timesheets.json

# Export user's timesheets for billing
jira-as time export -u [e-mail] --period this-month -o billing.csv

Note: For export, -o/--output specifies the file path and -f/--format specifies the format (csv or json).

Bulk operations

# Preview bulk time logging (dry run)
jira-as time bulk-log -i PROJ-1,PROJ-2 -t 15m -c "Sprint planning" -n

# Log standup time to multiple issues
jira-as time bulk-log -i PROJ-1,PROJ-2 -t 15m -c "Sprint planning"

# Log time to JQL results with dry run
jira-as time bulk-log -j "sprint = 456" -t 15m -c "Daily standup" -n

# Execute after confirming dry run output
jira-as time bulk-log -j "sprint = 456" -t 15m -c "Daily standup"

# Skip confirmation prompt with force flag
jira-as time bulk-log -i PROJ-1,PROJ-2 -t 15m -c "Team meeting" -f

# Output results as JSON
jira-as time bulk-log -i PROJ-1,PROJ-2 -t 15m -c "Meeting" -o json

Delete worklogs

# Preview worklog deletion (dry run)
jira-as time delete-worklog PROJ-123 -w 12345 --dry-run

# Delete with automatic estimate adjustment
jira-as time delete-worklog PROJ-123 -w 12345 --adjust-estimate auto

# Delete without modifying estimate
jira-as time delete-worklog PROJ-123 -w 12345 --adjust-estimate leave

# Delete and set new remaining estimate
jira-as time delete-worklog PROJ-123 -w 12345 --adjust-estimate new --new-estimate 3d

# Delete and increase estimate by specific amount (manual mode)
jira-as time delete-worklog PROJ-123 -w 12345 --adjust-estimate manual --increase-by 2h

# Delete without confirmation prompt
jira-as time delete-worklog PROJ-123 -w 12345 --yes

Dry Run Support

The following commands support --dry-run for previewing changes without making modifications:

Command	Dry Run Behavior
jira-as time bulk-log	Shows which issues would receive worklogs and the time that would be logged
jira-as time delete-worklog	Shows worklog details that would be deleted and estimate impact

Dry-Run Pattern: Always use -n/--dry-run first when performing bulk operations or deleting worklogs. This preview-before-execute workflow prevents accidental data changes:

# Step 1: Preview the operation
jira-as time bulk-log -j "sprint = 456" -t 15m -n

# Step 2: Review the output carefully
# Step 3: Execute only after confirming the preview is correct
jira-as time bulk-log -j "sprint = 456" -t 15m -c "Daily standup"

Time format

JIRA accepts human-readable time formats:

• 30m - 30 minutes
• 2h - 2 hours
• 1d - 1 day (8 hours by default)
• 1w - 1 week (5 days by default)
• 2d 4h 30m - Combined format

Configuration

Time tracking must be enabled in your JIRA project. If you receive an error about time tracking being disabled, ask your JIRA administrator to enable it.

Troubleshooting

Common Issues

"Time tracking is not enabled"

Time tracking must be enabled at the project level. Contact your JIRA administrator to enable it in Project Settings > Features > Time Tracking.

"Cannot log time to this issue"

Possible causes:

• The issue is in a status that doesn't allow time logging
• You don't have permission to log work on this issue
• The issue type doesn't support time tracking

"Worklog not found"

The worklog ID may be incorrect or the worklog was already deleted. Use jira-as time worklogs ISSUE-KEY to list valid worklog IDs.

Estimates not updating correctly

JIRA Cloud has a known bug (JRACLOUD-67539) where estimates may not update as expected. Workaround: Set both original and remaining estimates together:

jira-as time estimate PROJ-123 --original "2d" --remaining "1d"

Time logged but not showing in reports

• Check the --started date - worklogs are associated with the start date, not creation date
• Verify the correct --period filter is being used
• Ensure the user has permission to view the issue's worklogs

"Invalid time format"

Use JIRA's standard time notation:

• Correct: 2h, 1d 4h, 30m, 1w 2d
• Incorrect: 2 hours, 1.5h, 90 minutes

Bulk operation failures

When using bulk time logging:

1. Always use --dry-run first to preview changes
2. Check that all issues in the JQL results are accessible
3. Verify time tracking is enabled on all target projects

Permission Requirements

To use time tracking features, you typically need:

• Browse Projects - View issues and worklogs
• Work On Issues - Add worklogs to issues
• Edit All Worklogs - Modify/delete any user's worklogs (admin)
• Delete All Worklogs - Delete any user's worklogs (admin)

For detailed permission matrix, see Permission Matrix.

Advanced Troubleshooting

API rate limits

When performing bulk operations on large result sets, the CLI automatically retries with exponential backoff on 429 errors. To reduce load:

• Use smaller date ranges for reports
• Filter JQL to limit results before bulk operations

Timezone issues

Worklogs use UTC internally. If time appears on wrong date:

• Check your JIRA timezone settings
• Use explicit --started date when needed

Bulk operation timeouts

Large JQL result sets may timeout:

# Use smaller batches instead of one large query
jira-as time bulk-log -i PROJ-1,PROJ-2 -t 15m

Worklog visibility issues

If worklogs are logged but others cannot see them:

• Check worklog visibility settings
• Verify issue security scheme permissions

For complete error code reference, see Error Codes.

Common Questions

Why is my estimate not updating? JIRA Cloud bug (JRACLOUD-67539). Set both estimates together:

jira-as time estimate PROJ-123 --original 2d --remaining "1d 4h"

How do I log time for someone else? You need "Edit All Worklogs" permission. Most users can only log their own time.

Can I bill partial hours? Yes. Use minutes for precision: 1h 45m (not 1.75h). JIRA doesn't support decimal hours.

How does --adjust-estimate work?

Mode	Effect
auto	Reduces remaining by time logged
leave	No change to remaining estimate
new	Sets remaining to a new value
manual	Reduces remaining by specified amount

Advanced Guides

For specific roles and use cases, see:

Guide	Audience	Topics
IC Time Logging	Developers, QA	Daily habits, comment templates, special cases
Estimation Guide	PMs, Team Leads	Approaches, accuracy metrics, buffers
Team Policies	Managers, Admins	Policy templates, onboarding, compliance
Billing Integration	Finance, PMs	Invoicing, billable tracking, exports
Reporting Guide	Analysts, PMs	Reports, dashboards, JQL queries

Quick Reference

Reference	Content
Time Format	Format syntax, common values
JQL Snippets	Copy-paste queries for time tracking
Permission Matrix	Role-based permissions
Error Codes	Troubleshooting guide

Best Practices

For comprehensive guidance on time logging workflows, estimate management, and reporting patterns, see Best Practices Guide (navigation hub to all guides).

Related skills

• jira-issue: Create and manage issues (can set estimates on creation)
• jira-search: Search issues and view time tracking fields
• jira-agile: Sprint management with time tracking integration
• jira-bulk: Bulk operations at scale with dry-run support