BUGZILLA(1)

📦
version 3.3.0 · 2 versions
, in debian trixie, epel 10, fedora 43, fedora 44, nixos 26.05, nixpkgs unstable, ubuntu resolute, ubuntu stonking

💖 BUGZILLA(1) — User Commands 💖

okay bestie, welcome to the bugzilla(1) manual — it’s the command line tool for interacting with a Bugzilla, and it’s giving main character energy for your terminal. let’s go 💅✨

🌸 NAME 🌸

bugzilla — command line tool for interacting with Bugzilla. periodt. 💖

✨ SYNOPSIS ✨

bugzilla [options] [command] [command-options]

🦋 DESCRIPTION 🦋

bugzilla is a command line tool for interacting with a Bugzilla instance over REST or XMLRPC. no cap.

command is one of:

  • login — log into the given bugzilla instance
  • new — create a new bug
  • query — search for bugs matching given criteria
  • modify — modify existing bugs
  • attach — attach files to existing bugs, or get attachments
  • info — get info about the given bugzilla instance

🌍 GLOBAL OPTIONS 🌍

  • --help, -h — syntax: -h. show this help message and exit. iconic. ✨
  • --bugzilla — syntax: --bugzilla BUGZILLA. The bugzilla URL. Full API URLs are typically like:
* https://bugzilla.example.com/xmlrpc.cgi    # XMLRPC API
* https://bugzilla.example.com/rest/         # REST API

If a non-specific URL is passed, like 'bugzilla.redhat.com', bugzilla will try to probe whether the expected XMLRPC or REST path is available, preferring XMLRPC for backwards compatibility.

The default URL is https://bugzilla.redhat.com. 💅

  • --nosslverify — syntax: --nosslverify. Don't error on invalid bugzilla SSL certificate. bestie, be careful. 🫶
  • --cert — syntax: --cert CERTFILE. client side certificate file needed by the webserver.
  • --login — syntax: --login. Run interactive "login" before performing the specified command.
  • --username — syntax: --username USERNAME. Log in with this username.
  • --password — syntax: --password PASSWORD. Log in with this password.
  • --restrict-login — syntax: --restrict-login. The session (login token) will be restricted to the current IP address.
  • --ensure-logged-in — syntax: --ensure-logged-in. Raise an error if we aren't logged in to bugzilla. Consider using this if you are depending on cached credentials, to ensure that when they expire the tool errors, rather than subtly change output. lowkey important. 😭
  • --no-cache-credentials — syntax: --no-cache-credentials. Don't save any bugzilla tokens to disk, and don't use any pre-existing credentials.
  • --tokenfile — syntax: --tokenfile TOKENFILE. token file to use for bugzilla authentication.
  • --verbose — syntax: --verbose. give more info about what's going on.
  • --debug — syntax: --debug. output bunches of debugging info. 💀
  • --version — syntax: --version. show program's version number and exit.

🧸 STANDARD BUGZILLA OPTIONS 🧸

These options are shared by some combination of the 'new', 'query', and 'modify' sub commands. Not every option works for each command though. iykyk.

  • -p, --product — syntax: --product PRODUCT. Product name.
  • -v, --version — syntax: --version VERSION. Product version.
  • -c, --component — syntax: --component COMPONENT. Component name.
  • -s, --summary — syntax: --summary SUMMARY. Bug summary.
  • -l, --comment — syntax: --comment DESCRIPTION. Set initial bug comment/description.
  • --comment-tag — syntax: --comment-tag TAG. Comment tag for the new comment.
  • --sub-component — syntax: --sub-component SUB_COMPONENT. RHBZ sub component name.
  • -o, --os — syntax: --os OS. Operating system.
  • --arch — syntax: --arch ARCH. Arch this bug occurs on.
  • -x, --severity — syntax: --severity SEVERITY. Bug severity.
  • -z, --priority — syntax: --priority PRIORITY. Bug priority.
  • --alias — syntax: --alias ALIAS. Bug alias (name).
  • -s, --status — syntax: --status STATUS. Bug status (NEW, ASSIGNED, etc.).
  • -u, --url — syntax: --url URL. URL for further bug info.
  • -m --target_milestone — syntax: --target_milestone TARGET_MILESTONE. Target milestone.
  • --target_release — syntax: --target_release TARGET_RELEASE. RHBZ Target release.
  • --blocked — syntax: ...]. Bug IDs that this bug blocks.
  • --dependson — syntax: ...]. Bug IDs that this bug depends on.
  • --keywords — syntax: ...]. Bug keywords.
  • --groups — syntax: ...]. Which user groups can view this bug.
  • --cc — syntax: ...]. CC list.
  • -a, --assignee, --assigned_to — syntax: --assigned_to ASSIGNED_TO. Bug assignee.
  • -q, --qa_contact — syntax: --qa_contact QA_CONTACT. QA contact.
  • -f, --flag — syntax: --flag FLAG. Set or unset a flag. For example, to set a flag named devel_ack, do --flag devel_ack+ Unset a flag with the 'X' value, like --flag needinfoX.
  • --tags — syntax: --tags TAG. Set (personal) tags field.
  • -w, --whiteboard — syntax: --whiteboard WHITEBOARD. Whiteboard field.
  • --devel_whiteboard — syntax: --devel_whiteboard DEVEL_WHITEBOARD. RHBZ devel whiteboard field.
  • --internal_whiteboard — syntax: --internal_whiteboard INTERNAL_WHITEBOARD. RHBZ internal whiteboard field.
  • --qa_whiteboard — syntax: --qa_whiteboard QA_WHITEBOARD. RHBZ QA whiteboard field.
  • -F, --fixed_in — syntax: --fixed_in FIXED_IN. RHBZ 'Fixed in version' field.
  • --field — syntax: --field FIELD=VALUE. Manually specify a bugzilla API field. FIELD is the raw name used by the bugzilla instance. For example if your bugzilla instance has a custom field cf_my_field, do: --field cf_my_field=VALUE.
  • --field-json — syntax: --field-json JSONSTRING. Specify --field data as a JSON string. Example: --field-json '{"cf_my_field": "VALUE", "cf_array_field": [1, 2]}'.

🎀 OUTPUT OPTIONS 🎀

These options are shared by several commands, for tweaking the text output of the command results. slay.

  • --full — syntax: --full. output detailed bug info.
  • -i, --ids — syntax: --ids. output only bug IDs.
  • -e, --extra — syntax: --extra. output additional bug information (keywords, Whiteboards, etc.).
  • --oneline — syntax: --oneline. one line summary of the bug (useful for scripts).
  • --json — syntax: --json. output bug contents in JSON format.
  • --includefield — syntax: --includefield. Pass the field name to bugzilla include_fields list. Only the fields passed to include_fields are returned by the bugzilla server. This can be specified multiple times.
  • --extrafield — syntax: --extrafield. Pass the field name to bugzilla extra_fields list. When used with --json this can be used to request bugzilla to return values for non-default fields. This can be specified multiple times.
  • --excludefield — syntax: --excludefield. Pass the field name to bugzilla exclude_fields list. When used with --json this can be used to request bugzilla to not return values for a field. This can be specified multiple times.
  • --raw — syntax: --raw. raw output of the bugzilla contents. This format is unstable and difficult to parse. Please use the --json instead if you want maximum output from the bugzilla. bestie, don't parse raw. just don't. 💀
  • --outputformat — syntax: --outputformat OUTPUTFORMAT. Print output in the form given. You can use RPM-style tags that match bug fields, e.g.: '%{id}: %{summary}'.

The output of the bugzilla tool should NEVER BE PARSED unless you are using a custom --outputformat. For everything else, just don't parse it, the formats are not stable and are subject to change. periodt. 🔥

--outputformat allows printing arbitrary bug data in a user preferred format. For example, to print a returned bug ID, component, and product, separated with ::, do:

--outputformat "%{id}::%{component}::%{product}"

The fields (like 'id', 'component', etc.) are the names of the values returned by bugzilla's API. To see a list of all fields, check the API documentation in the 'SEE ALSO' section. Alternatively, run a 'bugzilla --debug query ...' and look at the key names returned in the query results. Also, in most cases, using the name of the associated command line switch should work, like --bug_status becomes %{bug_status}, etc.

🔎 ‘QUERY’ SPECIFIC OPTIONS 🔎

Certain options can accept a comma separated list to query multiple values, including --status, --component, --product, --version, --id.

Note: querying via explicit command line options will only get you so far. See the --from-url option for a way to use powerful Web UI queries from the command line.
  • -b, --bug_id, --id — syntax: --id ID. specify individual bugs by IDs, separated with commas.
  • -r, --reporter — syntax: --reporter REPORTER. Email: search reporter email for given address.
  • --quicksearch — syntax: --quicksearch QUICKSEARCH. Search using bugzilla's quicksearch functionality.
  • --savedsearch — syntax: --savedsearch SAVEDSEARCH. Name of a bugzilla saved search. If you don't own this saved search, you must passed --savedsearch_sharer_id.
  • --savedsearch-sharer-id — syntax: --savedsearch-sharer-id SAVEDSEARCH_SHARER_ID. Owner ID of the --savedsearch. You can get this ID from the URL bugzilla generates when running the saved search from the web UI.
  • --from-url — syntax: --from-url WEB_QUERY_URL. Make a working query via bugzilla's 'Advanced search' web UI, grab the url from your browser (the string with query.cgi or buglist.cgi in it), and --from-url will run it via the bugzilla API. Don't forget to quote the string! This only works for Bugzilla 5 and Red Hat bugzilla. 💅

🛠️ ‘MODIFY’ SPECIFIC OPTIONS 🛠️

Fields that take multiple values have a special input format.

Append: --cc=foo@example.com
Overwrite: --cc==foo@example.com
Remove: --cc=-foo@example.com

Options that accept this format: --cc, --blocked, --dependson, --groups, --tags, whiteboard fields.

  • -k, --close RESOLUTION — syntax: RESOLUTION. Close with the given resolution (WONTFIX, NOTABUG, etc.).
  • -d, --dupeid — syntax: --dupeid ORIGINAL. ID of original bug. Implies --close DUPLICATE.
  • --private — syntax: --private. Mark new comment as private.
  • --reset-assignee — syntax: --reset-assignee. Reset assignee to component default.
  • --reset-qa-contact — syntax: --reset-qa-contact. Reset QA contact to component default.
  • --minor-update — syntax: --minor-update. Request bugzilla to not send any email about this change. lowkey sneaky but okay. 🙈

🐣 ‘NEW’ SPECIFIC OPTIONS 🐣

  • --private — syntax: --private. Mark new comment as private.

📎 ‘ATTACH’ OPTIONS 📎

  • -f, --file — syntax: --file FILENAME. File to attach, or filename for data provided on stdin.
  • -d, --description — syntax: --description DESCRIPTION. A short description of the file being attached.
  • -t, --type — syntax: --type MIMETYPE. Mime-type for the file being attached.
  • -g, --get — syntax: --get ATTACHID. Download the attachment with the given ID.
  • --getall — syntax: --getall BUGID. Download all attachments on the given bug.
  • --ignore-obsolete — syntax: --ignore-obsolete. Do not download attachments marked as obsolete.
  • -l, --comment — syntax: --comment COMMENT. Add comment with attachment.

✨ ‘INFO’ OPTIONS ✨

okay so these are the info-gathering girlies — no bug editing, just metadata. 💅

  • -p, --products — Syntax: --products. Get a list of products. That's it, that's the whole vibe. 🛍️
  • -c, --components — Syntax: --components PRODUCT. List the components in the given product. You gotta pass a PRODUCT. 🧩
  • -o, --component_owners — Syntax: --component_owners PRODUCT. List components (and their owners). So you get the component plus who's responsible for it. 👑
  • -v, --versions — Syntax: --versions PRODUCT. List the versions for the given product. Version check but make it bugzilla. 📦
  • --active-components — Syntax: --active-components. Only show active components. Combine with --components*. So it's like a filter for the active girlies only. ✨

🎀 BUGZILLARC CONFIG FILE 🎀

Both bugzilla and the python-bugzilla library will read a bugzillarc config file if it is present in these locations:

  • /etc/bugzillarc
  • ~/.bugzillarc
  • ~/.config/python-bugzilla/bugzillarc

The contents of the files are processed and merged together in the order they are listed above. So yeah, they stack. 🫶

The main usage for bugzillarc is to store API keys for your bugzilla URLs:

[bugzilla.example.com]
api_key=INSERT-YOUR-API-KEY-HERE

[bugzilla.redhat.com]
api_key=MY-REDHAT-API-KEY-BLAH

The sections must be hostnames. Other values that can be set per hostname section are

  • user: default auth username
  • password: default auth password
  • cert: default client side certificate

A [DEFAULTS] section is also accepted, which takes the following values:

  • url: default bugzilla URL

🔐 AUTHENTICATION CACHE AND API KEYS 🔐

Some command usage will require an active login to the bugzilla instance. For example, if the bugzilla instance has some private bugs, those bugs will be missing from query output if you do not have an active login. So private bugs ghost you. 👻

If you are connecting to a bugzilla 5.0 or later instance, the best option is to use bugzilla API keys. From the bugzilla web UI, log in, navigate to Preferences->API Keys, and generate a key (it will be a long string of characters and numbers). It's giving secret password but make it API. 🔑

Then use bugzilla --bugzilla URL login --api-key, which will ask for the API key, and save it to bugzillarc for you. Bestie behavior. 🫶

For older bugzilla instances, you will need to cache a login token with the "login" subcommand or the "--login" argument. Old school, still valid. 💅

Additionally, the --no-cache-credentials option will tell the bugzilla tool to not save or use any authentication cache, including the bugzillarc file. No caching, no remembering, just vibes. 🙈

🌈 EXAMPLES 🌈

bugzilla query --bug_id 62037

bugzilla query --version 15 --component python-bugzilla

bugzilla login

bugzilla new -p Fedora -v rawhide -c python-bugzilla \
  --summary "python-bugzilla causes headaches" \
  --comment "python-bugzilla made my brain hurt when I used it."

bugzilla attach --file ~/Pictures/cam1.jpg --desc "me, in pain"
$BUGID

bugzilla attach --getall $BUGID

bugzilla modify --close NOTABUG --comment "Actually, you're
hungover." $BUGID

🚦 EXIT STATUS 🚦

bugzilla normally returns 0 if the requested command was successful. Otherwise, exit status is:

  • 1 if bugzilla is interrupted by the user (or a login attempt fails)
  • 2 if a socket error occurs (e.g. TCP connection timeout)
  • 3 if the Bugzilla server throws an error

💀 BUGS 💀

Please report any bugs as github issues at https://github.com/python-bugzilla/python-bugzilla

👀 SEE ALSO 👀

and that's the whole BUGZILLA(1) page, bestie! The footer is just BUGZILLA(1) — no version, no date, just the name — so that's the tea. Mwah! 💖🫶✨

📦 where this page comes from