feat: add --output/-o flag for all commands, bump to v6.2.0

Add --output <format> string flag as alternative to boolean flags (--json,
--csv, etc). Supports: json, compact-json, csv, markdown, table, raw, pretty.
Invalid values return structured error envelope with suggestions.

Also fixes publish workflow to report platform package failures instead of
silently ignoring them with || true.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: jakeschepis

.github/workflows/publish.yml

@@ -107,12 +107,20 @@ jobs:
       env:
         NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
       run: |
+        FAILED=0
         for pkg in npm/notion-cli-*/; do
           echo "Publishing $pkg..."
           cd "$pkg"
-          npm publish --access public || true
+          if ! npm publish --access public; then
+            echo "::warning::Failed to publish $pkg"
+            FAILED=1
+          fi
           cd ../..
         done
+        if [ "$FAILED" -eq 1 ]; then
+          echo "::error::One or more platform packages failed to publish. Check that the NPM_TOKEN has write access to the @coastal-programs scope and that the token owner is an org member with publish permissions."
+          exit 1
+        fi
 
     - name: Publish main wrapper package
       if: steps.check-version.outputs.version_exists == 'false'

CHANGELOG.md

@@ -7,6 +7,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [6.2.0] - 2026-03-02
+
+### Added
+- **`--output` / `-o` flag**: All commands now accept `--output <format>` (or `-o <format>`) as an alternative to boolean flags like `--json`, `--csv`, etc. Valid formats: `json`, `compact-json`, `csv`, `markdown`, `table`, `raw`, `pretty`. Invalid values return a structured error with suggestions.
+- **Platform binary packages on npm**: First publish of all 5 platform-specific packages (`@coastal-programs/notion-cli-darwin-arm64`, `-darwin-x64`, `-linux-x64`, `-linux-arm64`, `-win32-x64`). Users on supported platforms now get a native binary via npm's optional dependency resolution instead of relying on the postinstall GitHub Release fallback.
+
+### Fixed
+- **Publish workflow**: Platform package publish failures are no longer silently ignored (`|| true` removed). The workflow now reports explicit errors with guidance when platform packages fail to publish.
+
 ## [6.1.2] - 2026-03-02
 
 ### Fixed

internal/cli/commands/db.go

@@ -52,7 +52,17 @@ func resolveID(raw string) (string, error) {
 }
 
 // outputFormat returns the output.Format from command flags.
+// The --output string flag takes precedence over the boolean shorthand flags.
 func outputFormat(cmd *cobra.Command) output.Format {
+	// Check --output string flag first (takes precedence).
+	if outStr, _ := cmd.Flags().GetString("output"); outStr != "" {
+		f, err := output.ParseFormat(outStr)
+		if err == nil {
+			return f
+		}
+		// Invalid value — fall through to boolean flags.
+	}
+
 	if v, _ := cmd.Flags().GetBool("json"); v {
 		return output.FormatJSON
 	}
@@ -74,6 +84,26 @@ func outputFormat(cmd *cobra.Command) output.Format {
 	return output.FormatTable
 }
 
+// validateOutputFlag checks the --output flag value upfront and returns an error
+// for invalid values. Call this at the start of RunE handlers.
+func validateOutputFlag(cmd *cobra.Command) error {
+	outStr, _ := cmd.Flags().GetString("output")
+	if outStr == "" {
+		return nil
+	}
+	_, err := output.ParseFormat(outStr)
+	if err != nil {
+		return &clierrors.NotionCLIError{
+			Code:    clierrors.CodeInvalidRequest,
+			Message: fmt.Sprintf("Invalid --output format %q", outStr),
+			Suggestions: []string{
+				fmt.Sprintf("Valid formats: %s", strings.Join(output.ValidFormats, ", ")),
+			},
+		}
+	}
+	return nil
+}
+
 // handleError prints an error using the output printer and returns it for
 // cobra to handle the exit code.
 func handleError(cmd *cobra.Command, err error) error {
@@ -106,14 +136,38 @@ func handleError(cmd *cobra.Command, err error) error {
 }
 
 // addOutputFlags adds the shared output format flags to a command.
+// Both --output <format> and boolean shorthand flags (--json, --csv, …) are
+// supported. The --output flag takes precedence when both are provided.
+// A PreRunE hook is chained to validate the --output value early.
 func addOutputFlags(cmd *cobra.Command) {
+	cmd.Flags().StringP("output", "o", "", "Output format: json, compact-json, csv, markdown, table, raw, pretty")
 	cmd.Flags().Bool("json", false, "Output as JSON envelope")
 	cmd.Flags().Bool("compact-json", false, "Output as compact JSON (single line)")
 	cmd.Flags().Bool("raw", false, "Output raw API response without envelope")
 	cmd.Flags().Bool("csv", false, "Output as CSV")
 	cmd.Flags().Bool("markdown", false, "Output as markdown table")
 	cmd.Flags().Bool("pretty", false, "Output as pretty-printed JSON")
 	cmd.MarkFlagsMutuallyExclusive("json", "compact-json", "csv", "markdown", "raw", "pretty")
+
+	// Chain a PreRunE that validates the --output value upfront.
+	prev := cmd.PreRunE
+	cmd.PreRunE = func(c *cobra.Command, args []string) error {
+		if prev != nil {
+			if err := prev(c, args); err != nil {
+				return err
+			}
+		}
+		if err := validateOutputFlag(c); err != nil {
+			// Print the structured error envelope before returning,
+			// since SilenceErrors is set on the root command.
+			p := output.NewPrinter(output.FormatTable)
+			if cliErr, ok := err.(*clierrors.NotionCLIError); ok {
+				p.PrintError(cliErr.Code, cliErr.Message, cliErr.Details, cliErr.Suggestions)
+			}
+			return err
+		}
+		return nil
+	}
 }
 
 // maxPaginationPages is the safety limit for pagination loops.

npm/notion-cli-darwin-arm64/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coastal-programs/notion-cli-darwin-arm64",
-  "version": "6.1.2",
+  "version": "6.2.0",
   "description": "notion-cli binary for macOS ARM64 (Apple Silicon)",
   "os": ["darwin"],
   "cpu": ["arm64"],

npm/notion-cli-darwin-x64/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coastal-programs/notion-cli-darwin-x64",
-  "version": "6.1.2",
+  "version": "6.2.0",
   "description": "notion-cli binary for macOS x64 (Intel)",
   "os": ["darwin"],
   "cpu": ["x64"],

npm/notion-cli-linux-arm64/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coastal-programs/notion-cli-linux-arm64",
-  "version": "6.1.2",
+  "version": "6.2.0",
   "description": "notion-cli binary for Linux ARM64",
   "os": ["linux"],
   "cpu": ["arm64"],

npm/notion-cli-linux-x64/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coastal-programs/notion-cli-linux-x64",
-  "version": "6.1.2",
+  "version": "6.2.0",
   "description": "notion-cli binary for Linux x64",
   "os": ["linux"],
   "cpu": ["x64"],

npm/notion-cli-win32-x64/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coastal-programs/notion-cli-win32-x64",
-  "version": "6.1.2",
+  "version": "6.2.0",
   "description": "notion-cli binary for Windows x64",
   "os": ["win32"],
   "cpu": ["x64"],

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coastal-programs/notion-cli",
-  "version": "6.1.2",
+  "version": "6.2.0",
   "description": "Unofficial Notion CLI optimized for automation and AI agents. Single-binary Go implementation with intelligent caching, retry logic, structured error handling.",
   "author": "Jake Schepis <jake@coastalprograms.com>",
   "bin": {
@@ -24,11 +24,11 @@
     "release": "make release"
   },
   "optionalDependencies": {
-    "@coastal-programs/notion-cli-darwin-arm64": "6.1.2",
-    "@coastal-programs/notion-cli-darwin-x64": "6.1.2",
-    "@coastal-programs/notion-cli-linux-x64": "6.1.2",
-    "@coastal-programs/notion-cli-linux-arm64": "6.1.2",
-    "@coastal-programs/notion-cli-win32-x64": "6.1.2"
+    "@coastal-programs/notion-cli-darwin-arm64": "6.2.0",
+    "@coastal-programs/notion-cli-darwin-x64": "6.2.0",
+    "@coastal-programs/notion-cli-linux-x64": "6.2.0",
+    "@coastal-programs/notion-cli-linux-arm64": "6.2.0",
+    "@coastal-programs/notion-cli-win32-x64": "6.2.0"
   },
   "engines": {
     "node": ">=18.0.0"

pkg/output/output.go

@@ -6,6 +6,7 @@ import (
 	"io"
 	"os"
 	"sort"
+	"strings"
 	"time"
 )
 
@@ -22,6 +23,31 @@ const (
 	FormatPretty      Format = "pretty"
 )
 
+// ValidFormats lists all accepted values for the --output flag.
+var ValidFormats = []string{"json", "compact-json", "raw", "table", "csv", "markdown", "pretty"}
+
+// ParseFormat converts a string to a Format, returning an error for unknown values.
+func ParseFormat(s string) (Format, error) {
+	switch strings.ToLower(strings.TrimSpace(s)) {
+	case "json":
+		return FormatJSON, nil
+	case "compact-json":
+		return FormatCompactJSON, nil
+	case "raw":
+		return FormatRaw, nil
+	case "table":
+		return FormatTable, nil
+	case "csv":
+		return FormatCSV, nil
+	case "markdown":
+		return FormatMarkdown, nil
+	case "pretty":
+		return FormatPretty, nil
+	default:
+		return "", fmt.Errorf("unknown output format %q (valid: %s)", s, strings.Join(ValidFormats, ", "))
+	}
+}
+
 // Printer handles formatted output for CLI commands.
 type Printer struct {
 	Format    Format