jira-time-tracking

# 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 | > **Note:** For `estimate`, use the long form `--output` - on that command `-o` is short for `--original`. For `export`, `-o/--output` is the output *file path* (see export-specific options below). ### 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) | | `--reduce-by TIME` | Amount to reduce estimate (for adjust=manual with log) | | `--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 (YYYY-MM format is only accepted by `export`, not `report`) | | `-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 | Usage error (invalid arguments); also used for authentication errors | ## Examples ### Log time to an issue ```bash # 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 ```bash # 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 ```bash # 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 ```bash # 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 ```bash # 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 a specific month using an explicit date range # (report does not accept YYYY-MM for --period; use `time export` for that) jira-as time report -p PROJ -s 2025-01-01 --until 2025-01-31 # 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 ```bash # 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 alice@company.com --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 ```bash # 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 ```bash # 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: ```bash # 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