Configure¶

jira-cli reads one TOML file and a small set of JIRA_* environment variables. This page covers where that file lives, what overrides what, and the settings worth knowing. Tokens are the one thing that never live here — they sit in your keyring or 1Password; see Authenticate for that.

For the exact flags on each config subcommand, see the command reference: config init, config get, config set, config profile, config theme.

Where it lives¶

--config <path> overrides the location on any command, and config init creates the file on first run.

~/.config/jira-cli/config.toml

~/.config/jira-cli/config.toml

%AppData%\jira-cli\config.toml

What overrides what¶

When the same setting is set in more than one place, the highest wins:

1. CLI flag — --output=json, --config <path>, --profile <name>.
2. Environment variable — the JIRA_* set below.
3. Per-profile entry under [[profiles]].
4. Top-level key in config.toml.
5. Built-in default.

Profiles¶

A profile is one Jira site. The default profile covers the common case; add more when you point at several sites.

jira config init --base-url https://example.atlassian.net --email you@example.com

default_profile = "work"

[[profiles]]
  name = "work"
  base_url = "https://example.atlassian.net"
  email = "you@example.com"
  auth_type = "token"
  secret_backend = "keyring"

[[profiles]]
  name = "personal"
  base_url = "https://side-project.atlassian.net"
  email = "you@example.com"
  auth_type = "token"
  secret_backend = "1password"
  onepassword_account = "my.1password.com"
  vault = "Private"
  item = "jira-personal"

Defaults you set once¶

Set these on a profile and most commands stop needing the repetitive flags:

jira config set profiles.default.default_project ENG
jira config set profiles.default.default_issue_type Task
jira config set profiles.default.default_board "Engineering Sprint"

After this, jira issue list scopes to ENG, jira issue create defaults the type to Task, and --board resolves from default_board. config get reads a value back by its dotted key:

jira config get profiles.default.default_project --output=json

config set --dry-run runs the same key and value validation and reports the current and new value without writing the file — useful for previewing a scripted change:

jira config set theme.name dracula --dry-run --output=json

Where the token lives¶

secret_backend on each profile decides where the API token is stored — never the TOML. The token itself is covered in Authenticate; the backends:

Move a credential between the storing backends with auth migrate; it never lands in the config file. The env backend isn't a migrate target — it has no store; re-point a profile at it with jira auth login --backend env.

Any backend can be overridden for one run with JIRA_TOKEN_<PROFILE> (see the environment variables below) — it's checked before the stored backend, whichever backend the profile uses.

Themes¶

jira config theme --name catppuccin-mocha   # a bundled theme by name
jira config theme --path ~/my-theme.toml     # a custom TOML theme

Bundled names: auto, dark, light, catppuccin-{frappe,latte,macchiato,mocha}, dracula, gruvbox-{dark,light}, monochrome-{dark,light}, monokai, nord, one-dark, plain-{dark,light}, synthwave, solarized-{dark,light}, tokyo-night. JIRA_THEME=<name> overrides the configured theme for one process.

theme, so themed text (priority levels, help, markdown) stays readable on either surface. Status pills and assignee names carry fixed colours chosen to read on both light and dark, so they stay legible regardless of detection. Detection needs a real terminal: when output is piped, or --color=never / NO_COLOR is set, auto falls back to the dark theme and runs no detection. If your terminal is misdetected, pin light or dark.

Behaviour toggles¶

Reference¶

Per-profile keys¶

Top-level keys¶

Environment variables¶

Sample config.toml¶

A complete file covering two profiles, a theme, aliases, and TUI defaults. Copy, adapt, drop into ~/.config/jira-cli/config.toml.

default_profile = "work"
queries_path    = "~/.config/jira-cli/queries"
editor          = "nvim --wait"

[[profiles]]
  name = "work"
  base_url = "https://example.atlassian.net"
  email = "you@example.com"
  auth_type = "token"
  secret_backend = "keyring"
  default_project = "ENG"
  default_issue_type = "Task"
  default_board = "Engineering Sprint"
  refresh_interval = 30
  timeout = 30
  workday_seconds = 28800
  read_only = false

[[profiles]]
  name = "personal"
  base_url = "https://side-project.atlassian.net"
  email = "you@example.com"
  auth_type = "token"
  secret_backend = "1password"
  onepassword_account = "my.1password.com"
  vault = "Private"
  item = "jira-personal"

[theme]
  name = "catppuccin-mocha"

[tui]
  refresh_interval = 30
  default_tab = "issues"
  default_lens = "Team"
  preview = "right"
  preview_size = 40

[[tui.lenses]]
  title = "Team"
  jql = "project = ENG AND statusCategory != Done ORDER BY updated DESC"

[[tui.sections]]
  title = "Needs review"
  jql = "status = 'In Review' ORDER BY updated DESC"

[tui.keys]
  transition = ["T"]

[aliases]
  todo = "issue list --status \"To Do\""
  mine = "issue list --assignee me"

See also¶

• Authenticate — API tokens, keyring vs 1Password vs env, auth login and auth migrate.
• TUI — everything under [tui]: tabs, lenses, sections, preview, keybindings.
• Output and scripting — --output shapes what every command emits; the NO_COLOR / --color precedence lives in the table above.
• Cache — cached metadata lives under ~/.cache/jira-cli/<profile>-<hash>/, scoped by profile, base URL, and config path.