Relative date filtering

[sparrowt]

Describe the feature or problem you’d like to solve

When filtering by date it would be helpful to allow relative dates such as -7d for the last 7 days.

Although the docs are not at all clear, it seems you can do ranges but only with absolute dates:

gh search prs --updated ">=2026-01-01"

Proposed solution

It would be great to add support for negative offsets from today e.g. --updated ">=-1d" to find all PRs updated in the last 24h (or today + yesterday inclusive if the date filtering is only done by full day boundaries, I don't mind).

This will be useful for those wishing to automatically show only recently-updated PRs.

Additional context

It would also be helpful if the gh cli docs were more helpful about what date filters are supported.

For example gh search prs --help (and the online equivalent) lists all the following options:

--closed date             Filter on closed at date
--created date            Filter based on created at date
--merged-at date          Filter on merged at date
--updated date            Filter on last updated at date

but does not explain how to use them, either inline or with an example.

From guesswork (based on web github) and just trying stuff it seems that you can do the following:

YYYY-MM-DD
YYYY-MM-DD..YYYY-MM-DD
<YYYY-MM-DD
<=YYYY-MM-DD
>YYYY-MM-DD
>=YYYY-MM-DD

so it would be nice to have this documented, including any other options (if there are any).

[github-actions]

Thank you for your issue! We have categorized it as an enhancement (feature or improvement) request, and it has been added to our backlog. In doing so, we are not committing to implementing this feature at this time, but, we will consider it for future releases based on community feedback and our own product roadmap.

Unless you see the help wanted Contributions welcome label, we are not currently looking for external contributions for this feature.

If you come across this issue and would like to see it implemented, please add a thumbs up! This will help us prioritize the feature. Please only comment if you have additional information or viewpoints to contribute.

[BagToad]

Hey @sparrowt, thanks for the write up.

I think it's reasonable to add a few examples to something like gh search prs and gh search issues for how to do this date filtering.

The challenge with documentation here is that we should support everything that the issue search API/github.com UI supports. That's why we link to the documentation for github.com:

GitHub search syntax is documented at: https://docs.github.com/search-github/searching-on-github/searching-issues-and-pull-requests

On supported GitHub hosts, advanced issue search syntax can be used in the --search query. For more information about advanced issue search, see: https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/filtering-and-searching-issues-and-pull-requests#building-advanced-filters-for-issues

It's a challenge because to comprehensively stay up-to-date with our docs, we'd be duplicating the information in the docs for github.com and there'll always be drift there. The best thing to do is to go to the source of truth documentation, I think.

But yeah, for examples for date usage. I think that's totally reasonable 👍

Please let me know if I misunderstood anything 🙏

[BagToad]

Also, regarding the relative date filtering. gh should be able to do that with date:

   # macOS
   gh search prs --updated ">=$(date -v-7d +%Y-%m-%d)" --repo cli/cli
   
   # Linux
   gh search prs --updated ">=$(date -d '7 days ago' +%Y-%m-%d)" --repo cli/cli

[sparrowt]

I see, yes now that I carefully read the paragraphs at the top of https://cli.github.com/manual/gh_search_prs it makes more sense - I guess I was lazy to start with, but it would be nice to make it clearer so I think examples would go a long way.

https://docs.github.com/en/search-github/searching-on-github/searching-issues-and-pull-requests#search-by-when-an-issue-or-pull-request-was-created-or-last-updated links through to https://docs.github.com/en/search-github/getting-started-with-searching-on-github/understanding-the-search-syntax#query-for-dates so I wonder if something like this could be added under Examples:

# My PRs that were updated since a certain date. Relative dates are not supported, but can be constructed using `date`
# Supported syntax: https://docs.github.com/en/search-github/getting-started-with-searching-on-github/understanding-the-search-syntax#query-for-dates
gh search prs --author=@me --updated ">=2026-01-01"

I found myself searching the docstring for "date" and not finding anything so having the syntax link near to an example would be a bonus - but even just the example would be a good start.

P.S. bonus powershell option for anyone crazy enough to be using that (who me? never...)

--updated ">=$((Get-Date).AddDays(-7).ToString("yyyy-MM-dd"))"