### Install go-jira via Go

Source: https://context7.com/go-jira/jira/llms.txt

Installs the jira binary using the Go toolchain.

```bash
# Install via Go
go get github.com/go-jira/jira/cmd/jira
```

--------------------------------

### Install go-jira CLI

Source: https://github.com/go-jira/jira/blob/master/README.md

Build and install the go-jira command-line client from the official repository. Ensure GO111MODULE is set to 'on' before running.

```go
go get github.com/go-jira/jira/cmd/jira
```

--------------------------------

### Dynamic Configuration Script Example

Source: https://github.com/go-jira/jira/blob/master/README.md

An example of an executable configuration script that sets the Jira endpoint, preferred editor, and applies a 'table' template for 'list' operations. It also conditionally sets assignee and watchers for 'create' operations.

```sh
#!/bin/sh

echo "endpoint: https://jira.mycompany.com"
echo "editor: emacs -nw"

case $JIRA_OPERATION in
    list) 
      echo "template: table";;
esac

```

```sh
#!/bin/sh
echo "project: GOJIRA"

case $JIRA_OPERATION in
    create)
        echo "assignee: $USER"
        echo "watchers: mothra"
        ;;
esac

```

--------------------------------

### API Token Authentication Header Examples

Source: https://github.com/go-jira/jira/blob/master/README.md

Examples of Authorization headers for API token authentication, showing both Basic and Bearer schemes.

```text
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQK
```

```text
Authorization: Bearer MY_TOKEN
```

--------------------------------

### Setup Jira Service for Testing

Source: https://github.com/go-jira/jira/blob/master/_t/README.md

Script to set up the Jira service required for running tests. This needs to be run before executing other tests and may require daily execution due to a temporary license.

```bash
./000setup.t
```

--------------------------------

### Run Custom Command with Different Inputs

Source: https://github.com/go-jira/jira/blob/master/README.md

These examples demonstrate various ways to invoke the 'custom-test' command, highlighting error conditions for missing required arguments/options and successful executions with different argument and option values. It shows how repeated arguments are handled and how to override default option values.

```bash
$ jira custom-test
ERROR Invalid Usage: required flag --day not provided
```

```bash
$ jira custom-test --day Sunday
ERROR Invalid Usage: enum value must be one of Monday,Tuesday,Wednesday,Thursday,Friday, got 'Sunday'
```

```bash
$ jira custom-test --day Tuesday
ERROR Invalid Usage: required argument 'ARG' not provided
```

```bash
$ jira custom-test --day Tuesday arg1
COMMAND arg1 --abc default --day Tuesday
```

```bash
$ jira custom-test --day Tuesday arg1 more1 more2 more3
COMMAND arg1 --abc default --day Tuesday more1 more2 more3
```

```bash
$ jira custom-test --day Tuesday arg1 more1 more2 more3 --abc non-default
COMMAND arg1 --abc non-default --day Tuesday more1 more2 more3
```

```bash
$ jira custom-test --day Tuesday arg1 more1 more2 more3 -a short-non-default
COMMAND arg1 --abc short-non-default --day Tuesday more1 more2 more3
```

--------------------------------

### Configure gopass Password Source

Source: https://github.com/go-jira/jira/blob/master/README.md

Add this configuration to `$HOME/.jira.d/config.yml` to use `gopass` for password management. This requires a working `gopass` installation.

```yaml
password-source: gopass
password-name: jira.example.com/myuser
```

--------------------------------

### Execute Custom Jira Commands

Source: https://context7.com/go-jira/jira/llms.txt

Execute custom Jira commands defined in the configuration. These examples demonstrate calling the 'mine', 'bug', and 'sprint-report' commands with various options and arguments.

```bash
jira mine
jira bug --priority Critical --component "Payment Service" "Checkout crashes on empty cart"
jira sprint-report --count 5
```

--------------------------------

### AddIssueWorklog

Source: https://context7.com/go-jira/jira/llms.txt

Posts a worklog entry, including time spent, an optional comment, and the start time, to a specific issue.

```APIDOC
## `AddIssueWorklog` — Log time spent on an issue

Posts a worklog entry (time spent + optional comment + start time) to an issue.

### Parameters

- `httpClient` (*http.Client) - The HTTP client to use for the request.
- `endpoint` (string) - The Jira API endpoint URL.
- `issueKey` (string) - The key of the issue to log work against (e.g., "PROJ-789").
- `worklog` (*jiradata.Worklog) - A `Worklog` object containing details like `TimeSpent`, `Comment`, and `Started`.

### Request Example

```go
import "github.com/go-jira/jira/jiradata"

worklog := &jiradata.Worklog{
    TimeSpent: "2h 30m",
    Comment:   "Investigated null pointer and identified root cause",
    Started:   "2024-03-15T09:00:00.000+0000",
}

posted, err := jira.AddIssueWorklog(httpClient, endpoint, "PROJ-789", worklog)
if err != nil {
    log.Fatalf("AddWorklog: %v", err)
}
fmt.Printf("Logged %s by %s\n", posted.TimeSpent, posted.Author.DisplayName)
// Output: Logged 2h 30m by Jane Smith
```

### Response

- `*jiradata.Worklog` - The posted worklog details upon success.
```

--------------------------------

### Access Jira Environment Variables in Custom Command

Source: https://github.com/go-jira/jira/blob/master/README.md

This example shows how a custom command can directly access environment variables set by Jira, such as `JIRA_PROJECT`. The script simply echoes the value of the `JIRA_PROJECT` environment variable.

```yaml
custom-commands:
  - name: print-project
    help: print the name of the configured project
    script: "echo $JIRA_PROJECT"
```

--------------------------------

### Log Work on Jira Issue

Source: https://context7.com/go-jira/jira/llms.txt

Posts a worklog entry to a Jira issue, including time spent, an optional comment, and the start time of the work. Requires a populated jiradata.Worklog struct.

```go
import "github.com/go-jira/jira/jiradata"

worklog := &jiradata.Worklog{
    TimeSpent: "2h 30m",
    Comment:   "Investigated null pointer and identified root cause",
    Started:   "2024-03-15T09:00:00.000+0000",
}

posted, err := jira.AddIssueWorklog(httpClient, endpoint, "PROJ-789", worklog)
if err != nil {
    log.Fatalf("AddWorklog: %v", err)
}
fmt.Printf("Logged %s by %s\n", posted.TimeSpent, posted.Author.DisplayName)
// Output: Logged 2h 30m by Jane Smith
```

--------------------------------

### Initialize pass Tool

Source: https://github.com/go-jira/jira/blob/master/README.md

Initialize the `pass` tool with your GPG key. Replace "Go Jira <gojira@example.com>" with your actual GPG key details.

```bash
pass init "Go Jira <gojira@example.com>"
```

--------------------------------

### Create and List Project Components

Source: https://context7.com/go-jira/jira/llms.txt

Manages project components. `CreateComponent` adds a new component, while `GetProjectComponents` lists existing ones. Requires the `jiradata` package.

```go
import "github.com/go-jira/jira/jiradata"

// Create a component
comp := &jiradata.Component{
    Name:        "Payment Service",
    Description: "Handles all payment processing logic",
    Project:     "PROJ",
    LeadUserName: "jsmith",
}
created, err := jira.CreateComponent(httpClient, endpoint, comp)
if err != nil {
    log.Fatalf("CreateComponent: %v", err)
}
fmt.Printf("Created component %d: %s\n", created.ID, created.Name)
```

```go
// List project components
components, err := jira.GetProjectComponents(httpClient, endpoint, "PROJ")
if err != nil {
    log.Fatal(err)
}
for _, c := range *components {
    fmt.Printf("  %s (id=%d)\n", c.Name, c.ID)
}
```

--------------------------------

### Build and Run Integration Tests

Source: https://github.com/go-jira/jira/blob/master/_t/README.md

Commands to build the local 'jira' binary and run integration tests using the 'prove' command.

```bash
# this creates a local "jira" binary
make

# this runs the integration tests in the "_t" directory
prove
```

--------------------------------

### Configure go-jira with API Token Authentication

Source: https://github.com/go-jira/jira/blob/master/README.md

Sets up go-jira to use an API token for authentication with Atlassian Cloud. Requires setting subdomain and email, creating a config file, and then running 'jira session' to add the token to the keyring.

```bash
export SUBDOMAIN="https://<SUBDOMAIN>.atlassian.net"
export EMAIL="<EMAIL>"
mkdir -p ~/.jira.d
printf "endpoint: $SUBDOMAIN\nuser: $EMAIL\npassword-source: keyring" > ~/.jira.d/config.yml
```

--------------------------------

### Jira CLI Raw API Request

Source: https://context7.com/go-jira/jira/llms.txt

Make direct REST API requests to Jira. Supports GET, POST, PUT, and DELETE methods with optional JSON payloads.

```bash
jira req /rest/api/2/project/PROJ
```

```bash
jira req --method POST /rest/api/2/issue '{"fields":{"project":{"key":"PROJ"},"summary":"test","issuetype":{"name":"Task"}}}'
```

--------------------------------

### Run Individual Test with Options

Source: https://github.com/go-jira/jira/blob/master/_t/README.md

How to execute a specific test file directly. Use the -v option for verbose output and -a to abort on the first failure.

```bash
./100basic.t
```

--------------------------------

### Configure Jira Endpoint

Source: https://github.com/go-jira/jira/blob/master/README.md

Set up the Jira endpoint by creating a .jira.d/config.yml file in your home directory. This file specifies the base URL for your Jira instance.

```yaml
endpoint: https://jira.mycompany.com
```

--------------------------------

### Configure Atlassian Cloud Authentication

Source: https://context7.com/go-jira/jira/llms.txt

Sets up the configuration file for Atlassian Cloud using API token authentication. Prompts for the API token and stores it in the OS keyring.

```bash
# Atlassian Cloud (API token auth)
mkdir -p ~/.jira.d
cat > ~/.jira.d/config.yml <<EOF
endpoint: https://mycompany.atlassian.net
user: jane@example.com
login: jane@example.com
password-source: keyring
EOF
jira session   # prompts for API token, stores in OS keyring
```

--------------------------------

### Configure Bearer-Token Authentication for Jira

Source: https://context7.com/go-jira/jira/llms.txt

Sets up the configuration file for private Jira servers using bearer-token authentication. Requires user, login, and password source.

```bash
# Bearer-token auth (some private servers)
cat > ~/.jira.d/config.yml <<EOF
endpoint: https://jira.corp.com
user: jsmith
login: jsmith@corp.com
authentication-method: bearer-token
password-source: keyring
EOF
```

--------------------------------

### List GPG Keys

Source: https://github.com/go-jira/jira/blob/master/README.md

List your existing GPG keys to find the Key ID needed for initializing `pass`. The output shows the public key and associated user information.

```bash
gpg --list-keys
```

--------------------------------

### Configure Self-hosted Jira Session Authentication

Source: https://context7.com/go-jira/jira/llms.txt

Sets up the configuration file for a self-hosted Jira instance using session authentication. Requires a password source and name.

```bash
# Self-hosted Jira (session auth)
cat > ~/.jira.d/config.yml <<EOF
endpoint: https://jira.internal.example.com
user: jsmith
authentication-method: session
password-source: pass
password-name: jira.internal.example.com/jsmith
EOF
jira login
```

--------------------------------

### GetFields

Source: https://context7.com/go-jira/jira/llms.txt

Lists all system and custom fields available on the Jira instance.

```APIDOC
## GetFields — List all Jira fields

Returns all system and custom fields available on the Jira instance, useful for discovering custom field IDs.

### List fields
```go
fields, err := jira.GetFields(httpClient, endpoint)
if err != nil {
    log.Fatal(err)
}
for _, f := range fields {
    if f.Custom {
        fmt.Printf("Custom field: id=%s name=%s type=%s\n", f.ID, f.Name, f.Schema.Type)
    }
}
```
```

--------------------------------

### Search Jira Issues with Auto-Pagination

Source: https://context7.com/go-jira/jira/llms.txt

Perform JQL searches using `Search` and `SearchOptions`. `WithAutoPagination()` fetches all pages up to a limit. The `QueryFields` parameter specifies which fields to retrieve.

```go
import (
    jira "github.com/go-jira/jira"
)

// High-level SearchOptions builds a JQL query from structured fields
opts := &jira.SearchOptions{
    Project:     "PROJ",
    Assignee:    "jane@example.com",
    Status:      "In Progress",
    IssueType:   "Bug",
    Sort:        "priority asc, created",
    MaxResults:  50,
    QueryFields: "summary,status,assignee,priority,created",
}

results, err := jira.Search(httpClient, endpoint, opts, jira.WithAutoPagination())
if err != nil {
    log.Fatal(err)
}
fmt.Printf("Found %d issues (total: %d)\n", len(results.Issues), results.Total)
for _, issue := range results.Issues {
    fmt.Printf("  %s: %v\n", issue.Key, issue.Fields["summary"])
}

// Raw JQL query
rawOpts := &jira.SearchOptions{
    Query:       `project = PROJ AND sprint in openSprints() AND "Story Points" >= 5 ORDER BY rank`,
    MaxResults:  200,
    QueryFields: "summary,status,assignee,customfield_10016",
}
results, err = jira.Search(httpClient, endpoint, rawOpts, jira.WithAutoPagination())
```

--------------------------------

### Create Jira API Client with NewJira

Source: https://context7.com/go-jira/jira/llms.txt

Constructs a *Jira struct to interact with the Jira API. This client can be used for all API methods.

```go
package main

import (
    "fmt"
    "log"
    jira "github.com/go-jira/jira"
)

func main() {
    // NewJira creates a client using the oreo HTTP client with cookie jar support
    client := jira.NewJira("https://mycompany.atlassian.net")

    // All API methods available on the struct or as package-level functions
    issue, err := client.GetIssue("PROJ-123", nil)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("Summary: %v\n", issue.Fields["summary"])
    // Output: Summary: Fix login page redirect
}
```

--------------------------------

### List All Jira Fields

Source: https://context7.com/go-jira/jira/llms.txt

Retrieves a list of all system and custom fields available on the Jira instance. Useful for discovering custom field IDs.

```go
fields, err := jira.GetFields(httpClient, endpoint)
if err != nil {
    log.Fatal(err)
}
for _, f := range fields {
    if f.Custom {
        fmt.Printf("Custom field: id=%s name=%s type=%s\n", f.ID, f.Name, f.Schema.Type)
    }
}
// Output:
// Custom field: id=customfield_10016 name=Story Points type=number
// Custom field: id=customfield_10110 name=Epic Link type=any
```

--------------------------------

### Configure Keyring Password Source

Source: https://github.com/go-jira/jira/blob/master/README.md

Enable 'password-source: keyring' in your config.yml to automatically store your credentials in your OS's native keyring after a 'jira login' command.

```yaml
password-source: keyring
```

--------------------------------

### Component Management

Source: https://context7.com/go-jira/jira/llms.txt

Functions for creating new components in a project and listing existing components.

```APIDOC
## CreateComponent / GetProjectComponents — Project component management

Creates a new component in a project or lists existing components.

### Create a component
```go
comp := &jiradata.Component{
    Name:        "Payment Service",
    Description: "Handles all payment processing logic",
    Project:     "PROJ",
    LeadUserName: "jsmith",
}
created, err := jira.CreateComponent(httpClient, endpoint, comp)
if err != nil {
    log.Fatalf("CreateComponent: %v", err)
}
fmt.Printf("Created component %d: %s\n", created.ID, created.Name)
```

### List project components
```go
components, err := jira.GetProjectComponents(httpClient, endpoint, "PROJ")
if err != nil {
    log.Fatal(err)
}
for _, c := range *components {
    fmt.Printf("  %s (id=%d)\n", c.Name, c.ID)
}
```
```

--------------------------------

### Generate GPG Key

Source: https://github.com/go-jira/jira/blob/master/README.md

Use this command to generate a new GPG key if you don't have one already. This is a prerequisite for using `pass` or `gopass`.

```bash
gpg --gen-key
```

--------------------------------

### Configure gpg-agent for Passphrase Caching

Source: https://github.com/go-jira/jira/blob/master/README.md

Add this configuration to your `$HOME/.bashrc` to set up `gpg-agent` for automatic passphrase caching. This avoids repeated prompts for GPG decryption.

```bash
if [ -f $HOME/.gpg-agent-info ]; then
    . $HOME/.gpg-agent-info
    export GPG_AGENT_INFO
fi

if [ ! -f $HOME/.gpg-agent.conf ]; then
  cat <<EOM >$HOME/.gpg-agent.conf
default-cache-ttl 604800
max-cache-ttl 604800
default-cache-ttl-ssh 604800
max-cache-ttl-ssh 604800
EOM
fi

if [ -n "${GPG_AGENT_INFO}" ]; then
    nc  -U "${GPG_AGENT_INFO%%:*}" >/dev/null </dev/null
    if [ ! -S "${GPG_AGENT_INFO%%:*}" -o $? != 0 ]; then
        # set passphrase cache so I only have to type my passphrase once a day
        eval $(gpg-agent --options $HOME/.gpg-agent.conf --daemon --write-env-file $HOME/.gpg-agent-info --use-standard-socket --log-file $HOME/tmp/gpg-agent.log --verbose)
    fi
fi
export GPG_TTY=$(tty)
```

--------------------------------

### Insert Password with pass

Source: https://github.com/go-jira/jira/blob/master/README.md

Insert your password into the `pass` store using the configured name. This command encrypts and stores the password.

```bash
pass insert jira.example.com/myuser
```

--------------------------------

### Export and Customize Jira Templates

Source: https://context7.com/go-jira/jira/llms.txt

Export built-in Jira templates for customization. Templates use Go's text/template with helper functions. Edit exported templates to change output formatting.

```bash
# Export all built-in templates
jira export-templates

# Export a single template
jira export-templates --template view
```

```go-template
issue: {{ .Key | bold }}
{{- range $k, $v := .Fields }}
{{ $k }}: {{ $v }}
{{- end }}
```

```bash
# Use a custom template inline
jira list --template table
jira view PROJ-789 --template debug    # dumps raw JSON data model
jira list --gjq "issues.#.key"         # GJSON filter on JSON output
```

```json
# Output: ["PROJ-789","PROJ-790","PROJ-791"]
```

--------------------------------

### Jira CLI - View and List Issues

Source: https://context7.com/go-jira/jira/llms.txt

Command-line interface for viewing and listing Jira issues. Supports various filters and output formats.

```bash
# View a single issue (jira PROJ-123 also works as shorthand)
jira view PROJ-789
jira view PROJ-789 --template json
jira view PROJ-789 --gjq "fields.status.name"
# Output: In Progress
```

```bash
# List issues with JQL
jira list --query "project = PROJ AND sprint in openSprints() AND assignee = currentUser()"
jira list --project PROJ --status "In Progress" --assignee jane@example.com
jira list --project PROJ --limit 20 --sort "priority asc"
```

--------------------------------

### Jira CLI Commands for Voting and Watching Issues

Source: https://context7.com/go-jira/jira/llms.txt

Manage user participation in Jira issues. Vote for or against an issue, or start/stop watching an issue.

```bash
jira vote PROJ-789
```

```bash
jira vote --down PROJ-789
```

```bash
jira watch PROJ-789
```

```bash
jira watch --remove PROJ-789
```

--------------------------------

### NewJira - Create a Jira API client

Source: https://context7.com/go-jira/jira/llms.txt

Constructs a *Jira struct wrapping an HTTP client and endpoint. All Go library functions are available as methods or standalone functions accepting an HttpClient and endpoint string.

```APIDOC
## NewJira

### Description
Constructs a `*Jira` struct wrapping an HTTP client and endpoint. All Go library functions are available as methods or standalone functions accepting an `HttpClient` and endpoint string.

### Method Signature
`func NewJira(endpoint string) *Jira`

### Parameters
*   **endpoint** (string) - The base URL of the Jira instance.

### Request Example
```go
package main

import (
    "fmt"
    "log"
    jira "github.com/go-jira/jira"
)

func main() {
    // NewJira creates a client using the oreo HTTP client with cookie jar support
    client := jira.NewJira("https://mycompany.atlassian.net")

    // All API methods available on the struct or as package-level functions
    issue, err := client.GetIssue("PROJ-123", nil)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("Summary: %v\n", issue.Fields["summary"])
    // Output: Summary: Fix login page redirect
}
```
```

--------------------------------

### Define Custom Command with Arguments and Options

Source: https://github.com/go-jira/jira/blob/master/README.md

This YAML defines a 'custom-test' command with required arguments and options. It shows how to specify argument types, enums, repetition, and how options can have short aliases and default values. The script template uses `args` and `options` to construct a shell command.

```yaml
custom-commands:
  - name: custom-test
    help: Testing the custom commands
    options:
      - name: abc
        short: a
        default: default
      - name: day
        type: ENUM
        enum:
          - Monday
          - Tuesday
          - Wednesday
          - Thursday
          - Friday
        required: true
    args:
      - name: ARG
        required: true
      - name: MORE
        repeat: true
    script: | 
      echo COMMAND {{args.ARG}} --abc {{options.abc}} --day {{options.day}} {{range $more := args.MORE}}{{$more}} {{end}}
```

--------------------------------

### Jira CLI - Create Issue

Source: https://context7.com/go-jira/jira/llms.txt

Creates Jira issues via the CLI. Opens an editor with a YAML template by default. Use `--noedit` and `--override` to skip the editor and provide fields directly.

```bash
# Create an issue (opens editor with YAML template)
jira create --project PROJ --issuetype Bug --summary "Login fails on Safari"
```

```bash
# Skip editor with --noedit and --override
jira create --project PROJ -i Bug -s "Login fails" --noedit \
  -o priority=High -o assignee=jane@example.com
```

--------------------------------

### Enable Bash Shell Completion

Source: https://github.com/go-jira/jira/blob/master/README.md

Add this command to your bashrc or .profile to enable tab completion for go-jira commands, assuming the binary is in your PATH.

```bash
eval "$(jira --completion-script-bash)"
```

--------------------------------

### Specify Custom Password Source Path

Source: https://github.com/go-jira/jira/blob/master/README.md

Configure `password-source-path` in `$HOME/.jira.d/config.yml` to use a specific binary for `gopass` or `pass` interactions. If omitted, `gopass` or `pass` will be used by default.

```yaml
password-source: gopass
password-name: jira.example.com/myuser
password-source-path: /path/to/my-special-gopass
```

--------------------------------

### Jira CLI Commands for Blocking and Linking Issues

Source: https://context7.com/go-jira/jira/llms.txt

Establish relationships between Jira issues using these commands. Define blocking relationships or mark issues as duplicates.

```bash
jira block PROJ-789 PROJ-100   # PROJ-789 is blocked by PROJ-100
```

```bash
jira dup PROJ-789 PROJ-788     # PROJ-789 duplicates PROJ-788
```

--------------------------------

### Debug Template Data for 'view' Operation

Source: https://github.com/go-jira/jira/blob/master/README.md

Use the '-t debug' flag with the 'view' command to print available data in JSON format for template customization.

```bash
jira view GOJIRA-321 -t debug
```

--------------------------------

### Configure pass Password Source

Source: https://github.com/go-jira/jira/blob/master/README.md

Add this configuration to `$HOME/.jira.d/config.yml` to use the `pass` tool for password management. Ensure `pass` is set up correctly on your system.

```yaml
password-source: pass
password-name: jira.example.com/myuser
```

--------------------------------

### Jira CLI Commands for Attachments

Source: https://context7.com/go-jira/jira/llms.txt

Use these commands to manage attachments for Jira issues. Supports creating attachments from files or standard input, and listing existing attachments.

```bash
jira attach create PROJ-789 /path/to/screenshot.png
```

```bash
jira attach list PROJ-789
```

```bash
cat /var/log/app.log | jira attach create PROJ-789 --filename app.log
```

--------------------------------

### Interactive and File-Based YAML Issue Editing

Source: https://context7.com/go-jira/jira/llms.txt

Use EditLoop for interactive YAML editing of Jira issues, allowing retries on error. ReadYmlInputFile provides non-interactive editing from a specified file path.

```go
import (
    "github.com/go-jira/jira/jiracli"
    "github.com/go-jira/jira/jiradata"
)

common := &jiracli.CommonOptions{
    Template: figtree.NewStringOption("create"),
}

input := struct {
    Meta      *jiradata.IssueType `yaml:"meta"`
    Overrides map[string]string   `yaml:"overrides"`
}{
    Meta:      createMeta,
    Overrides: map[string]string{"project": "PROJ", "issuetype": "Bug"},
}

issueUpdate := jiradata.IssueUpdate{}
er...
```

--------------------------------

### Jira CLI - Edit and Transition Issues

Source: https://context7.com/go-jira/jira/llms.txt

Edits existing issues and transitions them through their workflow states. Use `--override` for non-interactive edits.

```bash
# Edit an issue
jira edit PROJ-789
jira edit PROJ-789 --override priority=Critical --noedit
```

```bash
# Transition an issue
jira transition "In Progress" PROJ-789
jira transition Done PROJ-789 --comment "Deployed to prod in v2.4.0"
# Shorthand commands
jira close PROJ-789
jira resolve PROJ-789
jira reopen PROJ-789
```

--------------------------------

### Attach File to Jira Issue

Source: https://context7.com/go-jira/jira/llms.txt

Attaches a local file or piped content from stdin to a specified Jira issue. Requires the file to be opened and passed as an io.Reader.

```go
import "os"

// Attach a local file
f, err := os.Open("/tmp/heapdump.hprof")
if err != nil {
    log.Fatal(err)
}
deferr f.Close()

attachments, err := jira.IssueAttachFile(httpClient, endpoint, "PROJ-789", "heapdump.hprof", f)
if err != nil {
    log.Fatalf("IssueAttachFile: %v", err)
}
for _, a := range *attachments {
    fmt.Printf("Attached: id=%d filename=%s url=%s\n", a.ID, a.Filename, a.Content)
}

// Attach from stdin (piped content)
// echo "log data" | jira attach create PROJ-789 --filename debug.log
```

--------------------------------

### Register Custom Jira CLI Command

Source: https://context7.com/go-jira/jira/llms.txt

Extend the Jira CLI by programmatically registering custom commands. This Go code defines a new command 'my-report' with its own flags and execution logic.

```go
package main

import (
    "fmt"
    "github.com/coryb/figtree"
    "github.com/coryb...
```

--------------------------------

### Jira CLI Commands for Epic Management

Source: https://context7.com/go-jira/jira/llms.txt

Manage Jira epics using these CLI commands. Includes creating new epics, listing epics associated with a project, and adding or removing issues from an epic.

```bash
jira epic create --project PROJ --epic-name "Q1 Auth Improvements"
```

```bash
jira epic list PROJ-50
```

```bash
jira epic add PROJ-50 PROJ-789 PROJ-790
```

```bash
jira epic remove PROJ-789
```

--------------------------------

### Search / SearchOptions

Source: https://context7.com/go-jira/jira/llms.txt

Executes a JQL search against `rest/api/3/search/jql`. `WithAutoPagination()` transparently fetches all pages up to a configured limit. Supports both structured fields and raw JQL queries.

```APIDOC
## `Search` / `SearchOptions` — JQL issue search with auto-pagination

Executes a JQL search against `rest/api/3/search/jql`. `WithAutoPagination()` transparently fetches all pages up to a configured limit.

```go
import (
    jira "github.com/go-jira/jira"
)

// High-level SearchOptions builds a JQL query from structured fields
opts := &jira.SearchOptions{
    Project:     "PROJ",
    Assignee:    "jane@example.com",
    Status:      "In Progress",
    IssueType:   "Bug",
    Sort:        "priority asc, created",
    MaxResults:  50,
    QueryFields: "summary,status,assignee,priority,created",
}

results, err := jira.Search(httpClient, endpoint, opts, jira.WithAutoPagination())
if err != nil {
    log.Fatal(err)
}
fmt.Printf("Found %d issues (total: %d)\n", len(results.Issues), results.Total)
for _, issue := range results.Issues {
    fmt.Printf("  %s: %v\n", issue.Key, issue.Fields["summary"])
}

// Raw JQL query
rawOpts := &jira.SearchOptions{
    Query:       `project = PROJ AND sprint in openSprints() AND "Story Points" >= 5 ORDER BY rank`,
    MaxResults:  200,
    QueryFields: "summary,status,assignee,customfield_10016",
}
results, err = jira.Search(httpClient, endpoint, rawOpts, jira.WithAutoPagination())
```
```

--------------------------------

### Fetch Jira Issue Worklogs and Comments

Source: https://context7.com/go-jira/jira/llms.txt

Fetches all worklogs or comments for a given Jira issue. The function handles pagination automatically, retrieving up to 100 items per page.

```go
// Fetch all worklogs
worklogs, err := jira.GetIssueWorklog(httpClient, endpoint, "PROJ-789")
if err != nil {
    log.Fatal(err)
}
total := 0
for _, w := range *worklogs {
    fmt.Printf("  %s spent %s: %s\n", w.Author.DisplayName, w.TimeSpent, w.Comment)
    total++
}
fmt.Printf("Total worklog entries: %d\n", total)

// Fetch all comments
comments, err := jira.GetIssueComment(httpClient, endpoint, "PROJ-789")
if err != nil {
    log.Fatal(err)
}
for _, c := range *comments {
    fmt.Printf("  [%s] %s: %.80s\n", c.Created, c.Author.DisplayName, c.Body)
}
```

--------------------------------

### Jira CLI - Worklog

Source: https://context7.com/go-jira/jira/llms.txt

Adds worklog entries to issues. Specify time spent and an optional comment. Use `--noedit` to bypass the editor.

```bash
# Worklog
jira worklog add PROJ-789 --time-spent "3h" --comment "Fixed the bug" --noedit
```

--------------------------------

### Debug Template Data for 'list' Operation

Source: https://github.com/go-jira/jira/blob/master/README.md

Use the '-t debug' flag with the 'list' command to print available data in JSON format for template customization.

```bash
jira list -t debug
```

--------------------------------

### Fetch Jira Issue with Options

Source: https://context7.com/go-jira/jira/llms.txt

Retrieves a Jira issue using specific fields, expand options, and update history. Handles potential errors by implementing jiradata.ErrorCollection.

```go
import (
    jira "github.com/go-jira/jira"
)

// Fetch with field and expand options
opts := &jira.IssueOptions{
    Fields:        []string{"summary", "status", "assignee", "description"},
    Expand:        []string{"renderedFields"},
    UpdateHistory: true,
}
issue, err := jira.GetIssue(httpClient, "https://mycompany.atlassian.net", "PROJ-456", opts)
if err != nil {
    // err implements jiradata.ErrorCollection with Status and ErrorMessages
    log.Fatalf("GetIssue failed: %v", err)
}
fmt.Println(issue.Key, issue.Fields["summary"])
```

--------------------------------

### TransitionIssue / GetIssueTransitions

Source: https://context7.com/go-jira/jira/llms.txt

Fetches available workflow transitions for an issue and allows transitioning it to a new state. Transition IDs can be resolved by name within the metadata.

```APIDOC
## `TransitionIssue` / `GetIssueTransitions` — Workflow state transitions

Fetches available transitions and moves an issue to a new state. Transition IDs are resolved by name within the metadata.

```go
// List available transitions
meta, err := jira.GetIssueTransitions(httpClient, endpoint, "PROJ-789")
if err != nil {
    log.Fatal(err)
}
for _, t := range meta.Transitions {
    fmt.Printf("  [%s] %s\n", t.ID, t.Name)
}
// Output:
//   [11] To Do
//   [21] In Progress
//   [31] Done

// Transition to Done with a resolution
issueUpdate := &jiradata.IssueUpdate{
    Transition: &jiradata.TransitionPayload{ID: "31"},
    Fields: map[string]interface{}{
        "resolution": map[string]string{"name": "Fixed"},
    },
    Update: map[string]interface{}{
        "comment": []map[string]interface{}{
            {"add": map[string]string{"body": "Resolved in PR #142"}},
        },
    },
}
err = jira.TransitionIssue(httpClient, endpoint, "PROJ-789", issueUpdate)
if err != nil {
    log.Fatalf("TransitionIssue: %v", err)
}
// HTTP 204 on success
```
```

--------------------------------

### Transition Jira Issue Workflow State

Source: https://context7.com/go-jira/jira/llms.txt

Use `GetIssueTransitions` to list available workflow transitions for an issue and `TransitionIssue` to move it to a new state. Transition IDs can be resolved by name. A resolution and comment can be included in the transition payload.

```go
// List available transitions
meta, err := jira.GetIssueTransitions(httpClient, endpoint, "PROJ-789")
if err != nil {
    log.Fatal(err)
}
for _, t := range meta.Transitions {
    fmt.Printf("  [%s] %s\n", t.ID, t.Name)
}
// Output:
//   [11] To Do
//   [21] In Progress
//   [31] Done

// Transition to Done with a resolution
issueUpdate := &jiradata.IssueUpdate{
    Transition: &jiradata.TransitionPayload{ID: "31"},
    Fields: map[string]interface{}{
        "resolution": map[string]string{"name": "Fixed"},
    },
    Update: map[string]interface{}{
        "comment": []map[string]interface{}{{"add": map[string]string{"body": "Resolved in PR #142"}}},
    },
}
err = jira.TransitionIssue(httpClient, endpoint, "PROJ-789", issueUpdate)
if err != nil {
    log.Fatalf("TransitionIssue: %v", err)
}
// HTTP 204 on success
```

--------------------------------

### Define Custom Commands in Configuration

Source: https://github.com/go-jira/jira/blob/master/README.md

Specify custom commands by listing their names in the 'custom-commands' section of your .jira.d/config.yml file. These commands are typically shell scripts.

```yaml
custom-commands:
  - command1
  - command2
```

--------------------------------

### Configure User and Login for API Tokens

Source: https://github.com/go-jira/jira/blob/master/README.md

When using API tokens, specify both 'user' for Jira API calls and 'login' for authentication purposes in your config.yml. This is useful when your login email differs from your Jira username.

```yaml
user: person
login: person@example.com
```

--------------------------------

### Jira CLI Commands

Source: https://context7.com/go-jira/jira/llms.txt

Command-line interface for various Jira operations including viewing, listing, creating, editing, and transitioning issues.

```APIDOC
## `jira` CLI — view, list, create, edit, transition commands

The binary provides subcommands for every operation. All commands load config from `.jira.d/config.yml` hierarchy and support `--template`, `--gjq` (GJSON filter), and `--browse` flags.

### View an issue
```bash
# View a single issue (jira PROJ-123 also works as shorthand)
jira view PROJ-789
jira view PROJ-789 --template json
jira view PROJ-789 --gjq "fields.status.name"
# Output: In Progress
```

### List issues
```bash
# List issues with JQL
jira list --query "project = PROJ AND sprint in openSprints() AND assignee = currentUser()"
jira list --project PROJ --status "In Progress" --assignee jane@example.com
jira list --project PROJ --limit 20 --sort "priority asc"
```

### Create an issue
```bash
# Create an issue (opens editor with YAML template)
jira create --project PROJ --issuetype Bug --summary "Login fails on Safari"
# Skip editor with --noedit and --override
jira create --project PROJ -i Bug -s "Login fails" --noedit \
  -o priority=High -o assignee=jane@example.com
```

### Edit an issue
```bash
jira edit PROJ-789
jira edit PROJ-789 --override priority=Critical --noedit
```

### Transition an issue
```bash
jira transition "In Progress" PROJ-789
jira transition Done PROJ-789 --comment "Deployed to prod in v2.4.0"
# Shorthand commands
jira close PROJ-789
jira resolve PROJ-789
jira reopen PROJ-789
```

### Add a comment
```bash
jira comment PROJ-789 --comment "Confirmed fix works in staging"
jira comment PROJ-789   # opens editor
```

### Assign / unassign
```bash
jira assign PROJ-789 jane@example.com
jira unassign PROJ-789
```

### Worklog
```bash
jira worklog add PROJ-789 --time-spent "3h" --comment "Fixed the bug" --noedit
```
```

--------------------------------

### Jira CLI - Add Comment, Assign, and Unassign

Source: https://context7.com/go-jira/jira/llms.txt

Commands for adding comments to issues and managing issue assignments.

```bash
# Add a comment
jira comment PROJ-789 --comment "Confirmed fix works in staging"
jira comment PROJ-789   # opens editor
```

```bash
# Assign / unassign
jira assign PROJ-789 jane@example.com
jira unassign PROJ-789
```

--------------------------------

### Create Jira Issue

Source: https://context7.com/go-jira/jira/llms.txt

Use `CreateIssue` to create a new Jira issue. The `IssueUpdateProvider` interface allows decoupling the data source from the HTTP call. Ensure `httpClient` and `issueUpdate` are properly initialized.

```go
import (
    "github.com/go-jira/jira/jiradata"
    jira "github.com/go-jira/jira"
)

issueUpdate := &jiradata.IssueUpdate{
    Fields: map[string]interface{}{
        "project":   map[string]string{"key": "PROJ"},
        "issuetype": map[string]string{"name": "Bug"},
        "summary":   "Null pointer exception in payment service",
        "priority":  map[string]string{"name": "High"},
        "description": "Steps to reproduce:\n1. Go to /checkout\n2. Submit with empty cart",
    },
}

resp, err := jira.CreateIssue(httpClient, "https://mycompany.atlassian.net", issueUpdate)
if err != nil {
    log.Fatalf("CreateIssue: %v", err)
}
fmt.Printf("Created %s: %s/browse/%s\n", resp.Key, endpoint, resp.Key)
// Output: Created PROJ-789: https://mycompany.atlassian.net/browse/PROJ-789
```

--------------------------------

### Assign Jira Issue

Source: https://context7.com/go-jira/jira/llms.txt

Assigns an issue to a user. For server deployments, use username; for cloud, use accountId. Pass an empty string to unassign.

```go
// Server deployment: assign by username
err := jira.IssueAssign(httpClient, endpoint, "PROJ-789", "jsmith")
if err != nil {
    log.Fatal(err)
}

// Cloud deployment: assign by accountId (GDPR-compliant)
err = jira.IssueAssignAccountID(httpClient, endpoint, "PROJ-789", "5b10ac8d82e05b22cc7d4ef5")
if err != nil {
    log.Fatal(err)
}

// Unassign
err = jira.IssueAssign(httpClient, endpoint, "PROJ-789", "")
if err != nil {
    log.Fatal(err)
}
```

--------------------------------

### Define Custom Command to Print Environment Variables

Source: https://github.com/go-jira/jira/blob/master/README.md

This YAML defines an 'env' command that prints all environment variables prefixed with 'JIRA'. This is useful for debugging and understanding the environment variables available to custom commands.

```yaml
custom-commands:
  - name: env
    help: print the JIRA environment variables available to custom commands
    script: |
      env | grep JIRA
```

--------------------------------

### Define Custom Jira Commands in YAML

Source: https://context7.com/go-jira/jira/llms.txt

Define custom commands for Jira workflows using YAML configuration. These commands can be extended with options and arguments, and their scripts can leverage Jira's CLI and Go templating.

```yaml
custom-commands:
  - name: mine
    help: List issues assigned to me in the current sprint
    script: |
      {{jira}} list --template table \
        --query "sprint in openSprints() AND assignee = currentUser() AND resolution = unresolved ORDER BY priority asc"

  - name: bug
    help: Create a bug with mandatory priority
    options:
      - name: priority
        short: P
        type: ENUM
        enum: [Blocker, Critical, Major, Minor]
        required: true
      - name: component
        short: c
    args:
      - name: SUMMARY
        required: true
    script: |
      {{jira}} create --project $JIRA_PROJECT -i Bug -s "{{args.SUMMARY}}" --noedit \
        -o priority={{options.priority}} \
        {{if options.component}}-o component={{options.component}}{{end}}

  - name: sprint-report
    help: Show sprint velocity for the last N sprints
    options:
      - name: count
        short: n
        default: "3"
    script: |
      {{jira}} list --template table \
        --query "project = $JIRA_PROJECT AND sprint in closedSprints() ORDER BY updated desc" \
        --limit {{options.count}}
```

--------------------------------

### Search, Add, and Remove Issues from Epics

Source: https://context7.com/go-jira/jira/llms.txt

Use these functions to manage issues within epics. Ensure the `httpClient` and `endpoint` are properly configured. `EpicRemoveIssues` moves issues to the backlog.

```go
import "github.com/go-jira/jira/jiradata"

// Search issues in an epic
searchOpts := &jira.SearchOptions{
    Status:      "In Progress",
    QueryFields: "summary,assignee,status",
}
results, err := jira.EpicSearch(httpClient, endpoint, "PROJ-50", searchOpts)
if err != nil {
    log.Fatal(err)
}
fmt.Printf("Epic PROJ-50 has %d in-progress issues\n", len(results.Issues))
```

```go
// Add issues to an epic
epicIssues := &jiradata.EpicIssues{
    Issues: []string{"PROJ-789", "PROJ-790", "PROJ-791"},
}
err = jira.EpicAddIssues(httpClient, endpoint, "PROJ-50", epicIssues)
if err != nil {
    log.Fatalf("EpicAddIssues: %v", err)
}
```

```go
// Remove issues from their epic (moves to backlog)
err = jira.EpicRemoveIssues(httpClient, endpoint, epicIssues)
if err != nil {
    log.Fatalf("EpicRemoveIssues: %v", err)
}
```

--------------------------------

### IssueAttachFile

Source: https://context7.com/go-jira/jira/llms.txt

Uploads a file as a multipart form POST to attach it to a Jira issue. It automatically sets the required `X-Atlassian-Token: no-check` header.

```APIDOC
## `IssueAttachFile` — Attach a file to an issue

Uploads a file as a multipart form POST, setting the required `X-Atlassian-Token: no-check` header automatically.

### Parameters

- `httpClient` (*http.Client) - The HTTP client to use for the request.
- `endpoint` (string) - The Jira API endpoint URL.
- `issueKey` (string) - The key of the issue to attach the file to (e.g., "PROJ-789").
- `filename` (string) - The name of the file to be attached.
- `file` (*os.File) - The file to upload.

### Request Example

```go
import "os"

f, err := os.Open("/tmp/heapdump.hprof")
if err != nil {
    log.Fatal(err)
}
defer f.Close()

attachments, err := jira.IssueAttachFile(httpClient, endpoint, "PROJ-789", "heapdump.hprof", f)
if err != nil {
    log.Fatalf("IssueAttachFile: %v", err)
}
for _, a := range *attachments {
    fmt.Printf("Attached: id=%d filename=%s url=%s\n", a.ID, a.Filename, a.Content)
}
```

### Response

- `*[]jiradata.Attachment` - A slice of attachment information upon success.
```

--------------------------------

### Use stdin for Password Input

Source: https://github.com/go-jira/jira/blob/master/README.md

When `password-source` is set to `stdin`, the `jira login` command reads the password from standard input until EOF. This is useful for programmatic password generation.

```bash
./password-generator | jira login --endpoint=https://my.jira.endpoint.com --user=USERNAME
```