Summary

Make the SynthOrg CLI maximally configurable and user-friendly by adding 93 features across 8 categories: global output control, config system extensions, per-command flags, environment variables, help/discoverability, exit codes, auto-behavior config keys, and hint control.

Every interactive prompt gets a persistent config override so users can configure their workflow once. Hints gain categories so they're shown contextually, not repetitively.

Implementation: 3 PRs

PR 1: Infrastructure (~1,050 lines)

GlobalOpts, UI modes, exit codes, env vars, --yes, hint categories, migrate all command files.

A. Global Output Control:

• 1. --quiet / -q -- errors only, no spinners/hints/boxes
• 2. --verbose / -v -- show Docker commands, API calls, timing (stackable -vv)
• 3. --no-color -- disable ANSI; respect NO_COLOR, CLICOLOR, TERM=dumb; config key: color (always/auto/never)
• 4. --plain -- ASCII-only: no spinners, no Unicode icons, no box-drawing, no logo
• 5. --json (promote to global) -- machine-readable JSON on stdout, progress to stderr
• 6. --yes / -y -- auto-accept all interactive prompts

D. Environment Variables:

• 67. SYNTHORG_LOG_LEVEL
• 68. SYNTHORG_BACKEND_PORT
• 69. SYNTHORG_WEB_PORT
• 70. SYNTHORG_DATA_DIR
• 71. SYNTHORG_CHANNEL
• 72. SYNTHORG_IMAGE_TAG
• 73. SYNTHORG_NO_VERIFY (rename, keep SYNTHORG_SKIP_VERIFY as compat alias)
• 74. SYNTHORG_AUTO_UPDATE_CLI
• 75. SYNTHORG_AUTO_PULL
• 76. SYNTHORG_AUTO_RESTART

F. Exit Codes:

• 83. ExitError type with typed exit codes
• 84. Documented codes: 0=success, 1=runtime, 2=usage, 3=unhealthy, 4=unreachable, 10=update-available

H. Hint Categories (infrastructure only, migration in PR 3):

• 90. Categorized hint methods: HintError, HintNextStep, HintTip, HintGuidance

Infrastructure:

• GlobalOpts struct via Cobra context (replaces global vars)
• PersistentPreRunE chain for flag/env/config precedence resolution
• UI Options (plain/quiet/json/no-color modes) on existing UI type
• Migrate all 15 command files to use GetGlobalOpts

---

PR 2: Config System + Init/Start/Stop/Status/Logs Flags (~1,220 lines)

Config extensions, auto-behavior config keys, and per-command flags for simpler commands.

B. Config System Extensions:

• 7. Make backend_port settable via config set (with compose regeneration)
• 8. Make web_port settable via config set (with compose regeneration)
• 9. Make sandbox settable via config set (with compose regeneration)
• 10. Make docker_sock settable via config set (with compose regeneration)
• 11. Make image_tag settable via config set (with compose regeneration)
• 12. New config key: color (always/auto/never)
• 13. New config key: output (text/json)
• 14. New config key: timestamps (relative/iso8601)
• 15. config unset <key> -- reset to default
• 16. config list -- show all keys with resolved value and source
• 17. config path -- print config file path
• 18. config edit -- open in EDITOR

G. Auto-Behavior Config Keys:

• 85. auto_update_cli -- auto-accept CLI updates
• 86. auto_pull -- auto-accept image pulls on update
• 87. auto_restart -- auto-restart after image update
• 88. auto_apply_compose -- auto-accept compose template changes
• 89. auto_start_after_wipe -- auto-start containers post-wipe
• 90. hints config key (always/auto/never)

C. Per-Command Flags -- init:

• 19. --backend-port override
• 20. --web-port override
• 21. --sandbox / --no-sandbox
• 22. --image-tag
• 23. --channel
• 24. --log-level

C. Per-Command Flags -- start:

• 25. --no-wait -- skip health check
• 26. --timeout -- health check timeout (Go duration)
• 27. --no-pull -- skip image pull
• 28. --dry-run
• 29. --no-detach -- stream logs after start
• 30. --no-verify -- alias for --skip-verify

C. Per-Command Flags -- stop:

• 31. --timeout / -t -- graceful shutdown timeout
• 32. --volumes / -v -- also remove volumes

C. Per-Command Flags -- status:

• 33. --watch / -w -- continuous polling
• 34. --interval -- watch polling interval
• 35. --wide -- extra columns (ports, digests)
• 36. --no-trunc -- full image names/IDs
• 37. --services -- filter by service
• 38. --check -- exit code only (0=healthy, 3=degraded, 4=down)

C. Per-Command Flags -- logs:

• 39. --since -- show since time
• 40. --until -- show until time
• 41. --timestamps / -t -- prepend timestamps
• 42. --no-log-prefix -- strip service prefix

D. Additional env vars:

• 91. SYNTHORG_AUTO_UPDATE_CLI env var
• 92. SYNTHORG_AUTO_PULL env var
• 93. SYNTHORG_AUTO_RESTART env var

---

PR 3: Remaining Command Flags + Auto-Behavior Wiring + Help (~1,030 lines)

Per-command flags for complex commands, wire auto-behavior config keys, help improvements.

C. Per-Command Flags -- update:

• 43. --dry-run
• 44. --no-restart -- pull but don't restart
• 45. --timeout -- verification + health timeout
• 46. --cli-only -- only update CLI
• 47. --images-only -- only update images
• 48. --check -- check availability, exit 0/10

C. Per-Command Flags -- cleanup:

• 49. --dry-run
• 50. --all -- all SynthOrg images
• 51. --keep -- keep N previous versions

C. Per-Command Flags -- backup create:

• 52. --output / -o -- save archive to path
• 53. --timeout -- API timeout

C. Per-Command Flags -- backup list:

• 54. --limit / -n -- show N most recent
• 55. --sort -- sort order (newest/oldest/size)

C. Per-Command Flags -- backup restore:

• 56. --dry-run
• 57. --no-restart -- restore without restarting
• 58. --timeout -- API timeout

C. Per-Command Flags -- wipe:

• 59. --dry-run
• 60. --no-backup -- skip backup prompt
• 61. --keep-images

C. Per-Command Flags -- doctor:

• 62. --checks -- run specific checks only
• 63. --fix -- auto-fix detected issues

C. Per-Command Flags -- version:

• 64. --short -- version number only

C. Per-Command Flags -- uninstall:

• 65. --keep-data -- preserve data dir
• 66. --keep-images -- preserve images

Auto-Behavior Wiring (reads config keys from PR 2):

• Wire auto_update_cli into update CLI prompt
• Wire auto_pull into update image pull prompt
• Wire auto_restart into update restart prompt
• Wire auto_apply_compose into compose changes prompt
• Wire auto_start_after_wipe into post-wipe start prompt

E. Help and Discoverability:

• 77. Command groups in --help
• 78. Example: blocks on every command
• 79. Did-you-mean suggestions (Cobra SuggestionsMinimumDistance)
• 80. Footer hints on table output
• 81. Error hints (contextual suggestions on every error)
• 82. --help-all flag

H. Hint Migration:

• Migrate all 20 existing Hint() calls to categorized methods

Design Decisions

• Precedence: CLI flag > env var > config file > default
• GlobalOpts struct via Cobra context (not more global vars)
• UI Options on existing UI type (backward compatible)
• --json promoted to global persistent flag
• Destructive prompts (wipe confirmation, uninstall) have NO config override -- require --yes or interactive
• Hint categories: error (always), next-step (always), tip (once per session in auto), guidance (always-mode only)
• No persistent hint tracking -- session-level dedup only
• Auto-behavior precedence: --yes flag > config key > interactive prompt > non-interactive default