bugzilla1
Command line tool for interacting with bugzilla
Usage
bugzilla [options]
[command]
[command-options]
Overview
bugzilla is a command line tool for interacting with a Bugzilla instance over REST or XMLRPC.
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
Options
--help, -h
Syntax: -h
show this help message and exit
--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 https://bugzilla.redhat.com
--nosslverify
Syntax: --nosslverify
Don't error on invalid bugzilla SSL certificate
--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.
--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
Options
These options are shared by some combination of the 'new', 'query', and 'modify' sub commands. Not every option works for each command though.
-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]}'
Options
These options are shared by several commands, for tweaking the text output of the command results.
--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
--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.
--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.
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
Options
Fields that take multiple values have a special input format.
Append: [email protected] Overwrite: [email protected] Remove: [email protected]
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
Options
--private
Syntax: --private
Mark new comment as private
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
Options
-p, --products
Syntax: --products
Get a list of products
-c, --components
Syntax: --components PRODUCT
List the components in the given product
-o, --component_owners
Syntax: --component_owners PRODUCT
List components (and their owners)
-v, --versions
Syntax: --versions PRODUCT
List the versions for the given product
--active-components
Syntax: --active-components
Only show active components. Combine with --components*
Bugzillarc config file
Both bugzilla and the python-bugzilla library will read a bugzillarc config file if it is present in the following 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.
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
•
|
|
|---|---|
•
|
|
•
|
|
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.
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).
Then use 'bugzilla --bugzilla URL login --api-key', which will ask for the API key, and save it to bugzillarc for you.
For older bugzilla instances, you will need to cache a login token with the "login" subcommand or the "--login" argument.
Additionally, the --no-cache-credentials option will tell the bugzilla tool to not save or use any authentication cache, including the bugzillarc file.
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), and 3 if the Bugzilla server throws an error.
Releases
5 releases since Debian 9 (Stretch); the text changed 3 times.
--active-components until Debian 10 (Buster);
--alias until Debian 10 (Buster);
--arch until Debian 10 (Buster);
--assigned_to until Debian 10 (Buster);
--assignee until Debian 10 (Buster);
--blocked until Debian 9 (Stretch);
--boolean_query until Debian 9 (Stretch);
--booleantype until Debian 9 (Stretch);
--bug_id until Debian 10 (Buster);
--bug_severity until Debian 9 (Stretch);
--bug_status until Debian 10 (Buster);
--bugzilla until Debian 10 (Buster);
--cc until Debian 9 (Stretch);
--cert until Debian 10 (Buster);
--close until Debian 10 (Buster);
--comment until Debian 10 (Buster);
--comment-tag until Debian 10 (Buster);
--component until Debian 10 (Buster);
--component_owners until Debian 10 (Buster);
--components until Debian 10 (Buster);
--components_file until Debian 9 (Stretch);
--cookiefile until Debian 10 (Buster);
--debug until Debian 10 (Buster);
--dependson until Debian 9 (Stretch);
--description until Debian 10 (Buster);
--devel_whiteboard until Debian 10 (Buster);
--dupeid until Debian 10 (Buster);
--emailtype until Debian 9 (Stretch);
--ensure-logged-in until Debian 10 (Buster);
--extra until Debian 10 (Buster);
--field until Debian 10 (Buster);
--file until Debian 10 (Buster);
--fixed_in until Debian 10 (Buster);
--flag until Debian 10 (Buster);
--from-url until Debian 10 (Buster);
--full until Debian 10 (Buster);
--get until Debian 10 (Buster);
--get-all until Debian 10 (Buster);
--getall until Debian 10 (Buster);
--help until Debian 10 (Buster);
--id until Debian 10 (Buster);
--ids until Debian 10 (Buster);
--internal_whiteboard until Debian 10 (Buster);
--keywords until Debian 9 (Stretch);
--keywords_type until Debian 9 (Stretch);
--login until Debian 10 (Buster);
--long_desc until Debian 9 (Stretch);
--no-cache-credentials until Debian 10 (Buster);
--nosslverify until Debian 10 (Buster);
--oneline until Debian 10 (Buster);
--os until Debian 10 (Buster);
--outputformat until Debian 10 (Buster);
--password until Debian 10 (Buster);
--priority until Debian 10 (Buster);
--private until Debian 10 (Buster);
--product until Debian 10 (Buster);
--products until Debian 10 (Buster);
--qa_contact until Debian 10 (Buster);
--qa_whiteboard until Debian 10 (Buster);
--quicksearch until Debian 10 (Buster);
--raw until Debian 10 (Buster);
--reporter until Debian 10 (Buster);
--reset-assignee until Debian 10 (Buster);
--reset-qa-contact until Debian 10 (Buster);
--savedsearch until Debian 10 (Buster);
--savedsearch-sharer-id until Debian 10 (Buster);
--severity until Debian 10 (Buster);
--short_desc until Debian 10 (Buster);
--status until Debian 10 (Buster);
--status_whiteboard until Debian 10 (Buster);
--status_whiteboard_type until Debian 9 (Stretch);
--sub-component until Debian 10 (Buster);
--summary until Debian 10 (Buster);
--tags until Debian 10 (Buster);
--target_milestone until Debian 10 (Buster);
--target_release until Debian 10 (Buster);
--tokenfile until Debian 10 (Buster);
--type until Debian 10 (Buster);
--url until Debian 10 (Buster);
--url_type until Debian 9 (Stretch);
--user until Debian 9 (Stretch);
--username until Debian 10 (Buster);
--verbose until Debian 10 (Buster);
--version until Debian 10 (Buster);
--versions until Debian 10 (Buster);
--whiteboard until Debian 10 (Buster);
-B until Debian 9 (Stretch);
-E until Debian 9 (Stretch);
-F until Debian 10 (Buster);
-K until Debian 9 (Stretch);
-U until Debian 9 (Stretch);
-W until Debian 9 (Stretch);
-a until Debian 10 (Buster);
-b until Debian 10 (Buster);
-c until Debian 10 (Buster);
-d until Debian 10 (Buster);
-e until Debian 10 (Buster);
-f until Debian 10 (Buster);
-g until Debian 10 (Buster);
-h until Debian 10 (Buster);
-i until Debian 10 (Buster);
-k until Debian 10 (Buster);
-l until Debian 10 (Buster);
-m until Debian 10 (Buster);
-o until Debian 10 (Buster);
-p until Debian 10 (Buster);
-q until Debian 10 (Buster);
-r until Debian 10 (Buster);
-s until Debian 10 (Buster);
-t until Debian 10 (Buster);
-u until Debian 10 (Buster);
-v until Debian 10 (Buster);
-w until Debian 10 (Buster);
-x until Debian 10 (Buster);
-z until Debian 10 (Buster).