.TH bugzilla 1  "Mar 30, 2017" "version 2.1.0" "User Commands"
.SH NAME
bugzilla \- command-line interface to Bugzilla over XML-RPC
.SH SYNOPSIS
.B bugzilla
[\fIoptions\fR] [\fIcommand\fR] [\fIcommand-options\fR]
.SH DESCRIPTION
.PP
.BR bugzilla
is a command-line utility that allows access to the XML-RPC interface provided
by Bugzilla.
.PP
\fIcommand\fP is one of:
.br
.I \fR * login - log into the given bugzilla instance
.br
.I \fR * new - create a new bug
.br
.I \fR * query - search for bugs matching given criteria
.br
.I \fR * modify - modify existing bugs
.br
.I \fR * attach - attach files to existing bugs, or get attachments
.br
.I \fR * info - get info about the given bugzilla instance
.SH GLOBAL OPTIONS
.IP "--version"
show program's version number and exit
.IP "--help, -h"
show this help message and exit
.IP "--bugzilla=BUGZILLA"
bugzilla XMLRPC URI. default: https://bugzilla.redhat.com/xmlrpc.cgi
.IP "--nosslverify"
Don't error on invalid bugzilla SSL certificate
.IP "--cert=CERTFILE"
client side certificate file needed by the webserver.
.IP "--login"
Run interactive "login" before performing the specified command.
.IP "--username=USERNAME"
Log in with this username
.IP "--password=PASSWORD"
Log in with this password
.IP "--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.
.IP "--no-cache-credentials"
Don't save any bugzilla cookies or tokens to disk, and don't use any pre-existing credentials.
.IP "--cookiefile=COOKIEFILE"
cookie file to use for bugzilla authentication
.IP "--tokenfile=TOKENFILE"
token file to use for bugzilla authentication
.IP "--verbose"
give more info about what's going on
.IP "--debug"
output bunches of debugging info
.IP "--version"
show program's version number and exit

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

.IP "--product=PRODUCT, -p PRODUCT"
Product name
.IP "--version=VERSION, -v VERSION"
Product version
.IP "--component=COMPONENT, -c COMPONENT"
Component name
.IP "--summary=SUMMARY, -s SUMMARY, --short_desc=SUMMARY"
Bug summary
.IP "--comment=DESCRIPTION, -l DESCRIPTION"
Set initial bug comment/description
.IP "--comment-tag=TAG"
Comment tag for the new comment
.IP "--sub-component=SUB_COMPONENT"
RHBZ sub component name
.IP "--os=OS, -o OS"
Operating system
.IP "--arch=ARCH"
Arch this bug occurs on
.IP "--severity=SEVERITY, -x SEVERITY"
Bug severity
.IP "--priority=PRIORITY, -z PRIORITY"
Bug priority
.IP "--alias=ALIAS"
Bug alias (name)
.IP "--status=STATUS, -s STATUS, --bug_status=STATUS"
Bug status (NEW, ASSIGNED, etc.)
.IP "--url=URL, -u URL"
URL for further bug info
.IP "--target_milestone=TARGET_MILESTONE, -m TARGET_MILESTONE"
Target milestone
.IP "--target_release=TARGET_RELEASE"
RHBZ Target release
.IP "--blocked=BUGID[, BUGID, ...]"
Bug IDs that this bug blocks
.IP "--dependson=BUGID[, BUGID, ...]"
Bug IDs that this bug depends on
.IP "--keywords=KEYWORD[, KEYWORD, ...]"
Bug keywords
.IP "--groups=GROUP[, GROUP, ...]"
Which user groups can view this bug
.IP "--cc=CC[, CC, ...]"
CC list
.IP "--assigned_to=ASSIGNED_TO, -a ASSIGNED_TO, --assignee ASSIGNED_TO"
Bug assignee
.IP "--qa_contact=QA_CONTACT, -q QA_CONTACT"
QA contact
.IP "--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
.IP "--tags=TAG"
Set (personal) tags field
.IP "--whiteboard WHITEBOARD, -w WHITEBOARD, --status_whiteboard WHITEBOARD"
Whiteboard field
.IP "--devel_whiteboard DEVEL_WHITEBOARD"
RHBZ devel whiteboard field
.IP "--internal_whiteboard INTERNAL_WHITEBOARD"
RHBZ internal whiteboard field
.IP "--qa_whiteboard QA_WHITEBOARD"
RHBZ QA whiteboard field
.IP "--fixed_in FIXED_IN, -F FIXED_IN
RHBZ 'Fixed in version' field
.IP "--field=FIELD=VALUE"
Manually specify a bugzilla XMLRPC 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


.SH Output options
.PP
These options are shared by several commands, for tweaking the text output of the command results.
.IP "--full, -f"
output detailed bug info
.IP "--ids, -i"
output only bug IDs
.IP "--extra, -e"
output additional bug information (keywords, Whiteboards, etc.)
.IP "--oneline"
one line summary of the bug (useful for scripts)
.IP "--raw"
raw output of the bugzilla contents
.IP "--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 XMLRPC interface. 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.


.SH \[oq]query\[cq] 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.
.IP "--id ID, -b ID, --bug_id ID"
specify individual bugs by IDs, separated with commas
.IP "--reporter REPORTER, -r REPORTER"
Email: search reporter email for given address
.IP "--quicksearch QUICKSEARCH"
Search using bugzilla's quicksearch functionality.
.IP "--savedsearch SAVEDSEARCH"
Name of a bugzilla saved search. If you don't own this saved search, you must passed --savedsearch_sharer_id.
.IP "--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.
.IP "--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


.SH \[oq]modify\[cq] 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.
.IP "--close RESOLUTION, -k RESOLUTION"
Close with the given resolution (WONTFIX, NOTABUG, etc.)
.IP "--dupeid ORIGINAL, -d ORIGINAL"
ID of original bug. Implies --close DUPLICATE
.IP "--private"
Mark new comment as private
.IP "--reset-assignee"
Reset assignee to component default
.IP "--reset-qa-contact"
Reset QA contact to component default


.SH \[oq]attach\[cq] options
.IP "--file=FILENAME, -f FILENAME"
File to attach, or filename for data provided on stdin
.IP "--description=DESCRIPTION, -d DESCRIPTION"
A short description of the file being attached
.IP "--type=MIMETYPE, -t MIMETYPE"
Mime-type for the file being attached
.IP "--get=ATTACHID, -g ATTACHID"
Download the attachment with the given ID
.IP "--getall=BUGID, --get-all=BUGID"
Download all attachments on the given bug
.IP "--comment=COMMENT, -l COMMENT"
Add comment with attachment


.SH \[oq]info\[cq] options
.IP "--products, -p"
Get a list of products
.IP "--components=PRODUCT, -c PRODUCT"
List the components in the given product
.IP "--component_owners=PRODUCT, -o PRODUCT"
List components (and their owners)
.IP "--versions=PRODUCT, -v PRODUCT"
List the versions for the given product
.IP "--active-components"
Only show active components. Combine with --components*


.SH AUTHENTICATION COOKIES AND TOKENS

Older bugzilla instances use cookie-based authentication, and
newer bugzilla instances (around 5.0) use a non-cookie token system.

When you log into bugzilla with the "login" subcommand or the "--login"
argument, we cache the login credentials in ~/.cache/python-bugzilla/
Previously we cached credentials in ~/.<filename>. If you want to see
which file the tool is using, check --debug output.

To perform an authenticated bugzilla command on a new machine, run a one time
"bugzilla login" to cache credentials before running the desired command. You
can also run "bugzilla --login" and the login process will be initiated before
invoking the command.

Additionally, the --no-cache-credentials option will tell the bugzilla tool to
_not_ save any credentials in $HOME, or use any previously cached credentials.

.SH EXAMPLES
.PP
.RS 0
bugzilla query --bug_id 62037

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

# All boolean options can be formatted like this
.br
bugzilla query --blocked "123456 | 224466"

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


.SH EXIT STATUS
.BR bugzilla
normally returns 0 if the requested command was successful.
Otherwise, exit status is 1 if
.BR 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 server returns
an XML-RPC fault.
.SH BUGS
Please report any bugs as github issues at
.br
https://github.com/python-bugzilla/python-bugzilla
.br
to the mailing list at
.br
https://fedorahosted.org/mailman/listinfo/python-bugzilla
.SH SEE ALSO
.nf
https://bugzilla.readthedocs.io/en/latest/api/index.html
https://bugzilla.redhat.com/docs/en/html/api/Bugzilla/WebService/Bug.html