Bug2Md.Tool 0.1.1

Bug2MD

Bug2MD is a .NET global tool that reads Azure DevOps bugs and generates clean Markdown files.

It is useful for bug investigation notes, handovers, daily updates, and coding-agent workflows.

Installation on Windows

Make sure the .NET 10 SDK is installed, then run:

dotnet tool install --global Bug2Md.Tool

Verify the installation:

bug2md --help

Installation on macOS

Make sure the .NET 10 SDK is installed, then run:

dotnet tool install --global Bug2Md.Tool

Add the .NET global tools directory to your PATH:

grep -qxF 'export PATH="$HOME/.dotnet/tools:$PATH"' ~/.zshrc 2>/dev/null || \
echo 'export PATH="$HOME/.dotnet/tools:$PATH"' >> ~/.zshrc

Reload your shell configuration:

source ~/.zshrc

Alternatively, close and reopen your terminal.

Verify the installation:

bug2md --help

Configure

Run the interactive setup:

bug2md configure

Or configure it in one command:

bug2md configure --organization my-org --project MyProject --output "D:\BugReports"

Bug2MD saves non-secret settings in:

%USERPROFILE%\.bug2md\config.json

Set Azure DevOps Access

Create an Azure DevOps PAT with Work Items: Read permission.

Bug2MD reads the PAT from BUG2MD_AZDO_PAT.

For the current PowerShell session:

$env:BUG2MD_AZDO_PAT="YOUR_PAT_HERE"

For the current Windows user:

[Environment]::SetEnvironmentVariable("BUG2MD_AZDO_PAT", "YOUR_PAT_HERE", "User")

Open a new terminal after setting a permanent environment variable.

Check Setup

Check local configuration:

bug2md doctor

Test Azure DevOps authentication:

bug2md auth test

List Bugs

List open bugs assigned to you:

bug2md list --assigned-to me

List bugs assigned to another user:

bug2md list --assigned-to user@example.com

Limit the number of results:

bug2md list --assigned-to me --top 10

Filter by state:

bug2md list --assigned-to me --state Active

Include closed bugs:

bug2md list --assigned-to me --include-closed

Show Bug Details

Show one bug:

bug2md show --bug-id 12345

Limit comments:

bug2md show --bug-id 12345 --comments-limit 5

Generate Markdown

Generate Markdown for one bug:

bug2md generate --bug-id 12345

Generate Markdown for your assigned open bugs:

bug2md generate --assigned-to me

Generate Markdown for a specific assigned user:

bug2md generate --assigned-to user@example.com

Generate only bugs in one state:

bug2md generate --assigned-to me --state Active

Include closed bugs:

bug2md generate --assigned-to me --include-closed

Choose an output folder:

bug2md generate --bug-id 12345 --output "D:\BugReports"

Overwrite an existing Markdown file:

bug2md generate --bug-id 12345 --overwrite

Limit comments in the generated file:

bug2md generate --bug-id 12345 --comments-limit 5

Security Notes

• Bug2MD only reads Azure DevOps work items.
• Your Azure DevOps PAT is not stored in config.json.
• The PAT is read from BUG2MD_AZDO_PAT.
• Generated files are skipped unless --overwrite is used.
• Do not publish real PATs, private organization URLs, client data, or real bug payloads.

Troubleshooting

If bug2md doctor says the PAT is missing, set BUG2MD_AZDO_PAT and open a new terminal.

If bug2md auth test fails, check:

• The organization name.
• The project name.
• The PAT value.
• The PAT permission: Work Items: Read.

If no bugs are listed, check that the bugs are assigned to the selected user and are not closed unless you used --include-closed.

Uninstall

To remove Bug2MD from your system, run:

dotnet tool uninstall --global Bug2Md.Tool

Verify that the tool was removed:

dotnet tool list --global