fix: simplify tree output defaults

Author: danielewood

.claude/docs/architecture.md

@@ -72,7 +72,7 @@ Thin CLI layer. Each file is one Cobra command. Flag variables are package-level
 - `probe_ssh.go` — `probe ssh` subcommand. Connects without authenticating, prints banner/algorithm details, and supports `--fips-140-2` / `--fips-140-3` policy heuristics for SSH transport algorithms.
 - `policy.go` — Shared CLI flag-to-policy selection helper used by `connect` and `probe ssh`.
 - `sign.go` — Sign certificates. Parent command with `self-signed` and `csr` subcommands for creating self-signed certs and signing CSRs with a CA.
-- `tree.go` — `tree` subcommand. Renders the full Cobra command graph, including built-in commands plus local and inherited flags accepted by each command; honors the global `--json` flag with structured command/flag output.
+- `tree.go` — `tree` subcommand. Renders the full Cobra command graph with a command-focused default text view; `--flags` and `--inherited` opt into text-mode flag detail, and the global `--json` flag still returns the structured command/flag surface.
 - `ocsp.go` — Check certificate revocation status via OCSP; `--format` flag.
 - `crl.go` — Parse and inspect Certificate Revocation Lists; `--check` to verify a cert against the CRL; `--format` flag.
 - `convert.go` — Convert certificates and keys between PEM, DER, PKCS#12, JKS, and PKCS#7 formats; `--to`, `-o` flags.

CHANGELOG.md

@@ -39,6 +39,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Parse extensionless or renamed DER/PKCS#7/PKCS#12/JKS inputs during certstore ingestion instead of skipping binary crypto content based on filename extension alone ([#172])
 - Harden browser/WASM AIA and upload handling by blocking obvious internal hostnames without DNS, streaming AIA response-size enforcement before buffering, and rejecting oversized uploads before `arrayBuffer()` reads them into JS memory ([#172])
 - Stop draining oversized `tar.gz` members after the size violation is already known, treat `gh api graphql` string variables literally in `pr-comments.py`, and add JSON output support for `certkit tree --json` so the global flag matches documented behavior ([#172])
+- Make `certkit tree` default to a command-focused text view, with `--flags` and `--inherited` available when you want flag detail in text mode ([#172])
 - Encrypt private key in YAML bundle output (`.yaml`) when an export password is supplied; previously leaked plaintext key ([#167])
 - Reject malformed `ENCRYPTED PRIVATE KEY` blocks with invalid AES IV length instead of panicking ([#167])
 - Trim whitespace from web UI export password so whitespace-only input is treated as blank ([#167])

EXAMPLES.md

@@ -74,8 +74,7 @@ A practical guide to common certificate tasks. No prior TLS/SSL knowledge requir
 
 ### See the full command surface
 
-Print the actual CLI command tree, including built-in Cobra commands and the
-flags each command accepts:
+Print the actual CLI command tree, including built-in Cobra commands:
 
 ```sh
 certkit tree
@@ -84,6 +83,12 @@ certkit tree
 This is useful when you want a quick map of the CLI without hopping through
 `--help` output command by command.
 
+If you also want the flag surface, opt in explicitly:
+
+```sh
+certkit tree --flags --inherited
+```
+
 ---
 
 ## Inspecting

RALPH.md

@@ -231,3 +231,10 @@ Area: [internal/certstore/process_test.go](internal/certstore/process_test.go)
 Summary: direct unit tests of unexported algorithm-conversion helpers were too implementation-coupled for the compat parser behavior they were intended to protect.
 Source: Follow-up PR review
 Fix: Removed the helper-specific tests and asserted public-key/signature algorithm mapping through the compatibility ingestion path instead
+
+33. `tree-default-flags-noise`
+Status: fixed
+Area: [cmd/certkit/tree.go](cmd/certkit/tree.go), [cmd/certkit/cli_semantics_test.go](cmd/certkit/cli_semantics_test.go), [README.md](README.md), [EXAMPLES.md](EXAMPLES.md)
+Summary: the default `tree` output included every local and inherited flag, which made the command map harder to scan than a command-focused tree.
+Source: User feedback
+Fix: `tree` now defaults to commands-only text output, with `--flags` and `--inherited` opt-ins for text-mode flag detail; JSON output remains the detailed machine-readable surface

README.md

@@ -110,7 +110,7 @@ See [EXAMPLES.md](EXAMPLES.md) for a walkthrough of the main certificate workflo
 | `certkit sign self-signed`  | Create a self-signed certificate                        |
 | `certkit sign csr <file>`   | Sign a CSR with a CA certificate and key                |
 | `certkit scan <path>`       | Scan a directory and catalog everything found           |
-| `certkit tree`              | Print the full CLI command and flag surface as a tree   |
+| `certkit tree`              | Print the full CLI command tree                         |
 | `certkit keygen`            | Generate a new key pair (and optionally a CSR)          |
 | `certkit csr`               | Generate a CSR from a template, cert, or existing CSR   |
 | `certkit ocsp <file>`       | Check certificate revocation status via OCSP            |

cmd/certkit/cli_semantics_test.go

@@ -144,15 +144,17 @@ func TestTreeCommand(t *testing.T) {
 		}
 	})
 
-	t.Run("includes help and version flags", func(t *testing.T) {
+	t.Run("default text output omits flags", func(t *testing.T) {
 		for _, flag := range []string{"--help", "--version"} {
-			if !strings.Contains(rootOutput, flag) {
-				t.Errorf("tree output missing flag %q", flag)
+			if strings.Contains(rootOutput, flag) {
+				t.Errorf("default tree output should omit flag %q", flag)
 			}
 		}
 	})
 
-	t.Run("includes subcommand help and inherited global flags", func(t *testing.T) {
+	t.Run("includes subcommand help and inherited global flags when requested", func(t *testing.T) {
+		treeIncludeFlags = true
+		treeIncludeInherited = true
 		var bundleTree strings.Builder
 		fmt.Fprintf(&bundleTree, "%s — %s\n", bundleCmd.Name(), bundleCmd.Short)
 		printCommandTree(&bundleTree, printCommandTreeInput{cmd: bundleCmd})
@@ -173,22 +175,48 @@ func TestTreeCommand(t *testing.T) {
 	})
 
 	t.Run("prefers long flag names over shorthand pairs", func(t *testing.T) {
+		treeIncludeFlags = true
+		treeIncludeInherited = true
+		var flagsTree strings.Builder
+		printCommandTree(&flagsTree, printCommandTreeInput{cmd: rootCmd})
+		flagsOutput := flagsTree.String()
 		for _, flag := range []string{"-h, --help", "-l, --log-level", "-p, --passwords", "-v, --verbose"} {
-			if strings.Contains(rootOutput, flag) {
+			if strings.Contains(flagsOutput, flag) {
 				t.Errorf("tree output should omit shorthand pair %q", flag)
 			}
 		}
 	})
 
-	t.Run("collapses inherited flags to one summary line", func(t *testing.T) {
-		if strings.Count(rootOutput, "inherits: ") == 0 {
+	t.Run("collapses inherited flags to one summary line when requested", func(t *testing.T) {
+		treeIncludeFlags = true
+		treeIncludeInherited = true
+		var flagsTree strings.Builder
+		printCommandTree(&flagsTree, printCommandTreeInput{cmd: rootCmd})
+		flagsOutput := flagsTree.String()
+		if strings.Count(flagsOutput, "inherits: ") == 0 {
 			t.Fatal("tree output missing inherited flag summaries")
 		}
-		if strings.Count(rootOutput, "\n│   ├── --json\n")+strings.Count(rootOutput, "\n│   └── --json\n") != 0 {
+		if strings.Count(flagsOutput, "\n│   ├── --json\n")+strings.Count(flagsOutput, "\n│   └── --json\n") != 0 {
 			t.Fatal("tree output should not repeat inherited flags as standalone subcommand entries")
 		}
 	})
 
+	t.Run("includes local flags only when requested", func(t *testing.T) {
+		treeIncludeFlags = true
+		treeIncludeInherited = false
+		var flagsTree strings.Builder
+		printCommandTree(&flagsTree, printCommandTreeInput{cmd: rootCmd})
+		flagsOutput := flagsTree.String()
+		for _, flag := range []string{"--help", "--version"} {
+			if !strings.Contains(flagsOutput, flag) {
+				t.Errorf("tree output missing requested local flag %q", flag)
+			}
+		}
+		if strings.Contains(flagsOutput, "inherits: ") {
+			t.Fatal("tree output should omit inherited summaries unless requested")
+		}
+	})
+
 	t.Run("rejects arguments", func(t *testing.T) {
 		if treeCmd.Args == nil {
 			t.Fatal("treeCmd.Args is nil; expected cobra.NoArgs")

cmd/certkit/readonly_commands_test.go

@@ -72,6 +72,10 @@ type readonlyGlobals struct {
 	// inspect flags
 	inspectFormat              string
 	inspectAllowPrivateNetwork bool
+
+	// tree flags
+	treeIncludeFlags     bool
+	treeIncludeInherited bool
 }
 
 func snapshotReadonlyGlobals() readonlyGlobals {
@@ -120,6 +124,9 @@ func snapshotReadonlyGlobals() readonlyGlobals {
 
 		inspectFormat:              inspectFormat,
 		inspectAllowPrivateNetwork: inspectAllowPrivateNetwork,
+
+		treeIncludeFlags:     treeIncludeFlags,
+		treeIncludeInherited: treeIncludeInherited,
 	}
 }
 
@@ -166,6 +173,9 @@ func restoreReadonlyGlobals(g readonlyGlobals) {
 
 	inspectFormat = g.inspectFormat
 	inspectAllowPrivateNetwork = g.inspectAllowPrivateNetwork
+
+	treeIncludeFlags = g.treeIncludeFlags
+	treeIncludeInherited = g.treeIncludeInherited
 	readonlyGlobalsMu.Unlock()
 }
 

cmd/certkit/tree.go

@@ -13,11 +13,16 @@ import (
 var treeCmd = &cobra.Command{
 	Use:   "tree",
 	Short: "Display the full command tree",
-	Long:  "Display every command, subcommand, and flag in a tree layout.",
+	Long:  "Display the command and subcommand tree. Use --flags to include flag details.",
 	Args:  cobra.NoArgs,
 	RunE:  runTree,
 }
 
+var (
+	treeIncludeFlags     bool
+	treeIncludeInherited bool
+)
+
 type printCommandTreeInput struct {
 	cmd    *cobra.Command
 	prefix string
@@ -32,6 +37,8 @@ type commandTreeJSON struct {
 }
 
 func init() {
+	treeCmd.Flags().BoolVar(&treeIncludeFlags, "flags", false, "Include local flags in text tree output")
+	treeCmd.Flags().BoolVar(&treeIncludeInherited, "inherited", false, "Include inherited flags in text tree output")
 	rootCmd.AddCommand(treeCmd)
 }
 
@@ -66,7 +73,8 @@ func initTreeSurface(cmd *cobra.Command) {
 }
 
 // printCommandTree recursively prints a command and its children with
-// box-drawing connectors. Each command shows its flags indented beneath it.
+// box-drawing connectors. Flag details are opt-in so the default tree stays
+// focused on the command surface.
 func printCommandTree(b *strings.Builder, in printCommandTreeInput) {
 	cmd := in.cmd
 	prefix := in.prefix
@@ -87,23 +95,28 @@ func printCommandTree(b *strings.Builder, in printCommandTreeInput) {
 		}
 	}
 
-	total := len(localFlags) + len(visible)
-	if len(inheritedFlags) > 0 {
+	total := len(visible)
+	if treeIncludeFlags {
+		total += len(localFlags)
+	}
+	if treeIncludeInherited && len(inheritedFlags) > 0 {
 		total++
 	}
 	idx := 0
 
 	// Print local flags.
-	for _, flag := range localFlags {
-		idx++
-		connector := "├── "
-		if idx == total {
-			connector = "└── "
+	if treeIncludeFlags {
+		for _, flag := range localFlags {
+			idx++
+			connector := "├── "
+			if idx == total {
+				connector = "└── "
+			}
+			fmt.Fprintf(b, "%s%s%s\n", prefix, connector, flag)
 		}
-		fmt.Fprintf(b, "%s%s%s\n", prefix, connector, flag)
 	}
 
-	if len(inheritedFlags) > 0 {
+	if treeIncludeInherited && len(inheritedFlags) > 0 {
 		idx++
 		connector := "├── "
 		if idx == total {