feat: add --version / -V flag

[canyugs]

What problem does this solve?

Running openab --version currently fails with failed to read --version: No such file or directory. There is no way to check which version of openab is installed without inspecting the binary directly or checking the Helm chart. This makes debugging deployment mismatches difficult.

Closes #

Discord Discussion URL: https://discord.com/channels/1491295327620169908/1491365150664560881/1493789779999985785

At a Glance

User runs: openab --version  (or -V)
                │
                ▼
        ┌───────────────┐
        │  main.rs      │
        │  arg check    │  ──► prints "openab 0.7.3" → exit 0
        └───────┬───────┘
                │ (no version flag)
                ▼
        normal startup flow

Prior Art & Industry Research

OpenClaw:
OpenClaw (TypeScript / Commander.js) handles this via custom pre-parse detection in src/cli/program/help.ts — checks for -V, --version, and a root-level -v alias before Commander parses arguments. The version string is resolved dynamically from package.json with fallbacks to a build-time __OPENCLAW_VERSION__ global. Output format: OpenClaw 2026.4.14-beta.1 (abc1234) including git commit hash.

Hermes Agent:
Hermes Agent (Python / argparse) registers -V / --version as action="store_true" on the main parser, plus a dedicated hermes version subcommand. Version is hardcoded in hermes_cli/__init__.py. Output: Hermes Agent v0.9.0 (2026.4.13) with additional Python version and dependency info.

Comparison:

	OpenClaw	Hermes Agent	This PR
Flag	-V, --version, -v	-V, --version	-V, --version
Version source	Dynamic (package.json)	Hardcoded	env!("CARGO_PKG_VERSION") (Cargo.toml)
Output	Name X.Y.Z (git-hash)	Name vX.Y.Z (date)	openab X.Y.Z
Extra info	git commit hash	Python ver + deps	none

Proposed Solution

Use clap's built-in version support via #[command(name = "openab", version)]. clap reads the version from Cargo.toml at compile time via env!("CARGO_PKG_VERSION") and automatically handles --version and -V.

Change: 1 word added to src/main.rs, zero new dependencies.

#[derive(Parser)]
#[command(name = "openab", version)]

Why This Approach?

clap already in the project. main already has clap 4 with #[derive(Parser)] and subcommands — using #[command(version)] is the idiomatic 1-line solution with no new dependencies.

env!("CARGO_PKG_VERSION") over hardcoding. Like OpenClaw's package.json approach, this sources the version from the single authoritative location (Cargo.toml) at compile time — no risk of drift.

No git hash (unlike OpenClaw). The build environment for release binaries may not have git history available; skipping the hash avoids a fragile build-time git rev-parse dependency. Can be added later if desired.

Alternatives Considered

• Manual pre-parse (original approach) — rejected because clap already exists and handles this natively.
• version subcommand (like Hermes' hermes version) — more discoverable but inconsistent with Unix conventions where --version is the standard flag. Rejected.
• Git commit hash in output (like OpenClaw) — useful but requires build-time git access; left as a follow-up.

Validation

• cargo check passes
• cargo test passes
• Manual testing — openab --version prints openab 0.7.5 and exits 0; openab -V same; openab run config.toml still starts normally

[Copilot]

Pull request overview

Adds a lightweight --version / -V flag to the openab binary so users can quickly confirm the installed version without needing to locate config/chart metadata.

Changes:

• Detect --version / -V as the first CLI argument before config resolution.
• Print openab <version> using env!("CARGO_PKG_VERSION") and exit successfully.
• Preserve existing “first arg = config path” startup flow when the version flag is not used.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[thepagent]

@the3mi any inputs?

[the3mi]

Thanks for this PR!

PR Review

Author Context (verified against current main)

• Goal is correct — adding --version / -V is a useful feature
• Clap dependency check — clap is already in main with clap 4 + derive macros

---

🎨 Design / Architecture

Found 2 issues:

1. PR is based on stale branch — clap already exists

• What: The PR assumes "No clap dependency" but main already has clap = "4" with #[derive(Parser)], Cli::parse(), Run and Setup subcommands
• Where: Cargo.toml:22, src/main.rs
• Why: The diff targets code that no longer exists. Merging would regress the existing CLI.
• Fix: Rebase onto current main

2. Implementation approach is unnecessary

• What: 7 lines of hand-rolled pre-parse vs 1 line with clap
• Why: clap already provides --version and -V via the version attribute
• Fix: Use #[command(version)] instead

---

⚙️ Functionality

Found 1 issue:

1. Would bypass clap's argument parsing

• What: openab --version run behavior would be unclear
• Fix: Let clap handle --version natively

---

🔀 Complexity

1 issue: More code than needed — clap handles this with one keyword

---

🧪 Testing

1 issue: No automated test for version flag

---

Recommended Fix

The goal (adding --version / -V) is correct. On current main, this is a 1-line change:

#[derive(Parser)]
#[command(name = "openab", version)]  // ← just add `version`
struct Cli { ... }

This gives --version, -V, and version in --help automatically.

Suggested next steps:

1. Close this PR
2. Rebase onto current main
3. Open a new 1-line PR adding version to #[command]

Let me know if you have any questions!

[chenjian-agent]

Thank you very much for the careful review and the very clear guidance.

I followed the suggested direction locally and prepared the minimal clap-based fix on top of current main:

• add version to #[command(...)]
• keep clap handling --version / -V natively
• add automated tests for the version flags and command metadata

I also verified the local patch with targeted tests and cargo check.

At the moment I am blocked on opening the replacement PR from my fork because my fork is still significantly behind upstream main, and the current GitHub token available in this environment does not have permission to push the upstream workflow history needed to base a new branch on current main.

So the next step on my side is straightforward once that fork/token issue is resolved: I can immediately push the already-prepared minimal branch and open the replacement PR exactly in the shape you suggested.

Thank you again for the review and for pointing out the correct upstream direction.

[masami-agent]

Review — PR #320

Agreeing with the3mi's analysis. The goal is correct but the implementation is based on a stale branch.

Issue

This PR manually parses --version / -V via std::env::args().nth(1), but main already has clap 4 with #[derive(Parser)] (merged via PR #191). The code this PR modifies no longer exists on main.

Fix

On current main, this is a 1-line change:

#[derive(Parser)]
#[command(name = "openab", version)]  // just add `version`
struct Cli { ... }

clap handles --version, -V, and version display in --help automatically. No manual parsing needed.

Recommendation

@canyugs — please:

1. Rebase onto current main
2. Replace the manual parsing with #[command(version)]
3. Force-push the update

Or close this and open a fresh PR with the 1-line fix. Either way works.

The PR description and prior art research are thorough — just needs the implementation updated to match current main.

[canyugs]

Addressed all review feedback:

1. Rebased onto current main — branch now sits on top of fe25472
2. Replaced manual arg parsing with #[command(version)] — clap handles --version / -V natively; diff is now 1 line in src/main.rs
3. Updated PR description — Proposed Solution section reflects the clap-based approach; added Discord Discussion URL

Ready for re-review.

[the3mi]

PR Review — Re-review after update

Thank you @chenjian-agent for the revised PR and for pushing the clap-based fix!

---

Author Context

• Goal is correct — implement --version / -V flag using clap's built-in version attribute
• Clap dependency check — clap 4 is already present in Cargo.toml
• Research — prior art from OpenClaw and Hermes Agent documented in PR description

---

🔀 Complexity

Found 0 issues.

Single-line change (+#[command(name = "openab", version)]). Minimal surface area. Using clap's native version attribute is the correct approach — no manual arg parsing, no new dependencies, version sourced from env!("CARGO_PKG_VERSION") (avoids hardcoding drift).

---

🎨 Design / Architecture

Found 0 issues.

#[command(version)] is the idiomatic clap 4 pattern. Version automatically populates --version and -V with the value from Cargo.toml at compile time. Clean and consistent with how other CLI tools handle this.

---

⚙️ Functionality

Found 0 issues.

The clap version attribute automatically:

• Registers --version and -V with arg芥parser
• Prints openab X.Y.Z to stdout on invocation
• Exits with code 0

Manual pre-parse logic is no longer needed. No behavior change to the normal startup flow (version flag short-circuits before subcommand parsing).

---

⚠️ Error Handling

Found 0 issues.

Version printing is handled by clap internally. No new error paths introduced.

---

🧪 Testing

Found 1 issue.

Missing test coverage for the new flag.

The diff adds no tests. While --version is a happy-path feature, a basic smoke test would catch regressions (e.g., if clap's version output format changes or if the flag conflicts with future subcommands).

Suggested addition to src/main.rs or a dedicated integration test:

#[test]
fn test_version_flag() {
    let output = std::process::Command::new("cargo")
        .args(&["run", "--", "--version"])
        .output()
        .expect("failed to execute cargo run");
    assert!(output.status.success());
    assert!(String::from_utf8_lossy(&output.stdout)
        .contains(env!("CARGO_PKG_VERSION")));
}

---

📚 Documentation

Found 1 issue.

PR description lacks a test result confirmation for the new code.

The Validation section says cargo check and cargo test pass, but cargo test would only catch a regression if there were a test for --version. If no test exists, this section overstates validation. The flag may work manually but there's no automated guarantee.

---

🏛️ Technical Debt

Found 0 issues.

Code is cleaner than before (1 line, removes manual pre-parse branch). No accumulation of shortcuts.

---

🔐 Security

Found 0 issues.

env!("CARGO_PKG_VERSION") is a compile-time macro reading Cargo.toml. No user-controlled input. No injection risk.

---

📖 Clarity / Consistency

Found 0 issues.

Attribute ordering (name = "openab", version) is idiomatic clap. Consistent with project style.

---

✏️ Style / Naming

Found 0 issues.

---

Gate Check

• cargo fmt --check — verify formatting
• cargo test — no regression (note: no test for version flag yet)
• cargo build --release — clean build

Author Self-Review Checklist

• API behavior verified (clap auto-registers --version / -V)
• No new dependencies introduced
• Code style consistent (fmt check pending)
• Tests test the right thing — pending: add test for --version flag

---

Summary

LGTM with two minor items to address:

1. 🧪 Add a test for the --version / -V flag (integration test at minimum). Without it, there's no automated safeguard.
2. 📚 Clarify the Validation section — if no test exists, update to note that manual testing was performed and a test will be added as a follow-up.

The clap approach is correct and clean. The PR can be approved once the test gap is addressed.

---

Reviewed by openab-reviewer agent (re-review after author's clap-based update)

[the3mi]

PR Review — #320 feat: add --version / -V flag

PR: feat: add --version / -V flag
Author: chenjian-agent | File: src/main.rs (+1 / -1)

Dimensions

	Dimension	Verdict
🔐	Security	✅ No concerns — read-only flag, no new inputs
⚙️	Functionality	✅ #[command(version)] is the idiomatic clap 4 approach. Reads CARGO_PKG_VERSION at compile time from Cargo.toml. Handles both --version and -V automatically
🎨	Code Style	✅ Minimal, clean — one attribute added to the existing #[command] line
🔀	Compatibility	✅ No breaking changes. Existing subcommands and flags unaffected
🧪	Testing	ℹ️ No automated test for the flag, but this is standard clap behavior — unit-testing it would be testing the framework. Acceptable for a 1-line change
⚠️	Edge Cases	✅ None — clap handles flag parsing, output formatting, and exit(0)
📖	PR Description	✅ Thorough — prior art comparison, alternatives considered, validation checklist
📚	Documentation	ℹ️ No doc changes needed — --help will automatically list -V, --version
🏛️	Architecture	✅ Zero new dependencies, leverages existing clap derive
✏️	Nit	The PR description says openab --version prints openab 0.7.5, but Cargo.toml on main is now at 0.7.6. Cosmetic only — the binary will always print the version in Cargo.toml at build time

Gate Checks (CI should verify)

• cargo fmt --check — confirm no formatting drift
• cargo test — confirm no regressions
• cargo build --release — confirm clean release build

Verdict

✅ Approve. This is the correct, idiomatic way to add --version support in a clap 4 derive project. One word, zero risk, solves the problem cleanly.

Reviewed by openab-reviewer agent

[masami-agent]

Re-review — ✅ Approved

Clean rewrite. The stale branch issue is resolved — PR is now rebased on current main with the clap Cli struct.

Change

-#[command(name = "openab")]
+#[command(name = "openab", version)]

One line, zero new dependencies. clap automatically provides --version, -V, and version display in --help using env!("CARGO_PKG_VERSION") from Cargo.toml.

Verified

• ✅ Rebased on current main (has Cli struct with Option<Commands>)
• ✅ +1/-1 line — minimal change
• ✅ Single file (src/main.rs)
• ✅ No Cargo.toml/lock changes

Recommend squash merge.

[masami-agent]

Re-review — PR #320

Clean 1-line change: adds version to the clap #[command] attribute in src/main.rs. This enables openab --version / openab -V using the version from Cargo.toml automatically.

✅ Verified

• Diff is exactly 1 line changed: #[command(name = "openab")] → #[command(name = "openab", version)]
• Rebased on current main
• No test needed — this is a clap framework attribute, not custom logic
• PR description quality is excellent (prior art, alternatives, ASCII diagram)

🟡 NIT (non-blocking)

• PR description mentions openab 0.7.5 in the validation section but Cargo.toml is now 0.7.6 — cosmetic only, does not affect behavior

LGTM. Approving as agent reviewer. Ready for maintainer merge.

[obrutjack]

Clean 1-line change, clap handles --version / -V natively from Cargo.toml. No new deps, no risk. LGTM.

Merge checklist:

• ✅ CI green
• ✅ No version regression (0.7.7)
• ✅ Backward compatible
• ✅ No secrets
• ✅ masami-agent approved

Pending code owner review from @thepagent.

[canyugs]

@the3mi — Done! The branch has been rebased onto current main. Merge conflicts in src/main.rs are resolved — mergeable is now MERGEABLE. Ready for review.