@fatecannotbealtered-/jira-cli 1.0.4 → 1.0.6

package/CHANGELOG.md

@@ -7,6 +7,30 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.0.6] - 2026-06-05
+
+### Added
+
+- **Built-in `update` command** — standalone binaries can check GitHub Releases, verify `checksums.txt`, and replace the current executable. Package-manager installs are detected and guided back to the package manager unless `--force` is used.
+- **Global output format control** — `--format json|text|raw` now controls CLI output across commands. JSON is the default for agent-friendly parsing, `text` keeps human-readable tables and prompts, and `raw` is explicitly supported only by commands that can return raw output.
+
+### Changed
+
+- **Agent-friendly defaults** — commands now emit stable JSON by default, while `--json` remains a compatibility alias for `--format json`.
+- **Reference output** — `jira-cli reference` now defaults to structured JSON; use `jira-cli --format text reference` for the Markdown command reference.
+- **Output flag rules** — `--compact` and `--fields` are JSON-only, `--quiet` no longer suppresses JSON/raw result bodies, and unsupported `raw` output returns an argument error instead of silently downgrading.
+
+### Fixed
+
+- **Structured argument errors** — Cobra argument validation errors now return machine-readable JSON by default instead of plain text.
+- **Clean JSON stdout** — interactive prompts and cancellation/error paths no longer pollute JSON success output.
+
+## [1.0.5] - 2026-06-02
+
+### Added
+
+- **`issue attachments` download** — the command can now fetch attachment content, not just list metadata. `--out <dir>` downloads all attachments into a directory; add `--id <attachmentId>` to download a single one (exit code 4 if not found). With `--json` it prints `{id, filename, path, mimeType}` per saved file. Downloads stream to disk (handles large files like screen recordings) and validate the content URL points at the configured Jira host. The `attachments --json` listing now also includes the `content` download URL.
+
 ## [1.0.4] - 2026-05-31
 
 ### Fixed
@@ -113,7 +137,10 @@ Initial release of jira-cli for Jira Data Center.
 - SKILL.md with JSON output schemas, error codes, exit codes, and complete flag reference.
 - GitHub PR template for contributors.
 
-[Unreleased]: https://github.com/fatecannotbealtered/jira-cli/compare/v1.0.3...HEAD
+[Unreleased]: https://github.com/fatecannotbealtered/jira-cli/compare/v1.0.6...HEAD
+[1.0.6]: https://github.com/fatecannotbealtered/jira-cli/compare/v1.0.5...v1.0.6
+[1.0.5]: https://github.com/fatecannotbealtered/jira-cli/compare/v1.0.4...v1.0.5
+[1.0.4]: https://github.com/fatecannotbealtered/jira-cli/compare/v1.0.3...v1.0.4
 [1.0.3]: https://github.com/fatecannotbealtered/jira-cli/compare/v1.0.2...v1.0.3
 [1.0.2]: https://github.com/fatecannotbealtered/jira-cli/compare/v1.0.1...v1.0.2
 [1.0.1]: https://github.com/fatecannotbealtered/jira-cli/compare/v1.0.0...v1.0.1

package/README.md

@@ -11,7 +11,7 @@ Full-featured Jira Data Center CLI for humans and AI Agents. Manage issues, spri
 
 Built with Go. Single static binary (small dependency footprint via `go.mod`). No separate runtime to install.
 
-[Installation](#installation) · [Authentication](#authentication) · [Commands](#commands) · [JSON Output](#json-output) · [Security](#security) · [Contributing](#contributing) · [Disclaimer](#disclaimer)
+[Installation](#installation) · [Updating](#updating) · [Authentication](#authentication) · [Commands](#commands) · [Output Formats](#output-formats) · [Security](#security) · [Contributing](#contributing) · [Disclaimer](#disclaimer)
 
 ## Disclaimer
 
@@ -22,12 +22,13 @@ This project is shared for **personal learning, research, and everyday productiv
 | Capability | Description |
 |---|---|
 | 🎯 **Complete Coverage** | Issues, Sprints, Boards, Epics, Projects, Users, Filters |
-| 🤖 **AI Friendly** | `--json` flat output (token-efficient), `--quiet`, `--dry-run`, `--force`, `--fields`, `--raw` |
+| 🤖 **AI Friendly** | JSON by default, `--format json\|text\|raw`, `--compact`, `--quiet`, `--dry-run`, `--force`, `--fields` |
 | ⚡ **Single Binary** | Download and run; no JVM/Node required for the CLI itself |
 | 🔄 **Smart Retry** | Auto-retry on 429 rate limits and 5xx errors with exponential backoff |
 | 🌈 **Beautiful Output** | Colored tables with CJK character support |
 | 🔍 **Powerful Search** | Full JQL support with auto-pagination |
 | 🔧 **Custom Fields** | Set custom fields during create and edit |
+| ⬆️ **Safe Update** | Built-in release checks, checksum verification, package-manager guardrails |
 | 🔐 **PAT Auth** | Bearer token authentication (Personal Access Token) |
 | 🌐 **Env Vars** | `JIRA_HOST` and `JIRA_TOKEN` override config file for CI/Agent use |
 | 📋 **Audit Log** | Automatic JSONL audit trail for all write commands with auto-rotation |
@@ -39,7 +40,8 @@ This project is shared for **personal learning, research, and everyday productiv
 Copy the block below to your agent (or run it yourself):
 
 ```bash
-# Please install jira-cli and use it for all Jira DC operations going forward (always pass --json).
+# Please install jira-cli and use it for all Jira DC operations going forward.
+# Machine-readable JSON is the default; use --format text only for human-readable output.
 # Install CLI (requires curl on PATH — used to download the binary)
 npm install -g @fatecannotbealtered-/jira-cli
 
@@ -48,7 +50,7 @@ npx skills add fatecannotbealtered/jira-cli -y -g
 
 # Login and verify
 jira-cli login
-jira-cli doctor --json
+jira-cli doctor
 ```
 
 Optional: `jira-cli install-skill` copies the bundled skill to `~/.openclaw/skills` for OpenClaw-compatible agents.
@@ -63,6 +65,22 @@ go install github.com/fatecannotbealtered/jira-cli/cmd/jira-cli@latest
 
 Download from [GitHub Releases](https://github.com/fatecannotbealtered/jira-cli/releases) and add to your PATH.
 
+## Updating
+
+```bash
+jira-cli update --check              # check latest GitHub Release
+jira-cli update                      # update a standalone binary
+jira-cli update --version v1.2.3     # install a specific release
+```
+
+`jira-cli update` verifies `checksums.txt` before replacing the current binary. If the CLI was installed through npm, the command will recommend the package-manager path instead:
+
+```bash
+npm install -g @fatecannotbealtered-/jira-cli@latest
+```
+
+Use `--dry-run` to preview and `--force` only when intentionally replacing the binary in place.
+
 ## Authentication
 
 jira-cli supports **Jira Data Center** (private deployments) with **Personal Access Token (PAT)** authentication.
@@ -92,7 +110,7 @@ Environment variables take precedence over the config file. This is the recommen
 ```bash
 export JIRA_HOST=https://jira.company.com
 export JIRA_TOKEN=<your-personal-access-token>
-jira-cli doctor --json   # verify authValid is true
+jira-cli doctor   # verify authValid is true
 ```
 
 ### Generating a PAT
@@ -117,7 +135,7 @@ jira-cli issue create --project PROJ --summary "Sized story" --field "Story Poin
 jira-cli issue edit PROJ-123 --priority High --assignee me
 jira-cli issue edit PROJ-123 --field "Story Points=8" --field "Team=Backend"
 jira-cli issue delete PROJ-123 --force          # --force skips confirmation prompt
-jira-cli issue delete PROJ-123 --dry-run --json   # preview delete (no confirmation prompt)
+jira-cli issue delete PROJ-123 --dry-run   # preview delete (no confirmation prompt)
 
 # Clone
 jira-cli issue clone PROJ-123
@@ -148,6 +166,9 @@ jira-cli issue worklog list PROJ-123
 # Links & Attachments
 jira-cli issue link PROJ-123 --to PROJ-456 --type "blocks"
 jira-cli issue attach PROJ-123 --file ./screenshot.png
+jira-cli issue attachments PROJ-123                       # List attachments
+jira-cli issue attachments PROJ-123 --out ./downloads     # Download all attachments
+jira-cli issue attachments PROJ-123 --out ./downloads --id 4609477   # Download one by ID
 jira-cli issue remote-link PROJ-123 --url https://pr.url --title "PR #42"
 ```
 
@@ -197,49 +218,60 @@ jira-cli user search --query "john"
 jira-cli user me
 jira-cli filter list
 jira-cli filter run <filterId>
-jira-cli filter run <filterId> --json --fields key,summary,status
-jira-cli filter run <filterId> --json --raw
+jira-cli filter run <filterId> --fields key,summary,status
+jira-cli --format raw filter run <filterId>
 ```
 
-## JSON Output
+## Output Formats
+
+`jira-cli` defaults to machine-readable JSON, so scripts and AI Agents can omit output flags. Use `--format json|text|raw` to choose the result format:
+
+- `json` is the default. Success JSON goes to stdout; error JSON goes to stderr.
+- `text` is for human-readable summaries, tables, colors, diff/log text, and prompts.
+- `raw` is for unwrapped raw command results where supported. Unsupported commands return an argument error instead of silently downgrading.
 
-All commands support `--json` for machine-readable output. **Success JSON goes to stdout; error JSON goes to stderr** — pipe or capture stdout for data, check `$?` and stderr for failures.
+`--json` remains as a compatibility alias for `--format json`, but new scripts should rely on the default or use `--format json`. `--json` cannot be combined with `--format text` or `--format raw`.
 
-By default, issue and sprint data is returned in a **flat, token-efficient format** (ideal for AI Agents):
+`--compact` only affects JSON. `--fields` only works with JSON output. `--quiet` suppresses auxiliary text output only; it does not suppress JSON or raw main results.
+
+By default, issue and sprint data is returned in a **flat, token-efficient JSON format** (ideal for AI Agents):
 
 ```bash
 # Flat JSON (default) — minimal fields, low token cost
-jira-cli issue get PROJ-123 --json
-jira-cli search "project = PROJ" --json | jq '.issues[].key'
+jira-cli issue get PROJ-123
+jira-cli search "project = PROJ" | jq '.issues[].key'
 
 # issue list returns a bare array; search wraps issues in pagination metadata
 # filter run with --fields also returns a bare trimmed array
-jira-cli issue list --project PROJ --json | jq '.[].key'
-jira-cli search "project = PROJ" --json | jq '.issues[].key'
-jira-cli filter run 12345 --json --fields key,summary | jq '.[].key'
+jira-cli issue list --project PROJ | jq '.[].key'
+jira-cli search "project = PROJ" | jq '.issues[].key'
+jira-cli filter run 12345 --fields key,summary | jq '.[].key'
 
 # Trim flat JSON output (issue get / issue list / sprint / filter run)
-jira-cli issue get PROJ-123 --json --fields key,summary,status,assignee
+jira-cli issue get PROJ-123 --fields key,summary,status,assignee
 
 # search --fields controls which fields Jira fetches (API request), not output trimming
-jira-cli search "project = PROJ" --fields summary,status,customfield_10001 --json
+jira-cli search "project = PROJ" --fields summary,status,customfield_10001
 
 # Raw Jira API response (full nested structure)
-jira-cli issue get PROJ-123 --json --raw
+jira-cli --format raw issue get PROJ-123
+
+# Human-readable output
+jira-cli --format text issue get PROJ-123
 
-# Clean output for scripts (suppress all non-JSON noise on stdout)
-jira-cli issue get PROJ-123 --json --quiet
+# Compact JSON for logs or pipes
+jira-cli --compact issue get PROJ-123
 
 # Preview destructive operations without executing
-jira-cli issue delete PROJ-123 --dry-run --json
+jira-cli issue delete PROJ-123 --dry-run
 ```
 
 ### Verify connectivity (`doctor`)
 
-When using `--json`, check the `authValid` field (exit code 3 on auth/config failure):
+With the default JSON output, check the `authValid` field (exit code 3 on auth/config failure):
 
 ```bash
-jira-cli doctor --json | jq '.authValid'   # must be true
+jira-cli doctor | jq '.authValid'   # must be true
 ```
 
 Error responses (stderr) include machine-readable error codes and actionable hints:
@@ -255,7 +287,7 @@ Error responses (stderr) include machine-readable error codes and actionable hin
 
 Set `NO_COLOR=1` to disable colored output (useful in CI/CD).
 
-Run `jira-cli reference` to get a complete listing of all commands and flags in structured markdown.
+Run `jira-cli reference` to get a structured JSON listing of all commands and flags. Use `jira-cli --format text reference` for the markdown reference.
 
 ## Environment Variables
 
@@ -283,18 +315,22 @@ Credentials stored at `~/.jira-cli/config.json` (permissions: 0600):
 
 | Flag | Description |
 |---|---|
-| `--json` | Output as JSON (flat format by default; use `--raw` for full Jira response) |
+| `--format json\|text\|raw` | Control output format. Default: `json` |
+| `--compact` | Emit compact JSON (only with `--format json`) |
+| `--json` | Compatibility alias for `--format json`; not recommended for new scripts |
 | `--force` | Skip interactive confirmation prompts |
-| `--quiet` | Suppress non-JSON stdout output (for scripts and AI Agents) |
-| `--dry-run` | Show what would be done without executing (write commands only) |
+| `--quiet` | Suppress auxiliary text output; does not suppress JSON/raw main results |
+| `--dry-run` | Show what would be done without executing (supported by write/update commands) |
 
 ### Per-command flags
 
 | Flag | Commands | Description |
 |---|---|---|
-| `--raw` | `issue get`, `issue list`, `search`, `filter run`, `sprint list`, `sprint issues`, `sprint active` | Return raw Jira API response instead of flat format |
-| `--fields` | `issue get`, `issue list`, `sprint list`, `sprint issues`, `filter run` | **Output trimming** — include only listed fields in flat JSON (e.g. `--fields key,summary,status`) |
-| `--fields` | `search` only | **Jira fetch fields** — comma-separated fields to request from the API (e.g. `--fields summary,status,customfield_10001`); does not trim flat output |
+| `--raw` | `issue get`, `issue list`, `search`, `filter run`, `sprint list`, `sprint issues`, `sprint active` | Legacy alias for `--format raw` on commands that support raw output |
+| `--fields` | `issue get`, `issue list`, `sprint list`, `sprint issues`, `filter run` | **JSON output trimming** — include only listed fields in flat JSON (e.g. `--fields key,summary,status`) |
+| `--fields` | `search` only | **Jira fetch fields** — comma-separated fields to request from the API (e.g. `--fields summary,status,customfield_10001`); only valid with JSON output |
+| `--out` | `issue attachments` | Download attachments into this directory instead of listing (default cwd via the dir you pass); JSON output prints `{id, filename, path, mimeType}` |
+| `--id` | `issue attachments` | With `--out`, download only the attachment with this ID (exit code 4 if not found) |
 
 ## Troubleshooting
 
@@ -317,7 +353,7 @@ Credentials stored at `~/.jira-cli/config.json` (permissions: 0600):
 - No credentials are logged or transmitted to third parties
 - Environment variables `JIRA_HOST` and `JIRA_TOKEN` take precedence over config file
 
-> **AI Agent Note:** This tool can be invoked by AI Agents to automate Jira operations. Use `--force` to skip interactive prompts and `--json` for structured output. Set `JIRA_HOST` and `JIRA_TOKEN` environment variables for non-interactive authentication.
+> **AI Agent Note:** This tool can be invoked by AI Agents to automate Jira operations. Structured JSON is the default; use `--format text` only when human-readable output is needed. Set `JIRA_HOST` and `JIRA_TOKEN` environment variables for non-interactive authentication.
 
 For vulnerability reports, see [SECURITY.md](SECURITY.md).
 
@@ -399,6 +435,7 @@ jira-cli/
 │   ├── issue_*.go           # Issue sub-commands
 │   ├── flatten.go           # Flat JSON output helpers (issues, sprints)
 │   ├── reference.go         # Self-documenting command reference
+│   ├── update.go            # GitHub Release self-update
 │   ├── sprint.go            # Sprint management
 │   ├── board.go             # Board operations
 │   ├── project.go           # Project management

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fatecannotbealtered-/jira-cli",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "description": "Full-featured Jira Data Center CLI for humans and AI Agents — manage issues, sprints, boards, epics, projects, users, and filters from your terminal",
   "keywords": [
     "jira",

package/scripts/run.js

@@ -8,7 +8,13 @@ const ext = process.platform === "win32" ? ".exe" : "";
 const bin = path.join(__dirname, "..", "bin", "jira-cli" + ext);
 
 try {
-  execFileSync(bin, process.argv.slice(2), { stdio: "inherit" });
+  execFileSync(bin, process.argv.slice(2), {
+    stdio: "inherit",
+    env: {
+      ...process.env,
+      JIRA_CLI_INSTALL_METHOD: process.env.JIRA_CLI_INSTALL_METHOD || "npm",
+    },
+  });
 } catch (e) {
   if (e.code === "ENOENT") {
     console.error("Binary not found. Run 'npm install -g @fatecannotbealtered-/jira-cli' to reinstall.");

package/skills/jira-cli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jira-cli
-description: Full Jira Data Center control from the terminal. Manage issues, sprints, boards, epics, projects, users, and filters. Use --json flag for machine-readable output when parsing results programmatically.
+description: Full Jira Data Center control from the terminal. Manage issues, sprints, boards, epics, projects, users, and filters. Output is machine-readable JSON by default; use --format text only for human-readable output.
 metadata: {"openclaw":{"emoji":"🎯","requires":{"bins":["jira-cli"]}}}
 ---
 
@@ -9,7 +9,8 @@ metadata: {"openclaw":{"emoji":"🎯","requires":{"bins":["jira-cli"]}}}
 Jira Data Center CLI for humans and AI Agents. Supports **Jira DC only** (self-hosted), not Jira Cloud.
 
 ```bash
-# Please install jira-cli and use it for all Jira DC operations going forward (always pass --json).
+# Please install jira-cli and use it for all Jira DC operations going forward.
+# Machine-readable JSON is the default; use --format text only for human-readable output.
 # Install CLI (requires curl on PATH)
 npm install -g @fatecannotbealtered-/jira-cli
 
@@ -18,11 +19,26 @@ npx skills add fatecannotbealtered/jira-cli -y -g
 
 # Login and verify
 jira-cli login
-jira-cli doctor --json
+jira-cli doctor
 ```
 
 Optional: `jira-cli install-skill` → `~/.openclaw/skills`.
 
+## Updating
+
+```bash
+jira-cli update --check              # Check the latest GitHub Release
+jira-cli update                      # Update a standalone binary after checksum verification
+```
+
+If the CLI was installed through npm, prefer the package manager instead of in-place replacement:
+
+```bash
+npm install -g @fatecannotbealtered-/jira-cli@latest
+```
+
+Use `--dry-run` to preview. Use `--force` only when the user explicitly wants in-place binary replacement.
+
 ## Prerequisites
 
 Before using any command, authenticate with a Jira DC instance. Follow these steps in order:
@@ -31,19 +47,19 @@ Before using any command, authenticate with a Jira DC instance. Follow these ste
 2. Ask the user for a **Personal Access Token (PAT)**. If they don't have one, guide them:
    "Log in to your Jira DC → click your profile avatar → Personal Access Tokens → Create token."
 3. Run `jira-cli login --host <URL> --token <PAT>` to save credentials.
-4. Run `jira-cli doctor --json` to verify connectivity. Check that `authValid` is `true` (exit code 3 on auth/config failure).
+4. Run `jira-cli doctor` to verify connectivity. Check that `authValid` is `true` (exit code 3 on auth/config failure).
 
 **Important:** Credentials are saved locally at `~/.jira-cli/config.json`. Environment variables `JIRA_HOST` and `JIRA_TOKEN` override the config file — use them for CI or when the user prefers not to save credentials.
 
-**Always use `--json` flag when parsing output.** Without it, output is human-formatted and not suitable for programmatic use.
+**Do not add output flags for programmatic parsing.** JSON is the default. Use `--format text` only when the user wants human-readable tables or summaries.
 
-**Stdout vs stderr:** Success JSON is written to **stdout**; error JSON is written to **stderr**. Capture stdout for data; check exit code and stderr for failures.
+**Stdout vs stderr:** Success JSON is written to **stdout** by default; error JSON is written to **stderr**. Capture stdout for data; check exit code and stderr for failures.
 
 ## Safety
 
 - **Do NOT use `--force` on destructive commands unless the user explicitly asks.** Commands like `issue delete` prompt for confirmation by default. Skipping confirmation with `--force` is irreversible.
 - **`issue delete --dry-run` skips confirmation** — dry-run is evaluated before the confirmation prompt.
-- **Use `--dry-run` before write operations** to preview what will happen without executing. Example: `issue create --project PROJ --summary "test" --type Task --dry-run --json`.
+- **Use `--dry-run` before write operations** to preview what will happen without executing. Example: `issue create --project PROJ --summary "test" --type Task --dry-run`.
 - **AI Agents can make mistakes.** Always confirm with the user before executing `issue delete`, `issue bulk-transition`, `sprint close`, or any operation that modifies multiple issues.
 - All write operations are recorded in `~/.jira-cli/audit/` for traceability.
 
@@ -51,34 +67,34 @@ Before using any command, authenticate with a Jira DC instance. Follow these ste
 
 ```bash
 # View issues (flat JSON by default — token-efficient)
-jira-cli issue get PROJ-123 --json
-jira-cli issue get PROJ-123 --json --fields key,summary,status,assignee   # Output trimming (flat JSON)
-jira-cli issue get PROJ-123 --json --raw                                  # Full Jira API response
-jira-cli issue list --project PROJ --json                                 # Returns bare array of flat issues
-jira-cli issue list --project PROJ --json --fields key,summary,status     # Trimmed array
+jira-cli issue get PROJ-123
+jira-cli issue get PROJ-123 --fields key,summary,status,assignee   # Output trimming (flat JSON)
+jira-cli --format raw issue get PROJ-123                            # Full Jira API response
+jira-cli issue list --project PROJ                                  # Returns bare array of flat issues
+jira-cli issue list --project PROJ --fields key,summary,status      # Trimmed array
 
 # Create and edit
-jira-cli issue create --project PROJ --summary "Fix login bug" --type Bug --json
-jira-cli issue create --project PROJ --summary "New feature" --type Story --assignee me --priority High --json
-jira-cli issue create --project PROJ --summary "Sized story" --type Story --field "Story Points=5" --json
+jira-cli issue create --project PROJ --summary "Fix login bug" --type Bug
+jira-cli issue create --project PROJ --summary "New feature" --type Story --assignee me --priority High
+jira-cli issue create --project PROJ --summary "Sized story" --type Story --field "Story Points=5"
 jira-cli issue edit PROJ-123 --summary "Updated summary" --priority Medium
 jira-cli issue edit PROJ-123 --field "Story Points=8" --field "Team=Backend"
 jira-cli issue delete PROJ-123 --force          # Skip confirmation prompt
-jira-cli issue delete PROJ-123 --dry-run --json   # Preview delete (no confirmation prompt)
+jira-cli issue delete PROJ-123 --dry-run        # Preview delete (no confirmation prompt)
 
 # Clone an issue
-jira-cli issue clone PROJ-123 --json                                # Clone with default summary
-jira-cli issue clone PROJ-123 --summary "New title" --json          # Clone with custom summary
-jira-cli issue clone PROJ-123 --with-links --json                   # Clone with issue links
+jira-cli issue clone PROJ-123                                # Clone with default summary
+jira-cli issue clone PROJ-123 --summary "New title"          # Clone with custom summary
+jira-cli issue clone PROJ-123 --with-links                   # Clone with issue links
 
 # Status transitions
-jira-cli issue transitions PROJ-123 --json          # List available transitions
+jira-cli issue transitions PROJ-123                 # List available transitions
 jira-cli issue transition PROJ-123 "In Progress"    # Transition to status (name required)
-jira-cli issue transition PROJ-123 "Done" --json
+jira-cli issue transition PROJ-123 "Done"
 
 # Bulk transition
-jira-cli issue bulk-transition "Done" --issues PROJ-1,PROJ-2,PROJ-3 --json
-jira-cli issue bulk-transition "In Progress" --jql "project = PROJ AND sprint = 10 AND status = 'To Do'" --json
+jira-cli issue bulk-transition "Done" --issues PROJ-1,PROJ-2,PROJ-3
+jira-cli issue bulk-transition "In Progress" --jql "project = PROJ AND sprint = 10 AND status = 'To Do'"
 
 # Assignment and watching
 jira-cli issue assign PROJ-123 me                   # Assign to current user
@@ -86,112 +102,114 @@ jira-cli issue assign PROJ-123 johndoe              # Assign by username (DC use
 jira-cli issue unassign PROJ-123
 jira-cli issue watch PROJ-123
 jira-cli issue unwatch PROJ-123
-jira-cli issue watchers PROJ-123 --json
+jira-cli issue watchers PROJ-123
 jira-cli issue vote PROJ-123
 jira-cli issue unvote PROJ-123
 
 # Comments
-jira-cli issue comment add PROJ-123 --body "Fixed in PR #42" --json
-jira-cli issue comment list PROJ-123 --json
+jira-cli issue comment add PROJ-123 --body "Fixed in PR #42"
+jira-cli issue comment list PROJ-123
 jira-cli issue comment delete PROJ-123 --id <commentId>
 
 # Worklogs
-jira-cli issue worklog add PROJ-123 --time 2h --comment "Debugging session" --json
+jira-cli issue worklog add PROJ-123 --time 2h --comment "Debugging session"
 jira-cli issue worklog add PROJ-123 --time 1h30m --started "2024-01-15T10:00:00.000+0000"
-jira-cli issue worklog list PROJ-123 --json
+jira-cli issue worklog list PROJ-123
 
 # Links
-jira-cli issue link-types --json                                    # List available link types
+jira-cli issue link-types                                           # List available link types
 jira-cli issue link PROJ-123 --to PROJ-456 --type "blocks"
 jira-cli issue unlink <linkId>
 jira-cli issue remote-link PROJ-123 --url https://pr.url --title "PR #42"
-jira-cli issue remote-links PROJ-123 --json
+jira-cli issue remote-links PROJ-123
 
 # Attachments
 jira-cli issue attach PROJ-123 --file ./screenshot.png
-jira-cli issue attachments PROJ-123 --json
+jira-cli issue attachments PROJ-123                              # list metadata (incl. content URL)
+jira-cli issue attachments PROJ-123 --out ./dl                   # download all -> [{id,filename,path,mimeType}]
+jira-cli issue attachments PROJ-123 --out ./dl --id 4609477      # download a single attachment by ID
 ```
 
 ## Search (JQL)
 
 ```bash
 # Basic search
-jira-cli search "assignee = currentUser() AND status != Done" --json
-jira-cli search "project = PROJ AND sprint in openSprints()" --json
+jira-cli search "assignee = currentUser() AND status != Done"
+jira-cli search "project = PROJ AND sprint in openSprints()"
 
 # Advanced options
-jira-cli search "project = PROJ" --limit 100 --json
-jira-cli search "project = PROJ" --all --json          # Fetch ALL results (auto-paginate)
+jira-cli search "project = PROJ" --limit 100
+jira-cli search "project = PROJ" --all                 # Fetch ALL results (auto-paginate)
 jira-cli search "project = PROJ" --count               # Only show total count
-jira-cli search "project = PROJ" --order-by updated --json
-jira-cli search "type = Bug AND priority = High" --fields summary,status,customfield_10001 --json  # Jira fetch fields (API request)
+jira-cli search "project = PROJ" --order-by updated
+jira-cli search "type = Bug AND priority = High" --fields summary,status,customfield_10001  # Jira fetch fields (API request)
 ```
 
 ## Sprint Management
 
 ```bash
-jira-cli board list --json                                          # Find board IDs first
-jira-cli sprint list --board 42 --json
-jira-cli sprint list --board 42 --state active --json
-jira-cli sprint active --board 42 --json                           # Active sprint + issues
-jira-cli sprint issues --sprint 10 --json
-jira-cli sprint create --board 42 --name "Sprint 5" --start-date 2024-02-01 --end-date 2024-02-14 --json
+jira-cli board list                                                 # Find board IDs first
+jira-cli sprint list --board 42
+jira-cli sprint list --board 42 --state active
+jira-cli sprint active --board 42                                  # Active sprint + issues
+jira-cli sprint issues --sprint 10
+jira-cli sprint create --board 42 --name "Sprint 5" --start-date 2024-02-01 --end-date 2024-02-14
 jira-cli sprint update --sprint 10 --goal "Complete payment refactor"
 jira-cli sprint move --sprint 10 --issues PROJ-123,PROJ-124,PROJ-125
-jira-cli sprint close --sprint 10 --json
-jira-cli sprint close --sprint 10 --dry-run --json   # Preview without closing (no confirmation prompt)
+jira-cli sprint close --sprint 10
+jira-cli sprint close --sprint 10 --dry-run   # Preview without closing (no confirmation prompt)
 ```
 
 ## Board & Backlog
 
 ```bash
-jira-cli board list --json
-jira-cli board list --project PROJ --type scrum --json
-jira-cli board get --board 42 --json
-jira-cli board backlog --board 42 --json
-jira-cli board epics --board 42 --json
-jira-cli board sprints --board 42 --state active --json
+jira-cli board list
+jira-cli board list --project PROJ --type scrum
+jira-cli board get --board 42
+jira-cli board backlog --board 42
+jira-cli board epics --board 42
+jira-cli board sprints --board 42 --state active
 ```
 
 ## Epic Management
 
 ```bash
-jira-cli epic list --board 42 --json
-jira-cli epic list --board 42 --done --json              # Completed epics only
-jira-cli epic issues PROJ-1 --board 42 --json
+jira-cli epic list --board 42
+jira-cli epic list --board 42 --done              # Completed epics only
+jira-cli epic issues PROJ-1 --board 42
 ```
 
 ## Project Management
 
 ```bash
-jira-cli project list --json
-jira-cli project list --type software --json
-jira-cli project get PROJ --json
-jira-cli project components PROJ --json
-jira-cli project versions PROJ --json
-jira-cli project versions PROJ --unreleased --json
-jira-cli project issue-types PROJ --json
-jira-cli project fields --json                       # List all fields (system + custom)
-jira-cli project fields --custom --json              # List custom fields only
+jira-cli project list
+jira-cli project list --type software
+jira-cli project get PROJ
+jira-cli project components PROJ
+jira-cli project versions PROJ
+jira-cli project versions PROJ --unreleased
+jira-cli project issue-types PROJ
+jira-cli project fields                       # List all fields (system + custom)
+jira-cli project fields --custom              # List custom fields only
 ```
 
 ## User Search
 
 ```bash
-jira-cli user me --json                                  # Current user info
-jira-cli user search --query "john" --json
-jira-cli user search --query "john" --assignable --project PROJ --json
+jira-cli user me                                  # Current user info
+jira-cli user search --query "john"
+jira-cli user search --query "john" --assignable --project PROJ
 ```
 
 ## Filters
 
 ```bash
-jira-cli filter list --json
-jira-cli filter get <filterId> --json
-jira-cli filter create --name "My Bugs" --jql "assignee = me AND type = Bug" --json
-jira-cli filter run <filterId> --json
-jira-cli filter run <filterId> --json --fields key,summary,status   # Output trimming
-jira-cli filter run <filterId> --json --raw                         # Raw Jira search response
+jira-cli filter list
+jira-cli filter get <filterId>
+jira-cli filter create --name "My Bugs" --jql "assignee = me AND type = Bug"
+jira-cli filter run <filterId>
+jira-cli filter run <filterId> --fields key,summary,status   # Output trimming
+jira-cli --format raw filter run <filterId>                  # Raw Jira search response
 jira-cli filter delete <filterId>
 ```
 
@@ -200,13 +218,13 @@ jira-cli filter delete <filterId>
 ### Find and update an issue
 ```bash
 # 1. Search for issues
-jira-cli search "project = PROJ AND assignee = me AND status = 'In Progress'" --json
+jira-cli search "project = PROJ AND assignee = me AND status = 'In Progress'"
 
 # 2. Get issue details
-jira-cli issue get PROJ-123 --json
+jira-cli issue get PROJ-123
 
 # 3. Check available transitions
-jira-cli issue transitions PROJ-123 --json
+jira-cli issue transitions PROJ-123
 
 # 4. Transition to Done
 jira-cli issue transition PROJ-123 "Done"
@@ -218,16 +236,16 @@ jira-cli issue comment add PROJ-123 --body "Completed and deployed to staging"
 ### Sprint planning workflow
 ```bash
 # 1. Find the board
-jira-cli board list --json
+jira-cli board list
 
 # 2. Check active sprint
-jira-cli sprint active --board 42 --json
+jira-cli sprint active --board 42
 
 # 3. View backlog
-jira-cli board backlog --board 42 --json
+jira-cli board backlog --board 42
 
 # 4. Create next sprint
-jira-cli sprint create --board 42 --name "Sprint 6" --start-date 2024-02-15 --end-date 2024-02-28 --json
+jira-cli sprint create --board 42 --name "Sprint 6" --start-date 2024-02-15 --end-date 2024-02-28
 
 # 5. Move issues to sprint
 jira-cli sprint move --sprint 11 --issues PROJ-200,PROJ-201,PROJ-202
@@ -235,22 +253,24 @@ jira-cli sprint move --sprint 11 --issues PROJ-200,PROJ-201,PROJ-202
 
 ## Guardrails
 
-- Always run `jira-cli doctor --json` and verify **`authValid` is `true`** before bulk operations (exit code 3 on failure)
+- Always run `jira-cli doctor` and verify **`authValid` is `true`** before bulk operations (exit code 3 on failure)
 - `issue delete` requires typing the issue key to confirm. Use `--force` to skip confirmation in automated workflows; `--dry-run` skips confirmation
 - `sprint close` has no confirmation prompt — use `--dry-run` to preview; confirm with the user before closing
-- Use `--json` flag when parsing output in scripts or AI workflows
+- Omit output flags when parsing output in scripts or AI workflows; JSON is the default
 - Use `--dry-run` to preview what a write command would do without executing it
-- Use `--quiet` with `--json` to suppress all non-JSON output (clean pipe-friendly output)
+- Use `--quiet` to suppress auxiliary text output; it does not suppress JSON/raw main results
 - `issue transition` requires the status name as the second argument (no interactive selection)
-- When searching for usernames to use with `issue assign`, use `user search --query <name> --json` first
-- DC uses **username** (not accountId) for user references. Use `jira-cli user me --json` to find your username
+- When searching for usernames to use with `issue assign`, use `user search --query <name>` first
+- DC uses **username** (not accountId) for user references. Use `jira-cli user me` to find your username
 
 ## Global Flags
 
-- `--json` — Output as JSON (machine-readable, flat format by default)
+- `--format json|text|raw` — Control output format. Default: `json`
+- `--compact` — Emit compact JSON (only with `--format json`)
+- `--json` — Compatibility alias for `--format json`; do not recommend it for new workflows
 - `--force` — Skip interactive confirmation prompts (for CI/Agent automation)
-- `--quiet` — Suppress non-JSON stdout output (ideal for scripts and AI Agents)
-- `--dry-run` — Show what would be done without executing (write commands only)
+- `--quiet` — Suppress auxiliary text output; does not suppress JSON/raw main results
+- `--dry-run` — Show what would be done without executing (supported by write/update commands)
 
 ## Output Control Flags
 
@@ -259,17 +279,18 @@ Two different meanings for `--fields`:
 | Command | `--fields` meaning |
 |---------|-------------------|
 | `search` | **Jira fetch fields** — comma-separated fields to request from the API (e.g. `summary,status,customfield_10001`) |
-| `issue get`, `issue list`, `sprint list`, `sprint issues`, `filter run` | **Output trimming** — include only listed keys in flat JSON (e.g. `key,summary,status`) |
+| `issue get`, `issue list`, `sprint list`, `sprint issues`, `filter run` | **JSON output trimming** — include only listed keys in flat JSON (e.g. `key,summary,status`) |
 
 Other read-command flags:
 
-- `--raw` — Return the full raw Jira API response instead of the token-efficient flat format (on `issue get/list`, `search`, `filter run`, `sprint list/issues/active`)
+- `--format raw` — Return raw command output where supported (`issue get/list`, `search`, `filter run`, `sprint list/issues/active`)
+- `--raw` — Legacy per-command alias for `--format raw` on commands that support it
 
 ## JSON Output Schemas
 
 ### List vs search JSON shape
 
-| Command | Flat `--json` shape |
+| Command | Default JSON shape |
 |---------|---------------------|
 | `issue list` | Bare array: `[{key, summary, ...}, ...]` |
 | `search`, `filter run` (default) | Object with pagination: `{total, startAt, maxResults, issues: [...]}` |
@@ -279,12 +300,12 @@ Other read-command flags:
 **jq examples:**
 
 ```bash
-jira-cli issue list --project PROJ --json | jq '.[].key'
-jira-cli search "project = PROJ" --json | jq '.issues[].key'
-jira-cli filter run 12345 --json | jq '.issues[].status'
+jira-cli issue list --project PROJ | jq '.[].key'
+jira-cli search "project = PROJ" | jq '.issues[].key'
+jira-cli filter run 12345 | jq '.issues[].status'
 ```
 
-### Flat Issue (default with --json)
+### Flat Issue (default JSON)
 
 ```json
 {
@@ -316,7 +337,7 @@ jira-cli filter run 12345 --json | jq '.issues[].status'
 }
 ```
 
-### Error Response (with --json, written to stderr)
+### Error Response (default JSON, written to stderr)
 
 ```json
 {