Global Flags

All persistent flags listed here can be used with any jr command. They control authentication, output formatting, caching, and request behavior.

Summary

Flag	Short	Type	Default	Description
--profile	-p	string	""	Config profile to use
--base-url		string	""	Jira base URL (overrides config)
--auth-type		string	""	Auth type: basic, bearer, or oauth2 (overrides config)
--auth-user		string	""	Username for basic auth (overrides config)
--auth-token		string	""	API token or bearer token (overrides config)
--preset		string	""	Named output preset (agent, detail, triage, board)
--jq		string	""	jq filter expression applied to the response
--fields		string	""	Comma-separated list of fields to return (GET only)
--cache		duration	0	Cache GET responses for this duration
--pretty		bool	false	Pretty-print JSON output
--no-paginate		bool	false	Disable automatic pagination
--verbose		bool	false	Log HTTP request/response details to stderr
--dry-run		bool	false	Print the request as JSON without executing it
--timeout		duration	30s	HTTP request timeout
--audit		bool	false	Enable audit logging for this invocation
--audit-file		string	""	Path to audit log file (implies --audit)

Detailed reference

---

--profile / -p

Type: stringDefault: "" (uses default profile)

Select a named configuration profile. Profiles let you switch between multiple Jira instances without modifying environment variables.

# Use the "work" profile for this command
jr issue get --profile work --issueIdOrKey PROJ-123

# Short form
jr issue get -p work --issueIdOrKey PROJ-123

Profiles are created with jr configure --profile <name>. See Getting Started for setup instructions.

---

--base-url

Type: stringDefault: "" (uses value from config or JR_BASE_URL env var)

Override the Jira instance URL for a single command. Useful for one-off requests to a different instance.

jr issue get --base-url https://other.atlassian.net --issueIdOrKey OTHER-1

---

--auth-type

Type: stringDefault: "" (uses value from config)

Override the authentication type for a single command. Accepted values: basic, bearer, oauth2.

INFO

oauth2 works as a runtime override but cannot be used with jr configure — OAuth2 profiles must be configured manually in the config file since they require client_id, client_secret, and token_url.

jr raw GET /rest/api/3/myself --auth-type bearer --auth-token MY_PAT

---

--auth-user

Type: stringDefault: "" (uses value from config or JR_AUTH_USER env var)

Override the username for basic authentication. This is your Atlassian account email.

jr issue get --issueIdOrKey PROJ-1 --auth-user other@company.com --auth-token TOKEN

---

--auth-token

Type: stringDefault: "" (uses value from config or JR_AUTH_TOKEN env var)

Override the API token or bearer token for a single command.

jr raw GET /rest/api/3/myself --auth-token NEW_TOKEN

WARNING

Avoid passing tokens directly on the command line in shared environments. Prefer environment variables (JR_AUTH_TOKEN) or config file profiles for sensitive credentials.

---

--preset

Type: stringDefault: "" (no preset)

Select a named output preset that expands to a predefined set of --fields. Presets provide a shorthand for common field combinations, avoiding the need to remember or type out long --fields lists.

Preset	Fields included
agent	key, summary, status, assignee, issuetype, priority
detail	key, summary, status, assignee, issuetype, priority, description, comment, subtasks, issuelinks
triage	key, summary, status, priority, created, updated, reporter
board	key, summary, status, assignee, sprint, story_points, issuetype

# Quick agent-friendly view
jr issue get --issueIdOrKey PROJ-123 --preset agent

# Detailed view with description and comments
jr issue get --issueIdOrKey PROJ-123 --preset detail

# List available presets
jr preset list

If --preset is used together with --fields or --jq, the explicit flags take precedence.

---

--jq

Type: stringDefault: "" (no filtering)

Apply a jq filter expression to the JSON response. This is client-side filtering --- it runs after the response is received.

# Extract just the key and summary
jr issue get --issueIdOrKey PROJ-123 --jq '{key: .key, summary: .fields.summary}'

# Get all issue keys from a search
jr search search-and-reconsile-issues-using-jql \
  --jql "project = PROJ" \
  --jq '[.issues[].key]'

# Count results
jr search search-and-reconsile-issues-using-jql \
  --jql "project = PROJ" \
  --jq '.total'

TIP

Combine --jq with --fields for maximum token efficiency. --fields reduces the Jira response at the server, and --jq shapes it into exactly what you need.

---

--fields

Type: stringDefault: "" (returns all fields)

Comma-separated list of Jira fields to include in the response. This is server-side filtering --- Jira only returns the requested fields, reducing response size and API load.

Only applies to GET requests.

# Return only key, summary, and status
jr issue get --issueIdOrKey PROJ-123 --fields key,summary,status

# Combine with --jq for minimal output
jr issue get --issueIdOrKey PROJ-123 \
  --fields key,summary \
  --jq '{key: .key, summary: .fields.summary}'

---

--cache

Type: durationDefault: 0 (caching disabled)

Cache GET responses locally for the specified duration. Cached responses are returned without making an API call. Accepts Go duration strings: 5m, 1h, 30s, etc.

Only applies to GET requests.

# Cache project list for 5 minutes
jr project search --cache 5m --jq '[.values[].key]'

# Cache for 1 hour
jr issue get --issueIdOrKey PROJ-123 --cache 1h --fields key,summary

TIP

Caching is especially useful for data that changes infrequently, like project lists, issue types, and field metadata. This avoids redundant API calls and reduces rate limit consumption.

---

--pretty

Type: boolDefault: false

Pretty-print the JSON output with indentation. Useful for human inspection; agents should generally leave this off to save tokens.

jr issue get --issueIdOrKey PROJ-123 --pretty

---

--no-paginate

Type: boolDefault: false

Disable automatic pagination. By default, jr fetches all pages for paginated endpoints and merges them into a single response. Use this flag when you only need the first page or want to handle pagination yourself.

# Only get the first page of results
jr project search --no-paginate

---

--verbose

Type: boolDefault: false

Log HTTP request and response details to stderr as JSON. Stdout remains clean JSON output. Useful for debugging API interactions.

jr issue get --issueIdOrKey PROJ-123 --verbose
# stderr shows: {"method":"GET","url":"https://...","status":200,"duration":"123ms"}
# stdout shows: the issue JSON

---

--dry-run

Type: boolDefault: false

Print the HTTP request that would be made as JSON, without actually executing it. Useful for debugging request payloads, especially for POST/PUT operations.

jr issue create-issue --body '{"fields":{"project":{"key":"PROJ"},"summary":"Test"}}' --dry-run
# Outputs the request details without calling Jira

---

--timeout

Type: durationDefault: 30s

Set the HTTP request timeout. Accepts Go duration strings: 10s, 1m, 2m30s, etc.

# Increase timeout for slow responses
jr search search-and-reconsile-issues-using-jql \
  --jql "project = PROJ" \
  --timeout 2m

# Short timeout for quick checks
jr raw GET /rest/api/3/myself --timeout 5s

--audit

Type: boolDefault: false

Enable audit logging for this invocation. Writes a JSONL entry per operation to the audit log file (~/.config/jr/audit.log by default). Can also be enabled per-profile with "audit_log": true in the config file.

jr issue get --issueIdOrKey PROJ-123 --audit

---

--audit-file

Type: stringDefault: "" (uses ~/.config/jr/audit.log)

Path to the audit log file. Implies --audit. Useful for directing audit logs to a specific location.

jr issue get --issueIdOrKey PROJ-123 --audit-file /var/log/jr-audit.log

---

Configuration resolution order

Flags override environment variables, which override the config file:

CLI flags  >  Environment variables  >  Config file (profile)

For example, if your config file sets base-url to https://a.atlassian.net but you pass --base-url https://b.atlassian.net, the flag value wins.