include::include/header.adoc[]

== Name

bite - a command line tool for bug, issue, and ticket mangling

== Synopsis

*bite* [<options>] <subcommand> [<args>]::
    Run a subcommand.

*bite* [-h|--help|-V|--version]::
    Output help or version information.

== Description

Bite is a command line tool for interacting with bug, issue, and ticket
trackers. It aims to support common actions such as searching, requesting,
creating, and updating bugs, issues, or tickets in addition to other
functionality provided by a service.

include::include/global-options.adoc[]

== Options

*-V, --version*::
    Print version and exit.

== Environment variables

*BUGBITE_CONNECTION*::
    Define a service connection to use.

== Subcommands

linkcmd:bite-bugzilla[1]::
    bugzilla service support

linkcmd:bite-github[1]::
    github service support

linkcmd:bite-redmine[1]::
    redmine service support

linkcmd:bite-show[1]::
    show service information

== Configuration

Bite supports defining connections via TOML config files. Example files are
found at `services/*` in the repo which are bundled in the bite binary,
allowing for config-less, read-only service access. These configurations can be
overridden (e.g. adding user authentication information) by copying the related
config file to `$HOME/.config/bugbite/services/`. Note that the location
`$XDG_CONFIG_HOME/bugbite/services/` is also supported and will take
precendence if both `$XDG_CONFIG_HOME` and `$HOME` are defined.

In order to see all configured connections use `bite show connections` that
outputs a list of connection names or `bite show services` for additional
service-related info per connection.

In general, fields that are required for read-only access can be seen in the
valid example below with field descriptions in comments:

.Config example
....
# one of the service types supported by bugbite
type = "bugzilla"

# name of the connection
name = "gentoo"

# base URL of the service
base = "https://bugs.gentoo.org/"

# Additional, optional client-related parameters with defaults shown

# custom root certificate in PEM format
# default: unset
certificate = "path/to/cert.pem"

# concurrent requests limit
# default: unset
concurrent = 5

# allow connection to services with insecure certificates
# default: false
insecure = true

# request timeout in seconds (defaults to 30 if unset)
# default: 30
timeout = 10
....

Each service type may support other config fields which are listed in the
configuration section of the related service document along with a service
specific example detailing all fields.

== Resources

*Project web site:* https://github.com/radhermit/bugbite