AI Agent Guide for jira-cli

This tool is designed for AI agents first, humans second. Interface design prioritizes agent ease of use above all else.

Critical Rules for Agents

1. NO DATA MODIFICATION WITHOUT PERMISSION — Never use create or update commands during testing or autonomous operation without explicit user approval. This is strictly forbidden.

2. Always use --output json — Required for reliable parsing and programmatic use.

3. YAML input for mutations — create and update accept structured YAML via stdin.

4. No interactive prompts — All commands are fully automatable.

Commands

Read Operations (safe for testing)

• ls — List issues with filters
• issue KEY — Get issue details
• search "JQL" — Advanced JQL queries

Write Operations (require user approval)

• create — Create issue from YAML stdin
• update --issue-key KEY — Update issue from YAML stdin

Key Points

• Auth via macOS Keychain (pre-configured by user)
• Output flattened for LLM context efficiency
• Epic issues include children in epicChildren field
• Labels are replaced on update, not merged
• Issue types vary by instance (use ls to discover)
• epicName required when creating Epos/Epic issues (customfield_10764)
• epicLink links stories/tasks to epics (customfield_10761)
• parent for subtasks only (built-in Jira field)
• parentLink for Epic → Del-leveranse hierarchy (customfield_13677)

Basic Examples

# List issues (safe)
jira-cli ls --project MUP --mine --output json

# Get details (safe)
jira-cli issue MUP-123 --output json

# Create (REQUIRES USER APPROVAL)
echo 'project: MUP
summary: Task title
type: Task' | jira-cli create --output json

# Update (REQUIRES USER APPROVAL)
echo 'summary: New title' | jira-cli update --issue-key MUP-123 --output json