lazyjira

The lazyjira documentation is organized into three main sections to help you configure and use the tool:

• Configuration: Details on how to set up the application and its settings.
• Keybindings: Information on how to map and use keyboard shortcuts.
• Fields: Guidance on working with custom fields within Jira.

If you do not explicitly set a type in your configuration, lazyjira attempts to detect the type based on the data returned from Jira:

• person: An object containing a displayName key.
• select: An object containing a value or name key.
• multiselect: An array.
• text: Any other data format.

To see all available keybindings while running lazyjira, press ?. If the list is long, you can filter the bindings by typing / inside the help popup.

`?` -> View Help
`/` (inside help) -> Filter bindings

You can define custom tabs in the issue list using JQL. Use the issueTabs key in your config. Template variables {{.ProjectKey}} and {{.UserEmail}} are expanded at runtime.

Each tab can have a name, a jql query, and an optional maxResults to limit the page size.

issueTabs:
  - name: "All"
    jql: "project = {{.ProjectKey}} AND statusCategory != Done ORDER BY updated DESC"
  - name: "Assigned"
    jql: "project = {{.ProjectKey}} AND assignee=currentUser() ORDER BY priority DESC"
  - name: "Recent"
    jql: "project = {{.ProjectKey}} AND updated >= -7d ORDER BY updated DESC"
    maxResults: 100

If your Jira instance requires client certificates (mTLS) or a custom CA, configure the tls block under jira in your YAML config:

You can also use the corresponding environment variables: JIRA_TLS_CERT, JIRA_TLS_KEY, JIRA_TLS_CA, and JIRA_TLS_INSECURE.

jira:
  tls:
    certFile: /path/to/client.crt
    keyFile:  /path/to/client.key
    caFile:   /path/to/ca.pem
    insecure: false

The gui.theme setting controls the color palette. Supported values include:

• default: ANSI 16 palette (inherits terminal colors).
• auto: Automatically detects terminal background and picks either catppuccin-mocha (dark) or catppuccin-latte (light).
• Catppuccin presets: catppuccin-latte, catppuccin-frappe, catppuccin-macchiato, catppuccin-mocha.

You can override specific colors using themeColors (applies to all presets), themeDark (applies to dark presets), or themeLight (applies to light presets). Supported keys include green, blue, red, yellow, cyan, magenta, orange, white, gray, and highlight.

Values can be hex ("#a6e3a1"), ANSI 16 ("4"), or ANSI 256 ("208").

gui:
  theme: catppuccin-mocha
  themeColors:
    green:     "#94e2d5"
    highlight: "#45475a"

By default, lazyjira assumes you are using Jira Cloud (which uses email + API token via Basic auth). To connect to Jira Server or Data Center (which uses a Personal Access Token via Bearer auth), set the serverType to server or datacenter in your config file.

Note: Server/Data Center connections do not require an email field.

jira:
  serverType: server

On the first launch of lazyjira, a setup wizard will guide you through connecting to your Jira instance. Credentials are saved to ~/.config/lazyjira/auth.json.

Jira Cloud

You will need:

1. Your email address.
2. An API token (Personal Access Token).
   • Create one at: https://id.atlassian.com/manage-profile/security/api-tokens

Jira Server / Data Center

You will need:

1. A Personal Access Token (PAT).
2. No email is required.
   • Generate a PAT in Jira via: Profile > Personal Access Tokens > Create token.

Note: For environments requiring client certificates (mTLS), refer to the Configuration documentation.

To find the specific IDs for your custom fields (e.g., customfield_12345), query the Jira REST API:

GET /rest/api/3/field

In the response, look for objects where custom is true. The id field in that object is the value you should use in your lazyjira configuration.

# Example conceptual request
GET /rest/api/3/field

To edit a field, press e while focused on that field in the info panel. The editing interface depends on the field type:

• select: Shows a picker with allowed values from Jira.
• multiselect: Shows a checklist.
• user/person: Shows a user picker.
• text: Shows an inline input.
• textarea or fields with multiline: true: Opens your system $EDITOR.

Note: Fields explicitly typed as text or textarea skip the CreateMeta API call and go directly to the input interface.