Skip to content

Add top-level --help and --version support to the Needle CLI #29

Description

@JJordan0C

Context

needle-app uses a small manual top-level command dispatcher. The current
usage path lists the available public commands, but --help, -h, --version,
and -V currently fall through as unknown subcommands. Usage failures are
reported on stderr and exit with status 2.

The package version already exists in Cargo metadata and the binary has an
existing VERSION constant, but users cannot inspect the version directly from
the command line. Adding a standard, zero-side-effect help and version surface
would make local source inspection easier and provide a bounded first Rust
contribution.

Outcome

Add successful top-level help and version commands without changing the current
manual parser, command behavior, or pre-alpha compatibility boundary.

Scope

  • Make needle --help, needle -h, and needle help print concise top-level
    help to stdout and exit with status 0.
  • Make needle --version and needle -V print needle <package-version> to
    stdout and exit with status 0.
  • Derive the displayed version from Cargo package metadata, for example through
    env!("CARGO_PKG_VERSION"); do not introduce another hard-coded version.
    Reuse or replace the current VERSION constant as appropriate.
  • List the same public top-level commands exposed by the current usage surface,
    with a short description for each. Keep the internal
    worker digest-files utility out of general help.
  • State in the help output that Needle is a pre-alpha developer preview and that
    interfaces may change.
  • Add process-level integration tests using CARGO_BIN_EXE_needle to verify
    exit status, stdout, and stderr for every new spelling.
  • Add a brief --help and --version example to
    docs/DEVELOPER_SETUP.md.

Non-goals

  • Adding clap or another argument-parsing dependency.
  • Adding nested help for every subcommand or redesigning existing usage text.
  • Changing the behavior of an empty argument list, unknown commands, or invalid
    subcommand arguments.
  • Initializing SQLite, resolving a product data directory, checking Codex,
    starting a provider process, using the network, or changing frontend code.
  • Claiming a stable CLI or installation interface.

Acceptance criteria

  • needle --help, needle -h, and needle help produce the same bounded
    help text on stdout, write nothing to stderr, and exit successfully.
  • needle --version and needle -V produce exactly one line in the form
    needle <CARGO_PKG_VERSION>, write nothing to stderr, and exit
    successfully.
  • Help and version execution perform no profile initialization, SQLite
    write, Codex lookup, provider call, or repository mutation.
  • The help text covers every command in the current public usage surface and
    does not advertise the internal worker digest-files utility.
  • Empty input and an unknown command retain their current non-zero usage
    behavior and needle: error prefix.
  • Tests execute the built binary rather than testing only a string-rendering
    helper.
  • No new dependency is added and existing command dispatch remains
    compatible.
  • Developer setup documentation contains working help and version examples
    without presenting the CLI as stable.

Starting points

  • crates/needle-app/src/main.rsmain, run, AppError::Usage, the
    top-level command match, and VERSION.
  • crates/needle-app/tests/mcp_stdio.rs — existing process-level binary test
    using CARGO_BIN_EXE_needle.
  • Cargo.toml and crates/needle-app/Cargo.toml — package version metadata.
  • docs/DEVELOPER_SETUP.md — source-development command examples.

Validation

Build the embedded frontend before compiling needle-app from a clean
checkout, then run the focused CLI test and app regression suite:

cd crates/needle-app/web
npm ci
npm run build
cd ../../..
cargo fmt --all -- --check
cargo test --locked -p needle-app --test cli_surface
cargo test --locked -p needle-app
git diff --check

The implementation and tests must remain fully offline and must not require a
Codex installation or provider credential.

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions