Skip to content

JSON and CSV output ​

Use --format json or --format csv for scripts. Table output is meant for people and may change; the JSON schema is versioned.

sh
ghusage weekly --format json > weekly.json
ghusage prs --format csv > prs.csv

Unless --include-private is given, JSON and CSV hide private repository names, titles and URLs. See Private repositories.

Conventions ​

  • Schema version. Every report has "schema_version": 1. Fields may be added in a compatible way without changing the version; removing or changing the meaning of a field changes it.
  • Timestamps are RFC 3339 / ISO 8601 strings. period.start and period.end use the report's time zone offset (2026-11-02T00:00:00+09:00); all other timestamps are UTC (2026-11-01T15:00:00Z).
  • Durations are whole seconds (fields ending in _secs, and timing statistics).
  • null versus 0. A count is 0 when nothing happened. null means unknown or not applicable: no last activity, no merge, no CI result, statistics over zero pull requests, an unknown account ID.
  • Field order is stable but should not be relied on. Arrays have a defined order, described below.
  • Command-specific sections are omitted (not null) when the command does not produce them.

Report object ​

All period reports (overview, daily, weekly, monthly, yearly, repos, prs, reviews, comments, issues) print one JSON object with these root fields:

FieldTypeDescription
schema_versioninteger1
accountobjectWho was analyzed: login, id (GitHub node ID or null), is_authenticated_user
periodobjectstart (inclusive) and end (exclusive), RFC 3339 in the report time zone
timezonestringIANA time zone used for calendar boundaries
metricsSummarySummary of the whole period
snapshotSnapshotCurrent-state values
repositoriesarray of RepoSummaryPer-repository summaries, ordered by your activity then name
activity_breakdownarray of BucketSummaryPer-bucket summaries in time order. Daily buckets unless the command is weekly, monthly or yearly
granularitystringday, week, month or year. Present only for daily, weekly, monthly, yearly
coveragearray of CoverageSummaryOne entry per data kind
synced_attimestamp or nullWhen the last sync of this account finished
private_repositories_redactedbooleantrue when private names were hidden (JSON/CSV without --include-private)

Command-specific fields:

CommandFields
prspull_requests (array of PrRow), intensity (Intensity), timing (TimingStats)
reviewsreviews_submitted, reviews_received (arrays of ReviewRow)
commentscomments (array of CommentRow)
issuesissues (array of IssueRow)

Definitions of every count are in Metric definitions.

Summary ​

FieldType
commits, merge_commitsinteger
prs_created, prs_merged, merges_performed, merges_unknown_actorinteger
prs_closed_without_merge, prs_reopenedinteger
reviews_submittedReviewCounts
reviewed_prsinteger (unique count)
reviews_receivedReviewCounts
reviews_received_from_bots, review_dismissals_performedinteger
comments_written, comments_receivedCommentCounts
review_responses, pr_commits, force_pushesinteger
coordination_actions, metadata_actionsinteger
issues_opened, issues_closed, issues_reopenedinteger
active_prs, active_prs_all_participantsinteger (unique counts)
pr_internal_eventsinteger
ciobject: passed, failed, pending, other (integers). Never part of activity
active_daysinteger
last_activitytimestamp or null
diff_statsDiffTotals

ReviewCounts ​

total, approved, changes_requested, commented, dismissed_unknown_state (integers).

CommentCounts ​

total, conversation, inline, review_summary (integers). total is the sum of the three types.

DiffTotals ​

Lines added and deleted by your counted commits. See Lines changed.

FieldTypeDescription
commitsintegerNon-merge commits counted in commits
excludedintegerOf those, commits left out of the line totals because their changes are counted through other commits
commits_with_statsintegerOf the remaining commits - excluded, commits with known line counts
additions, deletionsinteger or nullSums over the commits_with_stats commits only; null when coverage is unavailable
coveragestringno_commits, complete, partial or unavailable

additions and deletions are null when coverage is unavailable: no commit has known line counts, so the sums are unknown, not zero. With partial they cover only some commits; check coverage before using them.

json
"diff_stats": {
  "commits": 42,
  "excluded": 6,
  "commits_with_stats": 30,
  "additions": 1830,
  "deletions": 612,
  "coverage": "partial"
}

Snapshot ​

FieldDescription
open_prsYour pull requests that are open as of their last sync
open_issues_authoredIssues you opened that are currently open
threadsReview threads of pull requests active in the period: total, open, resolved, outdated

RepoSummary ​

FieldDescription
repository_idGitHub node ID of the repository
full_nameowner/name (redacted for private repositories)
visibilitypublic, private, internal or unknown
ownedWhether you own it (see CLI reference)
accessiblefalse when GitHub refused access to the repository (HTTP 403 or 404) during a sync; cached data is kept
summarySummary for this repository

BucketSummary ​

FieldDescription
bucket.keyFirst local date of the calendar bucket (YYYY-MM-DD)
bucket.label2026-11-21 (day), 2026-W47 (ISO week), 2026-11 (month)
bucket.start, bucket.endExact UTC range of the bucket, clipped to the period
summarySummary for the bucket

CoverageSummary ​

FieldDescription
kindcommits, pull_requests or issues
statuscomplete, partial, not_available, not_yet_synced or unknown for the whole period
scopesWhat was fetched, as human-readable descriptions
segmentsArray of {start, end, status, reason} covering the period in order; reason explains non-complete segments or is null

The report's overall coverage is complete only if every entry is complete; --require-complete uses that.

PrRow ​

FieldDescription
pr_idGitHub node ID of the pull request
repositoryowner/name
number, title, urlPull request number, title and URL
authorAuthor login (unknown if not known)
stateCurrent state: open, closed, merged
is_draftCurrent draft flag
created_at, merged_atTimestamps (merged_at is null if not merged)
events, events_by_subjectCounted non-CI events in the period by anyone / by you
commits, reviews, comments, participantsCounts in the period
discussion_participantsDistinct known accounts that wrote a conversation, inline or review summary comment in the period
threadsReview threads with an inline comment in the period
last_activityLatest event time in the period (commits use the selected --commit-date)
latest_ciCurrent CI state of the head commit: success, failure, pending, neutral, skipped, cancelled, unknown, or null
diffPrDiff or null when not known

Ordered by --sort (largest or newest first), then repository and number.

PrDiff ​

The pull request's diff between its base and head as of the last sync. It is a snapshot of the pull request, not changes made in the period. See Pull request changes.

FieldDescription
additions, deletionsLines added and deleted (integers)
changed_filesNumber of changed files
observed_atWhen the diff was fetched

Intensity ​

prs (number of pull requests), and events_per_pr, reviews_per_pr, comments_per_pr, commits_per_pr, participants_per_pr, discussion_participants_per_pr, threads_per_pr, active_days_per_pr, each a Stats object or null when there are no pull requests.

TimingStats ​

time_to_first_review, creation_to_merge, review_to_next_author_activity, first_to_last_activity: each a Stats object in seconds, or null when no pull request has that value. See lifecycle timing.

Stats ​

count, min, median, mean, p90 (nearest-rank 90th percentile), max. Numbers may be fractional.

ReviewRow ​

FieldDescription
event_idStable event identifier
submitted_atSubmission time
reviewerReviewer login
stateAPPROVED, CHANGES_REQUESTED, COMMENTED, DISMISSED (original state unknown), or null
repositoryowner/name
pr_idGitHub node ID of the reviewed pull request, or null
pr_number, pr_titlePull request number and title (or null)
urlLink to the review, or null

reviews_submitted lists your counted reviews; reviews_received lists reviews by others on your pull requests. Both in time order.

CommentRow ​

FieldDescription
event_idStable event identifier
created_atCreation time
authorAuthor login
kindconversation_comment, inline_comment or review_summary
written_by_subjecttrue for comments you wrote
repository, pr_numberWhere the comment is
pr_idGitHub node ID of the pull request, or null
editedWhether the comment was edited
urlLink, or null

Lists comments you wrote and comments others wrote on your pull requests, in time order.

IssueRow ​

FieldDescription
issue_idGitHub node ID
repository, number, title, urlThe issue
is_openCurrent state
opened_in_periodWhether you opened it in the period
closed_in_period, reopened_in_periodClose / reopen events by you in the period

Ordered by repository and number.

Pull request detail (ghusage pr) ​

FieldDescription
schema_version, account, timezoneAs in reports
pr_id, repository, number, title, urlThe pull request
authorAuthor login
state, is_draftCurrent state
created_at, merged_at, closed_atTimestamps (null when not applicable)
merged_byMerger login, or null when not merged or unknown
latest_ciCurrent CI state of the head commit (string) or null
commits, removed_commitsCommits currently in the pull request / commits removed by force pushes
reviewsReviewCounts
commentsCommentCounts
review_threadstotal, open, resolved, outdated (current state)
participantsLogins of known accounts with counted non-CI events, sorted
discussion_participantsLogins of known accounts that wrote a conversation, inline or review summary comment, sorted
commit_authorsArray of {author, commits}: commits currently in the pull request by commit author, most first
timingtime_to_first_review_secs, creation_to_merge_secs, review_to_next_author_activity_secs, first_to_last_activity_secs (integers or null)
diffPrDiff as of the last sync, or null when not known
timelineArray of TimelineEntry in event order (filtered by --event-type)
coverageCoverage status of this pull request's data
synced_atWhen the pull request was last fetched
private_repositories_redactedAs in reports

TimelineEntry ​

FieldDescription
event_idStable event identifier
occurred_atWhen it happened (for commits: the commit time, not the push time)
observed_atWhen ghusage fetched it
actor, actor_kindLogin (unknown if not known) and user, bot, organization, mannequin or unknown
event_typeOne of the event types listed in the CLI reference
labelHuman-readable event name
detailExtra information (review state, short SHA, label, previous title, CI check and outcome, notes such as "thread reply only, not counted as a review", "edited", "via merge", "no longer present"), or null
urlLink, or null
removed_observed_atWhen the item was found to be gone, or null

Events at the same instant are ordered by the natural order of a pull request's life (opened, commits, force pushes, ..., merged, closed, reopened).

Commit (ghusage commit) ​

FieldDescription
schema_versionAs in reports
repository, sha, urlThe commit (url is its page on GitHub, or null)
messageThe full commit message
author, committer{name, login, date}: git name, linked GitHub login and date (each may be null)
parentsSHAs of the parent commits
is_mergeWhether the commit has more than one parent
statsfiles, additions, deletions, total
filesArray of {filename, previous_filename, status, additions, deletions, changes, patch_available}; with --patch also patch (unified diff) when GitHub returned one
files_truncatedWhether some changed files are not listed
sourcecache or github
fetched_atWhen the commit was fetched from GitHub
private_repositories_redactedAs in reports

ghusage commit has no CSV output.

Other commands ​

sync ​

ghusage sync --format json:

FieldDescription
statuscomplete or partial
commits_foundDistinct commits found by commit search and the default-branch commit lists (commits found only inside pull requests are not included)
pull_requests_found, pull_requests_fetched, pull_requests_unchangedPull requests found by search / fetched / skipped as unchanged
issues_found, issues_fetched, issues_unchangedIssues found by search / fetched / skipped as unchanged
failuresDescriptions of pull requests or issues that failed or were partially fetched
coverageCoverage records written: kind, start, end, status, scope, reason, recorded_at
apirequests, retries, rate_limit_waits, total_api_time_ms, bytes_received (including the line count requests of --diff-stats)
diff_statsOnly with --diff-stats: commits (your non-merge commits in the period whose line counts go into the totals), already_known (already in the cache, not fetched again), fetched (fetched now), unavailable (not returned by GitHub; left unknown)

doctor ​

{"ok": true, "checks": [{"ok": true, "message": "..."}]}

auth status ​

authenticated, source, login, id, scopes (array or null), rate_limit (core_remaining, core_limit, core_reset, search_remaining, search_limit, graphql_remaining, graphql_limit, or null).

cache status ​

path, file_size_bytes, schema_version, account, repositories, pull_requests, issues, events, last_sync (started_at, finished_at, status, message, or null), coverage_last_30_days (array of CoverageSummary).

CSV ​

CSV output is one flat table per command, with a header row. Unknown values are empty cells; zero is written as 0. Timestamps are RFC 3339 in UTC. Booleans are true / false. Free text (titles, details) has control characters removed, and a leading =, +, - or @ is prefixed with ' so spreadsheets do not evaluate it as a formula.

overview, daily, weekly, monthly, yearly ​

One row per calendar bucket (overview produces daily rows):

text
period,start,end,commits,merge_commits,prs_created,prs_merged,merges_performed,prs_closed_without_merge,reviews_submitted,reviewed_prs,reviews_received,comments_written,comments_received,review_responses,pr_commits,issues_opened,issues_closed,active_prs,pr_internal_events,ci_passed,ci_failed,additions,deletions,line_count_commits,line_count_commits_known,line_count_commits_excluded,line_count_coverage,coverage

period is the bucket label, reviews_submitted / reviews_received are totals, comments_written / comments_received are totals of all three types, and coverage is the combined coverage of that bucket. The line count columns are described below.

repos ​

text
repository,visibility,owned,accessible,commits,prs_created,prs_merged,reviews_submitted,comments_written,issues_opened,active_prs,pr_internal_events,additions,deletions,line_count_commits,line_count_commits_known,line_count_commits_excluded,line_count_coverage,last_activity,period_coverage

Line count columns ​

ColumnDescription
additions, deletionsdiff_stats.additions and diff_stats.deletions. Empty when no commit has known line counts (unavailable); with partial they cover only the commits with known counts
line_count_commitsCommits whose line counts go into the sums: diff_stats.commits - diff_stats.excluded
line_count_commits_knownOf those, commits with known line counts (diff_stats.commits_with_stats)
line_count_commits_excludedCommits left out as counted through other commits (diff_stats.excluded)
line_count_coverageno_commits, complete, partial or unavailable

The prs CSV has no line count columns; use JSON for pull request diffs.

prs ​

text
repository,number,title,state,draft,author,created_at,merged_at,events,events_by_you,commits,reviews,comments,participants,discussion_participants,threads,last_activity,latest_ci,url,period_coverage

reviews ​

text
direction,submitted_at,reviewer,state,repository,pr_number,url,period_coverage

direction is submitted or received.

comments ​

text
created_at,author,kind,written_by_you,repository,pr_number,edited,url,period_coverage

issues ​

text
repository,number,title,open,opened_in_period,closed_in_period,reopened_in_period,url,period_coverage

pr ​

The timeline of the pull request, one row per event:

text
occurred_at,actor,actor_kind,event_type,detail,removed_observed_at,url

period_coverage is the overall coverage of the whole period. sync, doctor, auth status, cache status and tui have no CSV form; with --format csv they fail with exit code 2:

text
error: --format csv is not available for this command; use table or json

Private repositories ​

Without --include-private, JSON and CSV output hide information about non-public (private and internal) repositories. Numbers are identical either way.

ItemReplaced with
Repository name<owner>/repo-<8 hex characters>, where the owner is your login for repositories you own and private otherwise. The suffix is derived from the repository ID, so it is stable across runs
Pull request and issue titles[private]
Pull request and issue URLsempty string
Review, comment and event URLs, repository URLsnull
Review thread file paths, label and milestone names, previous titles, CI check namesremoved
Repository names in coverage reasons and in sync failures[private repository] (any repository not known to be public)
ghusage commit of a repository not known to be publicrepository private/repo-<8 hex characters>, url null, message [private], file paths [private], no previous paths, diffs and git names removed

Logins of people (yours and others') and GitHub node IDs are not hidden. Table output and the terminal UI always show real names, because they are shown only to you.