[aviatco]

📥 Pull Request

✨ Description of new changes

This pull request introduces machine-readable JSON help output for the Fabric CLI, enabling scripts and automation to programmatically discover commands, arguments, and flags. It also refactors the help system to support offline help discovery, adds a versioned schema for help responses, and updates the documentation to describe these features. Additional improvements include changes to parser setup and interactive help, and a minor fix to the configuration file location.

Machine-readable JSON help and documentation:

• Added support for machine-readable JSON help for root, group, and leaf commands, including offline help discovery and a versioned schema. (src/fabric_cli/core/fab_help.py, .changes/unreleased/added-20261026-103451.yaml) [1] [2]
• Updated documentation to describe how to use --output_format json for help and parameter discovery, including schema details and usage examples. (docs/essentials/output_format.md, docs/essentials/parameters.md) [1] [2] [3]

CLI parser and help system refactor:

• Refactored CustomArgumentParser to intercept help requests and output JSON or text help as appropriate, supporting new help request resolution and output logic. (src/fabric_cli/core/fab_parser_setup.py) [1] [2] [3] [4] [5] [6] [7] [8]
• Updated interactive mode to use the new help system for help commands, ensuring consistent behavior across CLI modes. (src/fabric_cli/core/fab_interactive.py) [1] [2]

Other improvements:

• Changed the default configuration file location to ~/.config/fab/config.json and ensured the config directory is created with restricted permissions. (src/fabric_cli/core/fab_state_config.py) [1] [2]

Link to spec
Json structure

[Copilot]

🟡 Changes recommended

JSON help can report the wrong command, omit aliases, reject valid options, ignore caller-provided streams and legacy preferences, and advertise an unsupported REPL help alias.

6 open issues

• Strip fab prefix only when present · New
• Support combined flags and long option abbreviations · New
• Accept -help in interactive help commands · New
• Preserve aliases for leaf JSON help · New
• Honor help_file for JSON help output · New
• Fallback to legacy output format preference · New

What changed in this PR

Adds machine-readable help to Fabric CLI so scripts can discover commands, arguments, and flags without authentication or command execution.

Changes:

• Introduces parser-derived JSON help with a versioned schema and shared output handling.
• Routes CLI and interactive help through the new system while deferring execution dependencies and configuration writes.
• Adds documentation and tests for metadata, format selection, offline behavior, and error handling.

File	Description
tests/​test_utils/​test_fab_ui.py	Tests help rendering, format precedence, streams, and failures.
tests/​test_parsers/​test_fab_help.py	Tests help metadata, aliases, and token boundaries.
tests/​test_main.py	Adds subprocess coverage for offline help and version output.
tests/​test_core/​test_fab_interactive.py	Tests interactive JSON and text help.
src/​fabric_cli/​utils/​fab_ui.py	Adds help format selection and shared rendering.
src/​fabric_cli/​parsers/​fab_jobs_parser.py	Adds job constraints and polling metadata.
src/​fabric_cli/​parsers/​fab_global_params.py	Preserves explicit output selectors across parser levels.
src/​fabric_cli/​parsers/​fab_fs_parser.py	Adds filesystem command guidance to help metadata.
src/​fabric_cli/​parsers/​fab_find_parser.py	Defers loading the find command implementation.
src/​fabric_cli/​parsers/​fab_extension_parser.py	Marks extension as an unsupported placeholder in help.
src/​fabric_cli/​main.py	Handles help and version before execution initialization.
src/​fabric_cli/​errors/​common.py	Adds structured help error messages.
src/​fabric_cli/​core/​fab_state_config.py	Defers configuration directory creation until writing.
src/​fabric_cli/​core/​fab_parser_setup.py	Integrates help resolution and retains parser descriptions.
src/​fabric_cli/​core/​fab_interactive.py	Routes interactive help through the parser.
src/​fabric_cli/​core/​fab_help.py	Implements help request resolution and versioned metadata.
docs/​essentials/​parameters.md	Documents JSON help invocation.
docs/​essentials/​output_format.md	Documents help examples and the response schema.
.changes/​unreleased/​added-20261026-103451.yaml	Records the JSON help feature.

_{Review effort: Balanced}

[shirasassoon]

aviatco I think some of the copilot comments are legitimate issues that should be addressed.

[Copilot]

🟡 Changes recommended

Interactive help can crash on invalid configuration, a misleading mkdir note can lead to unintended folder creation, and generated usage and examples misrepresent valid commands.

4 open issues

• Resolve help before config-dependent logging · New
• Align workspace folder behavior with discovery note · New
• Preserve interactive forms in login examples · New
• Show required flags in generated command usage · New

6 resolved since last review

• Fallback to legacy output format preference
• Honor help_file for JSON help output
• Preserve aliases for leaf JSON help
• Accept -help in interactive help commands
• Support combined flags and long option abbreviations
• Strip fab prefix only when present

_{Review effort: Balanced}

[Copilot]

🔵 Needs a closer look

Existing configuration directories may leave credentials accessible to other users, and JSON help misrepresents required flags, constraints, and defaults.

3 open issues

• Align workspace folder behavior with discovery note
• Show required flags in generated command usage
• Preserve interactive forms in login examples

4 previously missed issues

In code that hasn't changed since last review

Harden existing config directory permissions

src/​fabric_cli/​core/​fab_state_config.py:21

With an already initialized config, normal commands such as fab auth no longer tighten an existing ~/.config/fab directory to owner-only access. On POSIX, an older permissive directory can therefore leave pre-existing permissive credential files accessible to other users. Harden the directory in init_defaults(), while keeping the early offline help/version paths read-only.

JSON help reports incorrect default for --disable

src/​fabric_cli/​core/​fab_help.py:215

For job run-update --disable, argparse's store_false action has the internal default True, so JSON help advertises --disable with "default": true even though omitting the flag does not disable the schedule. Consumers can therefore infer the opposite of the actual default behavior. Omit this internal default, or represent the flag's presence semantics explicitly.

Document ln flag exclusivity and type constraint

src/​fabric_cli/​core/​fab_help.py:265

JSON help for ln marks both --target and --input optional without stating that exactly one is required, so consumers can construct commands that runtime validation rejects. Add parser-owned notes for that constraint and for the restriction that --target requires --type oneLake.

Generated usage omits required flags

src/​fabric_cli/​core/​fab_help.py:281

This usage string makes every flag optional, including flags that the parser requires. For example, JSON help for import advertises fab import <path> [flags], but that invocation always fails without --input; table load has the same problem with --file. Include required flags in the generated usage so clients can construct a valid invocation.

1 resolved since last review

• Resolve help before config-dependent logging

_{Review effort: Balanced}

[Copilot]

🔵 Needs a closer look

Potential issues in nested help handling and generated JSON metadata warrant human assessment.

1 open issue

• Show required flags in generated command usage

2 resolved since last review

• Align workspace folder behavior with discovery note
• Preserve interactive forms in login examples

_{Review effort: Balanced}

[Copilot]

🔵 Needs a closer look

Potential inconsistencies across metadata, error formatting, and CLI examples warrant human assessment.

No open issues 🎉

1 resolved since last review

• Show required flags in generated command usage

_{Review effort: Balanced}