@fatecannotbealtered-/jira-cli 1.0.5 → 1.0.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/CHANGELOG.md +20 -1
  2. package/README.md +65 -33
  3. package/package.json +1 -1
  4. package/scripts/run.js +7 -1
  5. package/skills/jira-cli/SKILL.md +115 -96
package/CHANGELOG.md CHANGED
@@ -7,6 +7,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
7
7
 
8
8
  ## [Unreleased]
9
9
 
10
+ ## [1.0.6] - 2026-06-05
11
+
12
+ ### Added
13
+
14
+ - **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.
15
+ - **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.
16
+
17
+ ### Changed
18
+
19
+ - **Agent-friendly defaults** — commands now emit stable JSON by default, while `--json` remains a compatibility alias for `--format json`.
20
+ - **Reference output** — `jira-cli reference` now defaults to structured JSON; use `jira-cli --format text reference` for the Markdown command reference.
21
+ - **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.
22
+
23
+ ### Fixed
24
+
25
+ - **Structured argument errors** — Cobra argument validation errors now return machine-readable JSON by default instead of plain text.
26
+ - **Clean JSON stdout** — interactive prompts and cancellation/error paths no longer pollute JSON success output.
27
+
10
28
  ## [1.0.5] - 2026-06-02
11
29
 
12
30
  ### Added
@@ -119,7 +137,8 @@ Initial release of jira-cli for Jira Data Center.
119
137
  - SKILL.md with JSON output schemas, error codes, exit codes, and complete flag reference.
120
138
  - GitHub PR template for contributors.
121
139
 
122
- [Unreleased]: https://github.com/fatecannotbealtered/jira-cli/compare/v1.0.5...HEAD
140
+ [Unreleased]: https://github.com/fatecannotbealtered/jira-cli/compare/v1.0.6...HEAD
141
+ [1.0.6]: https://github.com/fatecannotbealtered/jira-cli/compare/v1.0.5...v1.0.6
123
142
  [1.0.5]: https://github.com/fatecannotbealtered/jira-cli/compare/v1.0.4...v1.0.5
124
143
  [1.0.4]: https://github.com/fatecannotbealtered/jira-cli/compare/v1.0.3...v1.0.4
125
144
  [1.0.3]: https://github.com/fatecannotbealtered/jira-cli/compare/v1.0.2...v1.0.3
package/README.md CHANGED
@@ -11,7 +11,7 @@ Full-featured Jira Data Center CLI for humans and AI Agents. Manage issues, spri
11
11
 
12
12
  Built with Go. Single static binary (small dependency footprint via `go.mod`). No separate runtime to install.
13
13
 
14
- [Installation](#installation) · [Authentication](#authentication) · [Commands](#commands) · [JSON Output](#json-output) · [Security](#security) · [Contributing](#contributing) · [Disclaimer](#disclaimer)
14
+ [Installation](#installation) · [Updating](#updating) · [Authentication](#authentication) · [Commands](#commands) · [Output Formats](#output-formats) · [Security](#security) · [Contributing](#contributing) · [Disclaimer](#disclaimer)
15
15
 
16
16
  ## Disclaimer
17
17
 
@@ -22,12 +22,13 @@ This project is shared for **personal learning, research, and everyday productiv
22
22
  | Capability | Description |
23
23
  |---|---|
24
24
  | 🎯 **Complete Coverage** | Issues, Sprints, Boards, Epics, Projects, Users, Filters |
25
- | 🤖 **AI Friendly** | `--json` flat output (token-efficient), `--quiet`, `--dry-run`, `--force`, `--fields`, `--raw` |
25
+ | 🤖 **AI Friendly** | JSON by default, `--format json\|text\|raw`, `--compact`, `--quiet`, `--dry-run`, `--force`, `--fields` |
26
26
  | ⚡ **Single Binary** | Download and run; no JVM/Node required for the CLI itself |
27
27
  | 🔄 **Smart Retry** | Auto-retry on 429 rate limits and 5xx errors with exponential backoff |
28
28
  | 🌈 **Beautiful Output** | Colored tables with CJK character support |
29
29
  | 🔍 **Powerful Search** | Full JQL support with auto-pagination |
30
30
  | 🔧 **Custom Fields** | Set custom fields during create and edit |
31
+ | ⬆️ **Safe Update** | Built-in release checks, checksum verification, package-manager guardrails |
31
32
  | 🔐 **PAT Auth** | Bearer token authentication (Personal Access Token) |
32
33
  | 🌐 **Env Vars** | `JIRA_HOST` and `JIRA_TOKEN` override config file for CI/Agent use |
33
34
  | 📋 **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
39
40
  Copy the block below to your agent (or run it yourself):
40
41
 
41
42
  ```bash
42
- # Please install jira-cli and use it for all Jira DC operations going forward (always pass --json).
43
+ # Please install jira-cli and use it for all Jira DC operations going forward.
44
+ # Machine-readable JSON is the default; use --format text only for human-readable output.
43
45
  # Install CLI (requires curl on PATH — used to download the binary)
44
46
  npm install -g @fatecannotbealtered-/jira-cli
45
47
 
@@ -48,7 +50,7 @@ npx skills add fatecannotbealtered/jira-cli -y -g
48
50
 
49
51
  # Login and verify
50
52
  jira-cli login
51
- jira-cli doctor --json
53
+ jira-cli doctor
52
54
  ```
53
55
 
54
56
  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
63
65
 
64
66
  Download from [GitHub Releases](https://github.com/fatecannotbealtered/jira-cli/releases) and add to your PATH.
65
67
 
68
+ ## Updating
69
+
70
+ ```bash
71
+ jira-cli update --check # check latest GitHub Release
72
+ jira-cli update # update a standalone binary
73
+ jira-cli update --version v1.2.3 # install a specific release
74
+ ```
75
+
76
+ `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:
77
+
78
+ ```bash
79
+ npm install -g @fatecannotbealtered-/jira-cli@latest
80
+ ```
81
+
82
+ Use `--dry-run` to preview and `--force` only when intentionally replacing the binary in place.
83
+
66
84
  ## Authentication
67
85
 
68
86
  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
92
110
  ```bash
93
111
  export JIRA_HOST=https://jira.company.com
94
112
  export JIRA_TOKEN=<your-personal-access-token>
95
- jira-cli doctor --json # verify authValid is true
113
+ jira-cli doctor # verify authValid is true
96
114
  ```
97
115
 
98
116
  ### Generating a PAT
@@ -117,7 +135,7 @@ jira-cli issue create --project PROJ --summary "Sized story" --field "Story Poin
117
135
  jira-cli issue edit PROJ-123 --priority High --assignee me
118
136
  jira-cli issue edit PROJ-123 --field "Story Points=8" --field "Team=Backend"
119
137
  jira-cli issue delete PROJ-123 --force # --force skips confirmation prompt
120
- jira-cli issue delete PROJ-123 --dry-run --json # preview delete (no confirmation prompt)
138
+ jira-cli issue delete PROJ-123 --dry-run # preview delete (no confirmation prompt)
121
139
 
122
140
  # Clone
123
141
  jira-cli issue clone PROJ-123
@@ -200,49 +218,60 @@ jira-cli user search --query "john"
200
218
  jira-cli user me
201
219
  jira-cli filter list
202
220
  jira-cli filter run <filterId>
203
- jira-cli filter run <filterId> --json --fields key,summary,status
204
- jira-cli filter run <filterId> --json --raw
221
+ jira-cli filter run <filterId> --fields key,summary,status
222
+ jira-cli --format raw filter run <filterId>
205
223
  ```
206
224
 
207
- ## JSON Output
225
+ ## Output Formats
226
+
227
+ `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:
228
+
229
+ - `json` is the default. Success JSON goes to stdout; error JSON goes to stderr.
230
+ - `text` is for human-readable summaries, tables, colors, diff/log text, and prompts.
231
+ - `raw` is for unwrapped raw command results where supported. Unsupported commands return an argument error instead of silently downgrading.
208
232
 
209
- 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.
233
+ `--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`.
210
234
 
211
- By default, issue and sprint data is returned in a **flat, token-efficient format** (ideal for AI Agents):
235
+ `--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.
236
+
237
+ By default, issue and sprint data is returned in a **flat, token-efficient JSON format** (ideal for AI Agents):
212
238
 
213
239
  ```bash
214
240
  # Flat JSON (default) — minimal fields, low token cost
215
- jira-cli issue get PROJ-123 --json
216
- jira-cli search "project = PROJ" --json | jq '.issues[].key'
241
+ jira-cli issue get PROJ-123
242
+ jira-cli search "project = PROJ" | jq '.issues[].key'
217
243
 
218
244
  # issue list returns a bare array; search wraps issues in pagination metadata
219
245
  # filter run with --fields also returns a bare trimmed array
220
- jira-cli issue list --project PROJ --json | jq '.[].key'
221
- jira-cli search "project = PROJ" --json | jq '.issues[].key'
222
- jira-cli filter run 12345 --json --fields key,summary | jq '.[].key'
246
+ jira-cli issue list --project PROJ | jq '.[].key'
247
+ jira-cli search "project = PROJ" | jq '.issues[].key'
248
+ jira-cli filter run 12345 --fields key,summary | jq '.[].key'
223
249
 
224
250
  # Trim flat JSON output (issue get / issue list / sprint / filter run)
225
- jira-cli issue get PROJ-123 --json --fields key,summary,status,assignee
251
+ jira-cli issue get PROJ-123 --fields key,summary,status,assignee
226
252
 
227
253
  # search --fields controls which fields Jira fetches (API request), not output trimming
228
- jira-cli search "project = PROJ" --fields summary,status,customfield_10001 --json
254
+ jira-cli search "project = PROJ" --fields summary,status,customfield_10001
229
255
 
230
256
  # Raw Jira API response (full nested structure)
231
- jira-cli issue get PROJ-123 --json --raw
257
+ jira-cli --format raw issue get PROJ-123
258
+
259
+ # Human-readable output
260
+ jira-cli --format text issue get PROJ-123
232
261
 
233
- # Clean output for scripts (suppress all non-JSON noise on stdout)
234
- jira-cli issue get PROJ-123 --json --quiet
262
+ # Compact JSON for logs or pipes
263
+ jira-cli --compact issue get PROJ-123
235
264
 
236
265
  # Preview destructive operations without executing
237
- jira-cli issue delete PROJ-123 --dry-run --json
266
+ jira-cli issue delete PROJ-123 --dry-run
238
267
  ```
239
268
 
240
269
  ### Verify connectivity (`doctor`)
241
270
 
242
- When using `--json`, check the `authValid` field (exit code 3 on auth/config failure):
271
+ With the default JSON output, check the `authValid` field (exit code 3 on auth/config failure):
243
272
 
244
273
  ```bash
245
- jira-cli doctor --json | jq '.authValid' # must be true
274
+ jira-cli doctor | jq '.authValid' # must be true
246
275
  ```
247
276
 
248
277
  Error responses (stderr) include machine-readable error codes and actionable hints:
@@ -258,7 +287,7 @@ Error responses (stderr) include machine-readable error codes and actionable hin
258
287
 
259
288
  Set `NO_COLOR=1` to disable colored output (useful in CI/CD).
260
289
 
261
- Run `jira-cli reference` to get a complete listing of all commands and flags in structured markdown.
290
+ 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.
262
291
 
263
292
  ## Environment Variables
264
293
 
@@ -286,19 +315,21 @@ Credentials stored at `~/.jira-cli/config.json` (permissions: 0600):
286
315
 
287
316
  | Flag | Description |
288
317
  |---|---|
289
- | `--json` | Output as JSON (flat format by default; use `--raw` for full Jira response) |
318
+ | `--format json\|text\|raw` | Control output format. Default: `json` |
319
+ | `--compact` | Emit compact JSON (only with `--format json`) |
320
+ | `--json` | Compatibility alias for `--format json`; not recommended for new scripts |
290
321
  | `--force` | Skip interactive confirmation prompts |
291
- | `--quiet` | Suppress non-JSON stdout output (for scripts and AI Agents) |
292
- | `--dry-run` | Show what would be done without executing (write commands only) |
322
+ | `--quiet` | Suppress auxiliary text output; does not suppress JSON/raw main results |
323
+ | `--dry-run` | Show what would be done without executing (supported by write/update commands) |
293
324
 
294
325
  ### Per-command flags
295
326
 
296
327
  | Flag | Commands | Description |
297
328
  |---|---|---|
298
- | `--raw` | `issue get`, `issue list`, `search`, `filter run`, `sprint list`, `sprint issues`, `sprint active` | Return raw Jira API response instead of flat format |
299
- | `--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`) |
300
- | `--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 |
301
- | `--out` | `issue attachments` | Download attachments into this directory instead of listing (default cwd via the dir you pass); with `--json` prints `{id, filename, path, mimeType}` |
329
+ | `--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 |
330
+ | `--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`) |
331
+ | `--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 |
332
+ | `--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}` |
302
333
  | `--id` | `issue attachments` | With `--out`, download only the attachment with this ID (exit code 4 if not found) |
303
334
 
304
335
  ## Troubleshooting
@@ -322,7 +353,7 @@ Credentials stored at `~/.jira-cli/config.json` (permissions: 0600):
322
353
  - No credentials are logged or transmitted to third parties
323
354
  - Environment variables `JIRA_HOST` and `JIRA_TOKEN` take precedence over config file
324
355
 
325
- > **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.
356
+ > **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.
326
357
 
327
358
  For vulnerability reports, see [SECURITY.md](SECURITY.md).
328
359
 
@@ -404,6 +435,7 @@ jira-cli/
404
435
  │ ├── issue_*.go # Issue sub-commands
405
436
  │ ├── flatten.go # Flat JSON output helpers (issues, sprints)
406
437
  │ ├── reference.go # Self-documenting command reference
438
+ │ ├── update.go # GitHub Release self-update
407
439
  │ ├── sprint.go # Sprint management
408
440
  │ ├── board.go # Board operations
409
441
  │ ├── project.go # Project management
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@fatecannotbealtered-/jira-cli",
3
- "version": "1.0.5",
3
+ "version": "1.0.6",
4
4
  "description": "Full-featured Jira Data Center CLI for humans and AI Agents — manage issues, sprints, boards, epics, projects, users, and filters from your terminal",
5
5
  "keywords": [
6
6
  "jira",
package/scripts/run.js CHANGED
@@ -8,7 +8,13 @@ const ext = process.platform === "win32" ? ".exe" : "";
8
8
  const bin = path.join(__dirname, "..", "bin", "jira-cli" + ext);
9
9
 
10
10
  try {
11
- execFileSync(bin, process.argv.slice(2), { stdio: "inherit" });
11
+ execFileSync(bin, process.argv.slice(2), {
12
+ stdio: "inherit",
13
+ env: {
14
+ ...process.env,
15
+ JIRA_CLI_INSTALL_METHOD: process.env.JIRA_CLI_INSTALL_METHOD || "npm",
16
+ },
17
+ });
12
18
  } catch (e) {
13
19
  if (e.code === "ENOENT") {
14
20
  console.error("Binary not found. Run 'npm install -g @fatecannotbealtered-/jira-cli' to reinstall.");
package/skills/jira-cli/SKILL.md CHANGED
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: jira-cli
3
- 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.
3
+ 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.
4
4
  metadata: {"openclaw":{"emoji":"🎯","requires":{"bins":["jira-cli"]}}}
5
5
  ---
6
6
 
@@ -9,7 +9,8 @@ metadata: {"openclaw":{"emoji":"🎯","requires":{"bins":["jira-cli"]}}}
9
9
  Jira Data Center CLI for humans and AI Agents. Supports **Jira DC only** (self-hosted), not Jira Cloud.
10
10
 
11
11
  ```bash
12
- # Please install jira-cli and use it for all Jira DC operations going forward (always pass --json).
12
+ # Please install jira-cli and use it for all Jira DC operations going forward.
13
+ # Machine-readable JSON is the default; use --format text only for human-readable output.
13
14
  # Install CLI (requires curl on PATH)
14
15
  npm install -g @fatecannotbealtered-/jira-cli
15
16
 
@@ -18,11 +19,26 @@ npx skills add fatecannotbealtered/jira-cli -y -g
18
19
 
19
20
  # Login and verify
20
21
  jira-cli login
21
- jira-cli doctor --json
22
+ jira-cli doctor
22
23
  ```
23
24
 
24
25
  Optional: `jira-cli install-skill` → `~/.openclaw/skills`.
25
26
 
27
+ ## Updating
28
+
29
+ ```bash
30
+ jira-cli update --check # Check the latest GitHub Release
31
+ jira-cli update # Update a standalone binary after checksum verification
32
+ ```
33
+
34
+ If the CLI was installed through npm, prefer the package manager instead of in-place replacement:
35
+
36
+ ```bash
37
+ npm install -g @fatecannotbealtered-/jira-cli@latest
38
+ ```
39
+
40
+ Use `--dry-run` to preview. Use `--force` only when the user explicitly wants in-place binary replacement.
41
+
26
42
  ## Prerequisites
27
43
 
28
44
  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
31
47
  2. Ask the user for a **Personal Access Token (PAT)**. If they don't have one, guide them:
32
48
  "Log in to your Jira DC → click your profile avatar → Personal Access Tokens → Create token."
33
49
  3. Run `jira-cli login --host <URL> --token <PAT>` to save credentials.
34
- 4. Run `jira-cli doctor --json` to verify connectivity. Check that `authValid` is `true` (exit code 3 on auth/config failure).
50
+ 4. Run `jira-cli doctor` to verify connectivity. Check that `authValid` is `true` (exit code 3 on auth/config failure).
35
51
 
36
52
  **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.
37
53
 
38
- **Always use `--json` flag when parsing output.** Without it, output is human-formatted and not suitable for programmatic use.
54
+ **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.
39
55
 
40
- **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.
56
+ **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.
41
57
 
42
58
  ## Safety
43
59
 
44
60
  - **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.
45
61
  - **`issue delete --dry-run` skips confirmation** — dry-run is evaluated before the confirmation prompt.
46
- - **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`.
62
+ - **Use `--dry-run` before write operations** to preview what will happen without executing. Example: `issue create --project PROJ --summary "test" --type Task --dry-run`.
47
63
  - **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.
48
64
  - All write operations are recorded in `~/.jira-cli/audit/` for traceability.
49
65
 
@@ -51,34 +67,34 @@ Before using any command, authenticate with a Jira DC instance. Follow these ste
51
67
 
52
68
  ```bash
53
69
  # View issues (flat JSON by default — token-efficient)
54
- jira-cli issue get PROJ-123 --json
55
- jira-cli issue get PROJ-123 --json --fields key,summary,status,assignee # Output trimming (flat JSON)
56
- jira-cli issue get PROJ-123 --json --raw # Full Jira API response
57
- jira-cli issue list --project PROJ --json # Returns bare array of flat issues
58
- jira-cli issue list --project PROJ --json --fields key,summary,status # Trimmed array
70
+ jira-cli issue get PROJ-123
71
+ jira-cli issue get PROJ-123 --fields key,summary,status,assignee # Output trimming (flat JSON)
72
+ jira-cli --format raw issue get PROJ-123 # Full Jira API response
73
+ jira-cli issue list --project PROJ # Returns bare array of flat issues
74
+ jira-cli issue list --project PROJ --fields key,summary,status # Trimmed array
59
75
 
60
76
  # Create and edit
61
- jira-cli issue create --project PROJ --summary "Fix login bug" --type Bug --json
62
- jira-cli issue create --project PROJ --summary "New feature" --type Story --assignee me --priority High --json
63
- jira-cli issue create --project PROJ --summary "Sized story" --type Story --field "Story Points=5" --json
77
+ jira-cli issue create --project PROJ --summary "Fix login bug" --type Bug
78
+ jira-cli issue create --project PROJ --summary "New feature" --type Story --assignee me --priority High
79
+ jira-cli issue create --project PROJ --summary "Sized story" --type Story --field "Story Points=5"
64
80
  jira-cli issue edit PROJ-123 --summary "Updated summary" --priority Medium
65
81
  jira-cli issue edit PROJ-123 --field "Story Points=8" --field "Team=Backend"
66
82
  jira-cli issue delete PROJ-123 --force # Skip confirmation prompt
67
- jira-cli issue delete PROJ-123 --dry-run --json # Preview delete (no confirmation prompt)
83
+ jira-cli issue delete PROJ-123 --dry-run # Preview delete (no confirmation prompt)
68
84
 
69
85
  # Clone an issue
70
- jira-cli issue clone PROJ-123 --json # Clone with default summary
71
- jira-cli issue clone PROJ-123 --summary "New title" --json # Clone with custom summary
72
- jira-cli issue clone PROJ-123 --with-links --json # Clone with issue links
86
+ jira-cli issue clone PROJ-123 # Clone with default summary
87
+ jira-cli issue clone PROJ-123 --summary "New title" # Clone with custom summary
88
+ jira-cli issue clone PROJ-123 --with-links # Clone with issue links
73
89
 
74
90
  # Status transitions
75
- jira-cli issue transitions PROJ-123 --json # List available transitions
91
+ jira-cli issue transitions PROJ-123 # List available transitions
76
92
  jira-cli issue transition PROJ-123 "In Progress" # Transition to status (name required)
77
- jira-cli issue transition PROJ-123 "Done" --json
93
+ jira-cli issue transition PROJ-123 "Done"
78
94
 
79
95
  # Bulk transition
80
- jira-cli issue bulk-transition "Done" --issues PROJ-1,PROJ-2,PROJ-3 --json
81
- jira-cli issue bulk-transition "In Progress" --jql "project = PROJ AND sprint = 10 AND status = 'To Do'" --json
96
+ jira-cli issue bulk-transition "Done" --issues PROJ-1,PROJ-2,PROJ-3
97
+ jira-cli issue bulk-transition "In Progress" --jql "project = PROJ AND sprint = 10 AND status = 'To Do'"
82
98
 
83
99
  # Assignment and watching
84
100
  jira-cli issue assign PROJ-123 me # Assign to current user
@@ -86,31 +102,31 @@ jira-cli issue assign PROJ-123 johndoe # Assign by username (DC use
86
102
  jira-cli issue unassign PROJ-123
87
103
  jira-cli issue watch PROJ-123
88
104
  jira-cli issue unwatch PROJ-123
89
- jira-cli issue watchers PROJ-123 --json
105
+ jira-cli issue watchers PROJ-123
90
106
  jira-cli issue vote PROJ-123
91
107
  jira-cli issue unvote PROJ-123
92
108
 
93
109
  # Comments
94
- jira-cli issue comment add PROJ-123 --body "Fixed in PR #42" --json
95
- jira-cli issue comment list PROJ-123 --json
110
+ jira-cli issue comment add PROJ-123 --body "Fixed in PR #42"
111
+ jira-cli issue comment list PROJ-123
96
112
  jira-cli issue comment delete PROJ-123 --id <commentId>
97
113
 
98
114
  # Worklogs
99
- jira-cli issue worklog add PROJ-123 --time 2h --comment "Debugging session" --json
115
+ jira-cli issue worklog add PROJ-123 --time 2h --comment "Debugging session"
100
116
  jira-cli issue worklog add PROJ-123 --time 1h30m --started "2024-01-15T10:00:00.000+0000"
101
- jira-cli issue worklog list PROJ-123 --json
117
+ jira-cli issue worklog list PROJ-123
102
118
 
103
119
  # Links
104
- jira-cli issue link-types --json # List available link types
120
+ jira-cli issue link-types # List available link types
105
121
  jira-cli issue link PROJ-123 --to PROJ-456 --type "blocks"
106
122
  jira-cli issue unlink <linkId>
107
123
  jira-cli issue remote-link PROJ-123 --url https://pr.url --title "PR #42"
108
- jira-cli issue remote-links PROJ-123 --json
124
+ jira-cli issue remote-links PROJ-123
109
125
 
110
126
  # Attachments
111
127
  jira-cli issue attach PROJ-123 --file ./screenshot.png
112
- jira-cli issue attachments PROJ-123 --json # list metadata (incl. content URL)
113
- jira-cli issue attachments PROJ-123 --out ./dl --json # download all -> [{id,filename,path,mimeType}]
128
+ jira-cli issue attachments PROJ-123 # list metadata (incl. content URL)
129
+ jira-cli issue attachments PROJ-123 --out ./dl # download all -> [{id,filename,path,mimeType}]
114
130
  jira-cli issue attachments PROJ-123 --out ./dl --id 4609477 # download a single attachment by ID
115
131
  ```
116
132
 
@@ -118,82 +134,82 @@ jira-cli issue attachments PROJ-123 --out ./dl --id 4609477 # download a si
118
134
 
119
135
  ```bash
120
136
  # Basic search
121
- jira-cli search "assignee = currentUser() AND status != Done" --json
122
- jira-cli search "project = PROJ AND sprint in openSprints()" --json
137
+ jira-cli search "assignee = currentUser() AND status != Done"
138
+ jira-cli search "project = PROJ AND sprint in openSprints()"
123
139
 
124
140
  # Advanced options
125
- jira-cli search "project = PROJ" --limit 100 --json
126
- jira-cli search "project = PROJ" --all --json # Fetch ALL results (auto-paginate)
141
+ jira-cli search "project = PROJ" --limit 100
142
+ jira-cli search "project = PROJ" --all # Fetch ALL results (auto-paginate)
127
143
  jira-cli search "project = PROJ" --count # Only show total count
128
- jira-cli search "project = PROJ" --order-by updated --json
129
- jira-cli search "type = Bug AND priority = High" --fields summary,status,customfield_10001 --json # Jira fetch fields (API request)
144
+ jira-cli search "project = PROJ" --order-by updated
145
+ jira-cli search "type = Bug AND priority = High" --fields summary,status,customfield_10001 # Jira fetch fields (API request)
130
146
  ```
131
147
 
132
148
  ## Sprint Management
133
149
 
134
150
  ```bash
135
- jira-cli board list --json # Find board IDs first
136
- jira-cli sprint list --board 42 --json
137
- jira-cli sprint list --board 42 --state active --json
138
- jira-cli sprint active --board 42 --json # Active sprint + issues
139
- jira-cli sprint issues --sprint 10 --json
140
- jira-cli sprint create --board 42 --name "Sprint 5" --start-date 2024-02-01 --end-date 2024-02-14 --json
151
+ jira-cli board list # Find board IDs first
152
+ jira-cli sprint list --board 42
153
+ jira-cli sprint list --board 42 --state active
154
+ jira-cli sprint active --board 42 # Active sprint + issues
155
+ jira-cli sprint issues --sprint 10
156
+ jira-cli sprint create --board 42 --name "Sprint 5" --start-date 2024-02-01 --end-date 2024-02-14
141
157
  jira-cli sprint update --sprint 10 --goal "Complete payment refactor"
142
158
  jira-cli sprint move --sprint 10 --issues PROJ-123,PROJ-124,PROJ-125
143
- jira-cli sprint close --sprint 10 --json
144
- jira-cli sprint close --sprint 10 --dry-run --json # Preview without closing (no confirmation prompt)
159
+ jira-cli sprint close --sprint 10
160
+ jira-cli sprint close --sprint 10 --dry-run # Preview without closing (no confirmation prompt)
145
161
  ```
146
162
 
147
163
  ## Board & Backlog
148
164
 
149
165
  ```bash
150
- jira-cli board list --json
151
- jira-cli board list --project PROJ --type scrum --json
152
- jira-cli board get --board 42 --json
153
- jira-cli board backlog --board 42 --json
154
- jira-cli board epics --board 42 --json
155
- jira-cli board sprints --board 42 --state active --json
166
+ jira-cli board list
167
+ jira-cli board list --project PROJ --type scrum
168
+ jira-cli board get --board 42
169
+ jira-cli board backlog --board 42
170
+ jira-cli board epics --board 42
171
+ jira-cli board sprints --board 42 --state active
156
172
  ```
157
173
 
158
174
  ## Epic Management
159
175
 
160
176
  ```bash
161
- jira-cli epic list --board 42 --json
162
- jira-cli epic list --board 42 --done --json # Completed epics only
163
- jira-cli epic issues PROJ-1 --board 42 --json
177
+ jira-cli epic list --board 42
178
+ jira-cli epic list --board 42 --done # Completed epics only
179
+ jira-cli epic issues PROJ-1 --board 42
164
180
  ```
165
181
 
166
182
  ## Project Management
167
183
 
168
184
  ```bash
169
- jira-cli project list --json
170
- jira-cli project list --type software --json
171
- jira-cli project get PROJ --json
172
- jira-cli project components PROJ --json
173
- jira-cli project versions PROJ --json
174
- jira-cli project versions PROJ --unreleased --json
175
- jira-cli project issue-types PROJ --json
176
- jira-cli project fields --json # List all fields (system + custom)
177
- jira-cli project fields --custom --json # List custom fields only
185
+ jira-cli project list
186
+ jira-cli project list --type software
187
+ jira-cli project get PROJ
188
+ jira-cli project components PROJ
189
+ jira-cli project versions PROJ
190
+ jira-cli project versions PROJ --unreleased
191
+ jira-cli project issue-types PROJ
192
+ jira-cli project fields # List all fields (system + custom)
193
+ jira-cli project fields --custom # List custom fields only
178
194
  ```
179
195
 
180
196
  ## User Search
181
197
 
182
198
  ```bash
183
- jira-cli user me --json # Current user info
184
- jira-cli user search --query "john" --json
185
- jira-cli user search --query "john" --assignable --project PROJ --json
199
+ jira-cli user me # Current user info
200
+ jira-cli user search --query "john"
201
+ jira-cli user search --query "john" --assignable --project PROJ
186
202
  ```
187
203
 
188
204
  ## Filters
189
205
 
190
206
  ```bash
191
- jira-cli filter list --json
192
- jira-cli filter get <filterId> --json
193
- jira-cli filter create --name "My Bugs" --jql "assignee = me AND type = Bug" --json
194
- jira-cli filter run <filterId> --json
195
- jira-cli filter run <filterId> --json --fields key,summary,status # Output trimming
196
- jira-cli filter run <filterId> --json --raw # Raw Jira search response
207
+ jira-cli filter list
208
+ jira-cli filter get <filterId>
209
+ jira-cli filter create --name "My Bugs" --jql "assignee = me AND type = Bug"
210
+ jira-cli filter run <filterId>
211
+ jira-cli filter run <filterId> --fields key,summary,status # Output trimming
212
+ jira-cli --format raw filter run <filterId> # Raw Jira search response
197
213
  jira-cli filter delete <filterId>
198
214
  ```
199
215
 
@@ -202,13 +218,13 @@ jira-cli filter delete <filterId>
202
218
  ### Find and update an issue
203
219
  ```bash
204
220
  # 1. Search for issues
205
- jira-cli search "project = PROJ AND assignee = me AND status = 'In Progress'" --json
221
+ jira-cli search "project = PROJ AND assignee = me AND status = 'In Progress'"
206
222
 
207
223
  # 2. Get issue details
208
- jira-cli issue get PROJ-123 --json
224
+ jira-cli issue get PROJ-123
209
225
 
210
226
  # 3. Check available transitions
211
- jira-cli issue transitions PROJ-123 --json
227
+ jira-cli issue transitions PROJ-123
212
228
 
213
229
  # 4. Transition to Done
214
230
  jira-cli issue transition PROJ-123 "Done"
@@ -220,16 +236,16 @@ jira-cli issue comment add PROJ-123 --body "Completed and deployed to staging"
220
236
  ### Sprint planning workflow
221
237
  ```bash
222
238
  # 1. Find the board
223
- jira-cli board list --json
239
+ jira-cli board list
224
240
 
225
241
  # 2. Check active sprint
226
- jira-cli sprint active --board 42 --json
242
+ jira-cli sprint active --board 42
227
243
 
228
244
  # 3. View backlog
229
- jira-cli board backlog --board 42 --json
245
+ jira-cli board backlog --board 42
230
246
 
231
247
  # 4. Create next sprint
232
- jira-cli sprint create --board 42 --name "Sprint 6" --start-date 2024-02-15 --end-date 2024-02-28 --json
248
+ jira-cli sprint create --board 42 --name "Sprint 6" --start-date 2024-02-15 --end-date 2024-02-28
233
249
 
234
250
  # 5. Move issues to sprint
235
251
  jira-cli sprint move --sprint 11 --issues PROJ-200,PROJ-201,PROJ-202
@@ -237,22 +253,24 @@ jira-cli sprint move --sprint 11 --issues PROJ-200,PROJ-201,PROJ-202
237
253
 
238
254
  ## Guardrails
239
255
 
240
- - Always run `jira-cli doctor --json` and verify **`authValid` is `true`** before bulk operations (exit code 3 on failure)
256
+ - Always run `jira-cli doctor` and verify **`authValid` is `true`** before bulk operations (exit code 3 on failure)
241
257
  - `issue delete` requires typing the issue key to confirm. Use `--force` to skip confirmation in automated workflows; `--dry-run` skips confirmation
242
258
  - `sprint close` has no confirmation prompt — use `--dry-run` to preview; confirm with the user before closing
243
- - Use `--json` flag when parsing output in scripts or AI workflows
259
+ - Omit output flags when parsing output in scripts or AI workflows; JSON is the default
244
260
  - Use `--dry-run` to preview what a write command would do without executing it
245
- - Use `--quiet` with `--json` to suppress all non-JSON output (clean pipe-friendly output)
261
+ - Use `--quiet` to suppress auxiliary text output; it does not suppress JSON/raw main results
246
262
  - `issue transition` requires the status name as the second argument (no interactive selection)
247
- - When searching for usernames to use with `issue assign`, use `user search --query <name> --json` first
248
- - DC uses **username** (not accountId) for user references. Use `jira-cli user me --json` to find your username
263
+ - When searching for usernames to use with `issue assign`, use `user search --query <name>` first
264
+ - DC uses **username** (not accountId) for user references. Use `jira-cli user me` to find your username
249
265
 
250
266
  ## Global Flags
251
267
 
252
- - `--json` — Output as JSON (machine-readable, flat format by default)
268
+ - `--format json|text|raw` — Control output format. Default: `json`
269
+ - `--compact` — Emit compact JSON (only with `--format json`)
270
+ - `--json` — Compatibility alias for `--format json`; do not recommend it for new workflows
253
271
  - `--force` — Skip interactive confirmation prompts (for CI/Agent automation)
254
- - `--quiet` — Suppress non-JSON stdout output (ideal for scripts and AI Agents)
255
- - `--dry-run` — Show what would be done without executing (write commands only)
272
+ - `--quiet` — Suppress auxiliary text output; does not suppress JSON/raw main results
273
+ - `--dry-run` — Show what would be done without executing (supported by write/update commands)
256
274
 
257
275
  ## Output Control Flags
258
276
 
@@ -261,17 +279,18 @@ Two different meanings for `--fields`:
261
279
  | Command | `--fields` meaning |
262
280
  |---------|-------------------|
263
281
  | `search` | **Jira fetch fields** — comma-separated fields to request from the API (e.g. `summary,status,customfield_10001`) |
264
- | `issue get`, `issue list`, `sprint list`, `sprint issues`, `filter run` | **Output trimming** — include only listed keys in flat JSON (e.g. `key,summary,status`) |
282
+ | `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`) |
265
283
 
266
284
  Other read-command flags:
267
285
 
268
- - `--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`)
286
+ - `--format raw` — Return raw command output where supported (`issue get/list`, `search`, `filter run`, `sprint list/issues/active`)
287
+ - `--raw` — Legacy per-command alias for `--format raw` on commands that support it
269
288
 
270
289
  ## JSON Output Schemas
271
290
 
272
291
  ### List vs search JSON shape
273
292
 
274
- | Command | Flat `--json` shape |
293
+ | Command | Default JSON shape |
275
294
  |---------|---------------------|
276
295
  | `issue list` | Bare array: `[{key, summary, ...}, ...]` |
277
296
  | `search`, `filter run` (default) | Object with pagination: `{total, startAt, maxResults, issues: [...]}` |
@@ -281,12 +300,12 @@ Other read-command flags:
281
300
  **jq examples:**
282
301
 
283
302
  ```bash
284
- jira-cli issue list --project PROJ --json | jq '.[].key'
285
- jira-cli search "project = PROJ" --json | jq '.issues[].key'
286
- jira-cli filter run 12345 --json | jq '.issues[].status'
303
+ jira-cli issue list --project PROJ | jq '.[].key'
304
+ jira-cli search "project = PROJ" | jq '.issues[].key'
305
+ jira-cli filter run 12345 | jq '.issues[].status'
287
306
  ```
288
307
 
289
- ### Flat Issue (default with --json)
308
+ ### Flat Issue (default JSON)
290
309
 
291
310
  ```json
292
311
  {
@@ -318,7 +337,7 @@ jira-cli filter run 12345 --json | jq '.issues[].status'
318
337
  }
319
338
  ```
320
339
 
321
- ### Error Response (with --json, written to stderr)
340
+ ### Error Response (default JSON, written to stderr)
322
341
 
323
342
  ```json
324
343
  {