Skip to content

Expand CLI help into a discoverable command and option reference #36

Description

@dapi

Problem

code-converge --help currently prints only:

usage: code-converge [flags] [config]

The command gives no way to discover:

  • available commands (config, update);
  • supported global flags;
  • configuration entry points and the primary documentation;
  • command-specific syntax.

Additionally, code-converge config --help and code-converge update --help currently fail with exit code 2, rather than presenting successful help.

The minimal root-help output was intentionally introduced by #20, but it is insufficient for interactive operators and makes normal CLI discovery depend on reading the README.

Desired outcome

Provide concise, stable, human-oriented help without loading configuration, starting a workflow, or checking for updates.

Acceptance criteria

  • code-converge -h and code-converge --help exit 0 and show:
    • root usage;
    • command synopsis for config and update;
    • a concise list of global options, grouped where helpful;
    • a pointer to the full README/configuration reference.
  • code-converge config --help exits 0 and explains its purpose and valid invocation.
  • code-converge update --help exits 0 and documents --yes / -y.
  • Help never loads project/user configuration, creates diagnostic session logs, starts Codex, or invokes self-update.
  • The help text and exit semantics are covered by focused tests and documented in the public CLI contract.
  • Machine-readable workflow output remains unaffected.

Scope notes

This changes the public CLI/stdout contract, so it should use Feature Flow rather than Small Change. The implementation should decide whether the detailed option list is generated from the flag definitions to prevent drift.

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions