feat(cli): coding-agent sidecar UX — wizard, doctor, help, banner

crates/cli/Cargo.toml

@@ -22,9 +22,11 @@ async-stream = "0.3"
 axum = "0.8"
 bytes = "1"
 clap = { version = "4", features = ["derive", "env"] }
+clap_complete = "4"
 futures-util = "0.3"
 http = "1"
 http-body-util = "0.1"
+dialoguer = { version = "0.11", default-features = false }
 reqwest = { version = "0.12", default-features = false, features = ["json", "rustls-tls-native-roots", "stream"] }
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"

crates/cli/README.md

@@ -0,0 +1,123 @@
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
+
+[![License](https://img.shields.io/github/license/NVIDIA/NeMo-Flow)](https://github.com/NVIDIA/NeMo-Flow/blob/main/LICENSE)
+[![GitHub](https://img.shields.io/badge/github-repo-blue?logo=github)](https://github.com/NVIDIA/NeMo-Flow/)
+[![Release](https://img.shields.io/github/v/release/NVIDIA/NeMo-Flow?color=green)](https://github.com/NVIDIA/NeMo-Flow/releases)
+[![Codecov](https://codecov.io/gh/NVIDIA/NeMo-Flow/branch/main/graph/badge.svg)](https://app.codecov.io/gh/NVIDIA/NeMo-Flow)
+[![PyPI](https://img.shields.io/pypi/v/nemo-flow?color=4B8BBE&logo=pypi)](https://pypi.org/project/nemo-flow/)
+[![npm node](https://img.shields.io/npm/v/nemo-flow-node?label=nemo-flow-node&color=CC3534&logo=npm)](https://www.npmjs.com/package/nemo-flow-node)
+[![npm wasm](https://img.shields.io/npm/v/nemo-flow-wasm?label=nemo-flow-wasm&color=CC3534&logo=npm)](https://www.npmjs.com/package/nemo-flow-wasm)
+[![Crates.io](https://img.shields.io/crates/v/nemo-flow?label=nemo-flow&color=B7410E&logo=rust)](https://crates.io/crates/nemo-flow)
+[![Crates.io](https://img.shields.io/crates/v/nemo-flow-adaptive?label=nemo-flow-adaptive&color=B7410E&logo=rust)](https://crates.io/crates/nemo-flow-adaptive)
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/NVIDIA/NeMo-Flow)
+
+# nemo-flow-cli
+
+`nemo-flow-cli` is the coding-agent gateway CLI for NeMo Flow observability.
+It installs the `nemo-flow` binary, which can configure supported coding-agent
+hooks, run agents through an ephemeral gateway, and diagnose local agent and
+exporter readiness.
+
+The CLI is a Rust package in this repository, but most users should interact
+with the installed `nemo-flow` command rather than link against the crate.
+
+## Why Use It?
+
+- 🧭 **Observe existing coding agents**: Run Claude Code, Codex, Cursor, or
+  Hermes through a local NeMo Flow gateway without changing the agent itself.
+- 🛠️ **Configure hooks interactively**: Use the setup wizard to write project or
+  user config and install the hook files needed by supported agents.
+- 📡 **Export local sessions**: Write ATIF trajectory files, ATOF event JSONL
+  streams, or OpenInference spans from one shared config model.
+- 🩺 **Diagnose the machine**: Check config layers, agent binaries, hook status,
+  observability outputs, and shell completions with `nemo-flow doctor`.
+
+## What You Get
+
+- ✅ **`nemo-flow` binary**: The executable installed by the `nemo-flow-cli`
+  Cargo package.
+- ✅ **First-run setup**: Bare `nemo-flow` launches setup when no config exists,
+  then runs doctor once config is present.
+- ✅ **Agent shortcuts**: `nemo-flow claude`, `nemo-flow codex`,
+  `nemo-flow cursor`, and `nemo-flow hermes` start observed agent runs.
+- ✅ **Config-driven launch**: `nemo-flow run` resolves config, environment, and
+  CLI overrides for deterministic non-interactive use.
+- ✅ **Hook forwarding server**: A local gateway accepts agent hook events and
+  provider-shaped OpenAI or Anthropic requests.
+
+## Installation
+
+Install the CLI from a repository checkout:
+
+```bash
+cargo install --path crates/cli
+```
+
+That command installs the binary as:
+
+```bash
+nemo-flow --version
+```
+
+For local development, build and test the package directly:
+
+```bash
+cargo build -p nemo-flow-cli
+cargo test -p nemo-flow-cli
+```
+
+## Getting Started
+
+Run the first-time setup wizard:
+
+```bash
+nemo-flow
+```
+
+After setup, inspect local readiness:
+
+```bash
+nemo-flow doctor
+```
+
+Run a supported agent through the gateway:
+
+```bash
+nemo-flow codex
+nemo-flow claude -- "summarize this repository"
+```
+
+Use `run --dry-run` to inspect resolved config without spawning the agent:
+
+```bash
+nemo-flow run --agent codex --dry-run
+```
+
+## Configuration
+
+Project config lives at `./.nemo-flow/config.toml`; user config lives at
+`~/.config/nemo-flow/config.toml` or `$XDG_CONFIG_HOME/nemo-flow/config.toml`.
+The project layer overrides system config, and the user layer overrides the
+project layer.
+
+Exporter config uses nested per-backend tables:
+
+```toml
+[exporters.atif]
+dir = "./atif"
+
+[exporters.atof]
+dir = "./atof"
+mode = "append"
+filename_template = "{session_id}.jsonl"
+
+[exporters.openinference]
+endpoint = "http://localhost:6006/v1/traces"
+```
+
+## Documentation
+
+NeMo Flow Documentation: https://nvidia.github.io/NeMo-Flow