GitHub CLI: Seamlessly Close Issues With `gh Pmu Close`

Hey guys! Let's talk about making your GitHub workflow even smoother with the GitHub CLI, specifically gh. We all know how awesome the gh tool is for managing repositories right from your terminal. But sometimes, you run into little quirks that can slow you down, right? Well, the folks working on gh-pmu have come up with a super neat enhancement that's going to save you a bunch of typing and prevent those annoying errors. We're talking about adding a new command, gh pmu close, which wraps the existing gh issue close command but brings some sweet alias support for close reasons. This is all about keeping things consistent with the rest of the gh-pmu conventions, which, if you're using it, you know loves its underscore-based aliases. So, buckle up, because we're diving deep into why this is a big deal and how it's going to make your life just that little bit easier.

The Problem: Inconsistent Closing Reasons

So, here's the deal, guys. The native gh issue close command is pretty cool, but it has this one little hang-up when it comes to specifying the reason why you're closing an issue. The --reason flag, or its shorter -r version, expects you to type out the reason exactly as it is, spaces and all. This means you have to be super careful. For instance, if you want to mark an issue as "not planned" because it's no longer a priority, you have to type it out as "not planned" with that pesky space in there. Same goes for other reasons like "completed". Now, this might seem like a minor thing, but it's a huge point of friction when you compare it to the rest of the gh-pmu ecosystem. If you've been using gh-pmu, you'll know that it has its own set of conventions, and it heavily favors using underscores instead of spaces for its aliases. Think about commands like in_progress which gh-pmu understands as "In progress", or in_review for "In review". It's intuitive, it's consistent, and it makes things flow much better.

The inconsistency hits hard when users, accustomed to the gh-pmu way, try to use underscores with the gh issue close --reason flag. You'd naturally think that not_planned would work, right? After all, that's how you handle similar concepts in other gh-pmu commands. But nope! If you try it, you'll get an error message that looks something like this: Error: invalid argument "not_planned" for "-r, --reason" flag. It's frustrating because you're doing what seems logical based on the tool's overall design, only to be met with a wall. This kind of discrepancy can really throw off your workflow, especially when you're in the zone and trying to close out a bunch of issues quickly. It forces you to stop, remember the exact syntax for the native gh command, and then retype it, which is just not ideal. The goal of CLI tools like gh and gh-pmu is to speed things up, not slow them down with rigid syntax requirements for common operations. This is precisely the problem the gh pmu close command aims to solve, bringing much-needed uniformity and user-friendliness to the issue closing process.

The Solution: Introducing gh pmu close

Alright guys, so to tackle this inconsistency head-on, the brilliant minds behind gh-pmu are proposing a fantastic new command: gh pmu close. This command is designed to be a super-convenient wrapper around the existing gh issue close functionality, but with a crucial upgrade – it understands and normalizes close reasons, bridging the gap between gh-pmu's underscore conventions and gh issue close's strict syntax. Let's break down exactly what this new command brings to the table. First and foremost, gh pmu close will accept both forms of input for the reason: the gh-pmu style with underscores and the native gh style with spaces. This means you can type not_planned or not planned, and the command will intelligently figure out that you mean "not planned". It'll also handle the straightforward completed reason without any fuss. This normalization is key because it means you don't have to remember which command expects which format anymore. You can stick to the gh-pmu convention you're already used to, making your commands more readable and less prone to errors. It's all about making the tool work for you, not the other way around.

But wait, there's more! The gh pmu close command also comes with an optional but incredibly useful flag: --update-status. What this bad boy does is, before closing the issue, it'll move the issue to the done status. Why is this cool? Well, in many project management workflows, especially those using GitHub Projects or similar boards, transitioning an issue to a 'done' or 'completed' state is a distinct step before it's fully closed. This flag adds that extra layer of workflow management directly into the closing command. So, you can close an issue and ensure it's also correctly marked as done in your project board, all in one go. This is a huge time-saver and helps maintain accurate project tracking. Plus, to ensure you don't lose any functionality, gh pmu close will support all the same flags that gh issue close currently does. This includes the --reason (-r) flag (now with alias support, as we've discussed) and the --comment (-c) flag for adding a closing comment. This means you get all the power of the original command, plus the added convenience and consistency of gh-pmu's user-friendly approach. It’s the best of both worlds, really, offering a more streamlined and integrated experience for anyone managing issues via the GitHub CLI.

Example Usage: Making It Real

Okay guys, let's see this magic in action! The proposed gh pmu close command isn't just a theoretical improvement; it's designed to be incredibly practical and easy to use in your everyday workflow. Imagine you're working on an issue, say issue number 123, and you've decided it's no longer relevant or planned. Instead of fumbling with the exact syntax for the --reason flag, you can now simply type:

gh pmu close 123 --reason not_planned

See? Clean, simple, and uses the gh-pmu underscore convention you're likely already comfortable with. But what if you prefer the original syntax, or you're switching between tools? No problem! The command is smart enough to understand that too. You could achieve the exact same result by typing:

gh pmu close 123 --reason "not planned"

This dual support means you can adopt the new command without breaking your existing habits or scripts. And if you need to add a comment explaining why you're closing the issue, say it's a duplicate of another issue, you can easily do that too. You can combine the reason and comment flags like this:

gh pmu close 123 -r not_planned -c "Duplicate of #100"

This command will close issue 123 with the reason "not planned" and add the specified comment, all in one go. It's incredibly efficient! Now, let's talk about that awesome --update-status flag we mentioned. Suppose you want to close issue 123, mark it as completed, and ensure your project board reflects this status update. You can do it with a single command:

gh pmu close 123 --reason completed --update-status

This single command will first ensure issue 123 is moved to the done state within your project tracking system (like GitHub Projects) and then proceed to close it. This integrated workflow management is a game-changer for keeping your project boards tidy and up-to-date with minimal effort. The goal here is to make common actions like closing issues as intuitive and frictionless as possible, allowing you to focus more on coding and less on command-line syntax.

Acceptance Criteria: What Makes It Official?

So, how do we know when this fantastic new gh pmu close command is ready for prime time, guys? The development team has laid out some clear Acceptance Criteria. Think of these as the checklist items that need to be ticked off to ensure the command works perfectly and delivers on its promise. First off, the most basic requirement: the gh pmu close command must successfully accept an issue number as input. This sounds obvious, but it's the foundation upon which everything else is built. You need to be able to tell the command which issue you want to close, so this is paramount.

Next up is the star of the show: the --reason flag. This flag needs to be robust. Specifically, it must accept not_planned (with the underscore) and correctly normalize it to the required "not planned" format for the underlying gh issue close command. This is the core of the alias support we've been talking about. Equally important, it must also accept the standard completed reason without any issues. No errors, no weird behavior, just a clean acceptance. Beyond the reason, the command needs to play nicely with other existing functionalities. This means the --comment flag, or its shorthand -c, must be passed through accurately to the gh issue close command. Any comment you provide should appear when the issue is closed, just as if you'd used the native command directly. This ensures users don't lose the ability to add context to their closures.

Then we have the powerful --update-status flag. If this flag is present, the command must perform the action of moving the issue to the done status before it proceeds to close the issue. This integrated workflow step is crucial for projects that rely on status transitions. Finally, to make sure everyone understands how to use this new command and its neat features, the help text needs to be updated. This means running gh pmu close --help should clearly document the alias support for reasons and explain the functionality of all flags, including --update-status. These criteria ensure that gh pmu close is not just functional but also user-friendly, consistent, and fully integrated into the existing gh ecosystem. It's all about delivering a polished and reliable tool for the community.

References: Where Did This Come From?

For those of you who like to know the backstory or want to dive deeper, it's helpful to know where this enhancement proposal originated. This specific improvement, the addition of the gh pmu close command with its intelligent handling of close reasons and the optional status update, stems directly from user feedback and observations during practical usage sessions. The core finding that prompted this work came from a session held on 2025-12-08. During this session, a key UX inconsistency was identified between the conventions followed by the main gh CLI tool and the conventions adopted by the gh-pmu extension. This mismatch, particularly around how issue closing reasons are specified, was highlighted as a significant point of friction for users who work with both tools. The goal is always to make the developer experience as seamless as possible, and this inconsistency was a clear barrier to that goal. By addressing it with a dedicated command like gh pmu close, the aim is to harmonize the workflow and eliminate the cognitive load associated with remembering different syntaxes for similar operations. It's a perfect example of how iterative improvements, informed by real-world usage, can significantly enhance the usability of command-line tools.