Skip to content

docs: add coding-agent CLI guidance #97

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
AjayThorve wants to merge 1 commit into from
Closed

docs: add coding-agent CLI guidance #97

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 4 additions & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -114,7 +114,8 @@ For source builds, testing, and contribution workflow, see [CONTRIBUTING.md](CON

End-user documentation lives at [nvidia.github.io/NeMo-Flow](https://nvidia.github.io/NeMo-Flow/).

The primary documentation track covers Rust, Python, and Node.js.
The primary documentation track covers Rust, Python, and Node.js. Experimental
CLI gateway docs are available for local coding-agent observability.
Comment on lines +116 to +117
Copy link
Copy Markdown

@coderabbitai coderabbitai Bot May 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Link the First Mention of CLI Gateway Documentation

Line 116 introduces the experimental CLI docs but does not link to the destination. Add a direct link at first mention to improve navigation.

As per coding guidelines, "Link the first mention of a product name when the destination helps the reader."

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@README.md` around lines 116 - 117, Update the README sentence that currently
reads "Experimental CLI gateway docs are available for local coding-agent
observability." to make the first mention of the CLI docs a markdown link:
replace the plain phrase "experimental CLI gateway docs" with a link to the
canonical CLI gateway documentation page (e.g., the project docs path or URL for
the CLI gateway) so the first occurrence of that product/document is clickable;
keep the remainder of the sentence unchanged and ensure no subsequent duplicate
linking of the same phrase elsewhere.


The Go, WebAssembly, and raw FFI surfaces are currently experimental and remain source-first under
`go/nemo_flow`, `crates/wasm`, and `crates/ffi`.
Expand All @@ -128,6 +129,7 @@ The table below summarizes the support level for each binding surface.
| Python | ✅ Fully Supported | Fully documented with Quick Start and Guides |
| Node.js | ✅ Fully Supported | Fully documented with Quick Start and Guides |
| Rust | ✅ Fully Supported | Fully documented with Quick Start and Guides |
| Coding-Agent CLI | 🚧 Experimental | Binary crate under `crates/cli`. |
| Go | 🚧 Experimental | Source-first under `go/nemo_flow`. |
| WebAssembly | 🚧 Experimental | Source-first under `crates/wasm`. |
| FFI | 🚧 Experimental | Source-first under `crates/ffi`. |
Expand Down Expand Up @@ -162,6 +164,7 @@ The following table summarizes maintained third-party integrations and whether e
| [opencode](third_party/README-opencode.md) | 🚧 Patch | ✅ Yes | ✅ Yes | ✅ Yes | ✅ Yes |
| [OpenClaw](integrations/openclaw/README.md) | `nemo-flow-openclaw` package, `nemo-flow` plugin ID | ✅ Yes | ❌ No | ❌ No | ❌ No |
| [Hermes Agent](third_party/README-hermes-agent.md) | 🚧 Patch | ✅ Yes | ✅ Yes | ✅ Yes | ✅ Yes |
| [Coding-Agent CLI](docs/integrate-frameworks/coding-agent-gateway.md) for Claude Code, Codex, Cursor, and Hermes | 🚧 Experimental `nemo-flow-cli` binary | ✅ Yes | 🚧 LLM gateway only | 🚧 LLM gateway only | 🚧 LLM gateway only |

Patch-based integrations offer experimental support. Our roadmap includes switching over to first-party plugins and packages where upstream extension points allow it.

Expand Down
59 changes: 49 additions & 10 deletions crates/cli/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,14 +12,15 @@ SPDX-License-Identifier: Apache-2.0
[![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)
[![Crates.io](https://img.shields.io/crates/v/nemo-flow-cli?label=nemo-flow-cli&color=B7410E&logo=rust)](https://crates.io/crates/nemo-flow-cli)
[![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.
`nemo-flow-cli` is the experimental 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.
Expand Down Expand Up @@ -50,10 +51,10 @@ with the installed `nemo-flow` command rather than link against the crate.

## Installation

Install the CLI from a repository checkout:
Install the CLI:

```bash
cargo install --path crates/cli
cargo install nemo-flow-cli
```

That command installs the binary as:
Expand Down Expand Up @@ -96,12 +97,47 @@ Use `run --dry-run` to inspect resolved config without spawning the agent:
nemo-flow run --agent codex --dry-run
```

## Benchmark And Eval Runs
Copy link
Copy Markdown

@coderabbitai coderabbitai Bot May 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Use lowercase for conjunctions in title case headings.

The heading uses "Benchmark And Eval Runs" but standard title case rules require conjunctions like "and" to be lowercase unless they are the first or last word. As per coding guidelines, use title case consistently in technical documentation headings.

Proposed fix 
-## Benchmark And Eval Runs
+## Benchmark and Eval Runs
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
## Benchmark And Eval Runs
## Benchmark and Eval Runs
🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@crates/cli/README.md` at line 106, Update the heading "Benchmark And Eval
Runs" to follow title case rules by lowercasing the conjunction: change it to
"Benchmark and Eval Runs" so "and" is lowercase (adjust the heading text in the
README where the heading "Benchmark And Eval Runs" appears).


Use `nemo-flow run` for non-interactive benchmark tasks so each run gets an
ephemeral gateway and isolated observability artifacts. Prefer absolute
artifact directories when the benchmark harness runs from a different directory
than the task repository.

This example uses Codex CLI because it has a non-interactive `exec` mode. Use
the equivalent non-interactive command for another coding agent when one is
available.

```bash
RUN_ID="$(date +%Y%m%d_%H%M%S)"
ART="/tmp/nemo-flow-eval/$RUN_ID"
mkdir -p "$ART/atif" "$ART/atof"

nemo-flow run \
--atif-dir "$ART/atif" \
--atof-dir "$ART/atof" \
-- codex \
--ask-for-approval never \
exec \
--cd /path/to/benchmark/repo \
--sandbox workspace-write \
--color never \
"Run the benchmark task and report the result."

find "$ART" -maxdepth 3 -type f -print
```

The expected output includes one ATIF JSON file and one ATOF JSONL file for
the run. Remote or cloud-hosted tasks are outside the local gateway's LLM
capture boundary unless their model traffic reaches the local gateway.

## 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.
System config lives at `/etc/nemo-flow/config.toml`, project config lives at
the nearest `./.nemo-flow/config.toml`, and user config lives at
`$XDG_CONFIG_HOME/nemo-flow/config.toml` or `~/.config/nemo-flow/config.toml`.
The CLI loads those layers in that order, then applies `NEMO_FLOW_*`
environment variables and command flags.

Exporter config uses nested per-backend tables:

Expand All @@ -118,6 +154,9 @@ filename_template = "{session_id}.jsonl"
endpoint = "http://localhost:6006/v1/traces"
```

Use `plugin.toml` in the same system, project, or user config locations when
the gateway should activate process-level plugin config.

## Documentation

NeMo Flow Documentation: https://nvidia.github.io/NeMo-Flow
159 changes: 159 additions & 0 deletions docs/getting-started/cli.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,159 @@
<!--
SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
SPDX-License-Identifier: Apache-2.0
-->

# CLI Gateway Quick Start

The `nemo-flow` CLI gateway is experimental. Use it when you want to try local
observability for coding agents without changing the agent implementation. The
CLI can configure supported agent hooks, start a short-lived gateway around one
agent run, run a long-running gateway, and diagnose local setup.

## Install The CLI
Copy link
Copy Markdown

@coderabbitai coderabbitai Bot May 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Normalize heading title case for articles.

Headings capitalize The mid-title (Install The CLI, Use The Wizard, Run An Observed Agent), which is inconsistent with standard title case used elsewhere in the docs.

As per coding guidelines, "Use title case consistently in technical documentation headings."

Also applies to: 23-23, 48-48

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/getting-started/cli.md` at line 13, Update the three headings to use
consistent title case by lowercasing articles mid-title: change "Install The
CLI" to "Install the CLI", "Use The Wizard" to "Use the Wizard" (if not
first/last word lowercase 'the'), and "Run An Observed Agent" to "Run an
Observed Agent"; locate and edit the heading strings in the document (search for
the exact heading text) to apply these normalized title-case forms.


Install the CLI:

```bash
cargo install nemo-flow-cli
```

That command installs the executable as `nemo-flow`.

## Use The Wizard

Run the first-time setup wizard:

```bash
nemo-flow
```

Bare `nemo-flow` launches setup when no config exists. After config exists, the
same command runs `nemo-flow doctor` as a quick health check.

The wizard detects supported agent binaries on `PATH`, asks which agents to
observe, asks where to save config, and enables local ATIF export by default.
Re-run setup later with:

```bash
nemo-flow config
nemo-flow config codex
nemo-flow config hermes
```

Use the scoped form when you only want to refresh one agent's settings. Use
`nemo-flow config --reset` to remove the project config, or
`nemo-flow config <agent> --reset` to remove one project-local agent block.

## Run An Observed Agent

Use the agent shortcuts for day-to-day runs:

```bash
nemo-flow codex
nemo-flow claude -- "summarize this repository"
nemo-flow cursor
nemo-flow hermes
```

The shortcut starts an ephemeral gateway on `127.0.0.1`, injects the agent's
hook and provider routing settings for that process, and stops the gateway when
the agent exits.

Inspect readiness and detected agents with:

```bash
nemo-flow doctor
nemo-flow doctor codex
nemo-flow agents
```

## Config Layers

When no explicit `--config` path is passed, the CLI loads config from lowest to
highest precedence:

1. System: `/etc/nemo-flow/config.toml`
2. Project: nearest `.nemo-flow/config.toml`, walking up from the current
directory
3. User: `$XDG_CONFIG_HOME/nemo-flow/config.toml`, or
`~/.config/nemo-flow/config.toml`
4. Environment variables such as `NEMO_FLOW_ATIF_DIR` and
`NEMO_FLOW_OPENAI_BASE_URL`
5. CLI flags on the current command

Passing `--config path/to/config.toml` disables automatic system, project, and
user discovery for that command.

Use this minimal project config as a starting point:

```toml
[exporters.atif]
dir = ".nemo-flow/atif"

[exporters.atof]
dir = ".nemo-flow/atof"
mode = "append"
filename_template = "{session_id}.jsonl"

[agents.codex]
command = "codex"

[agents.claude]
command = "claude"

[agents.cursor]
command = "cursor-agent"
patch_restore_hooks = true

[agents.hermes]
command = "hermes"
```

Add provider and OpenInference settings only when you need to override defaults:

```toml
[upstream]
openai_base_url = "https://api.openai.com"
anthropic_base_url = "https://api.anthropic.com"

[exporters.openinference]
endpoint = "http://localhost:6006/v1/traces"
```

Plugin config can live in one of three places: `--plugin-config` JSON,
`[plugins].config` inside `config.toml`, or a sibling/discovered `plugin.toml`.
Do not mix these sources in one effective CLI invocation.

## Advanced Commands

Use `run` when you need deterministic, non-interactive behavior:

```bash
nemo-flow run --agent codex --dry-run --print
nemo-flow run --agent codex -- exec "fix the failing test"
```

Use daemon mode when an agent or IDE is launched separately and can point its
provider traffic or hooks at a long-running local gateway:

```bash
nemo-flow --bind 127.0.0.1:4040
```

Install shell completions when your package manager did not do that for you:

```bash
nemo-flow completions --install
```

`nemo-flow hook-forward` is the internal hook entrypoint generated by setup and
transparent runs. You normally do not call it directly except for smoke tests.

## Next Steps

- [Advanced Guide: Coding-Agent Gateway](../integrate-frameworks/coding-agent-gateway.md)
Comment on lines +154 to +155
Copy link
Copy Markdown

@coderabbitai coderabbitai Bot May 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 Nitpick | 🔵 Trivial | ⚡ Quick win

Add a lead-in sentence before the links list.

The "Next Steps" section jumps directly from the heading to a list of links without a prose introduction.

Suggested improvement 
 ## Next Steps
 
+Refer to the following guides for detailed configuration and agent-specific setup:
+
 - [Advanced Guide: Coding-Agent Gateway](../integrate-frameworks/coding-agent-gateway.md)

As per coding guidelines, "All lists should have a complete lead-in sentence."

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
- [Advanced Guide: Coding-Agent Gateway](../integrate-frameworks/coding-agent-gateway.md)
## Next Steps
Refer to the following guides for detailed configuration and agent-specific setup:
- [Advanced Guide: Coding-Agent Gateway](../integrate-frameworks/coding-agent-gateway.md)
🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/getting-started/cli.md` around lines 160 - 161, Add a complete lead-in
sentence immediately under the "Next Steps" heading describing what the reader
will find in the following links (e.g., a short sentence like "The following
guides walk you through advanced setup and integration options:") so the
bulleted list that includes "Advanced Guide: Coding-Agent Gateway" has a prose
introduction; update the paragraph text directly above the existing list in
docs/getting-started/cli.md near the "Next Steps" heading.

- [Claude Code Gateway Guide](../integrate-frameworks/coding-agent-claude-code.md)
- [Codex Gateway Guide](../integrate-frameworks/coding-agent-codex.md)
- [Cursor Gateway Guide](../integrate-frameworks/coding-agent-cursor.md)
- [Hermes Gateway Guide](../integrate-frameworks/coding-agent-hermes.md)
55 changes: 55 additions & 0 deletions docs/getting-started/configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -50,3 +50,58 @@ deployment manifests.
## Adaptive Setup

Adaptive optimization is enabled through the adaptive plugin component and binding helper APIs. See [Configure Adaptive Optimization](../use-adaptive-optimization/configure.md).

## CLI Gateway Setup

The `nemo-flow` CLI gateway is the exception to the "no global config file"
rule because it runs outside an application process. Use it when you want local
observability for coding-agent sessions such as Claude Code, Codex, Cursor, or
Hermes.

Run the setup wizard:

```bash
nemo-flow
```

The wizard writes project config at `.nemo-flow/config.toml`, user config at
`$XDG_CONFIG_HOME/nemo-flow/config.toml` or `~/.config/nemo-flow/config.toml`,
or both. System config can be supplied at `/etc/nemo-flow/config.toml` for
shared machines and CI images.

When no explicit `--config` path is passed, CLI config precedence is:

1. Built-in defaults
2. `/etc/nemo-flow/config.toml`
3. Nearest project `.nemo-flow/config.toml`, walking up from the current
directory
4. `$XDG_CONFIG_HOME/nemo-flow/config.toml`, or
`~/.config/nemo-flow/config.toml`
5. `NEMO_FLOW_*` environment variables
6. Current command flags

Use the current exporter shape in new config files:

```toml
[exporters.atif]
dir = ".nemo-flow/atif"

[exporters.atof]
dir = ".nemo-flow/atof"
mode = "append"
filename_template = "{session_id}.jsonl"

[exporters.openinference]
endpoint = "http://localhost:6006/v1/traces"

[agents.codex]
command = "codex"
```

For CLI gateway plugin activation, use exactly one source per invocation:
`--plugin-config` JSON, `[plugins].config` inside `config.toml`, or
`plugin.toml` in the discovered system, project, or user config locations.

See [CLI Gateway Quick Start](cli.md) for wizard commands and
[Advanced Guide: Coding-Agent Gateway](../integrate-frameworks/coding-agent-gateway.md)
for daemon mode, transparent runs, hook forwarding, and per-agent guides.
11 changes: 5 additions & 6 deletions docs/getting-started/installation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -47,9 +47,9 @@ nemo-flow-adaptive = "0.1.*"

- `nemo-flow` provides the core runtime APIs for scopes, middleware, subscribers, plugins, tool calls, and LLM calls.
- `nemo-flow-adaptive` provides adaptive runtime primitives and Redis-backed learning components when you want adaptive optimization behavior in Rust.
- `nemo-flow-cli` is a published binary crate for coding-agent hook and LLM
gateway observability. Install it with `cargo install nemo-flow-cli` when
you need the `nemo-flow` executable.
- `nemo-flow-cli` is a binary crate for coding-agent hook and LLM gateway
observability. Install it with `cargo install nemo-flow-cli` when you need
the `nemo-flow` executable.

## Install from Source

Expand Down Expand Up @@ -103,11 +103,10 @@ nemo-flow = { path = "../NeMo-Flow/crates/core" }
nemo-flow-adaptive = { path = "../NeMo-Flow/crates/adaptive" }
```

Install the local gateway binary from a source checkout when you need to run the
gateway during development:
Install the gateway binary when you need to run the gateway:

```bash
cargo install --path ../NeMo-Flow/crates/cli
cargo install nemo-flow-cli
```

## Install from the Repository
Expand Down
1 change: 1 addition & 0 deletions docs/getting-started/quick-start.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,4 +13,5 @@ Choose the Quick Start guide for the primary binding that you plan to use.
Python Quick Start <python>
Node.js Quick Start <nodejs>
Rust Quick Start <rust>
CLI Gateway Quick Start <cli>
```
8 changes: 4 additions & 4 deletions docs/getting-started/rust.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,8 +25,8 @@ serde_json = "1"

- `nemo-flow` is the core Rust runtime surface.
- `nemo-flow-adaptive` is the companion crate for adaptive runtime primitives and Redis-backed learning components.
- `nemo-flow-cli` is a binary crate. Use `cargo install --path
../NeMo-Flow/crates/cli` when you need the local coding-agent gateway.
- `nemo-flow-cli` is a binary crate. Use `cargo install nemo-flow-cli` when
you need the local coding-agent gateway.

### Install from a Package Manager

Expand All @@ -39,8 +39,8 @@ nemo-flow-adaptive = "0.1.*"
serde_json = "1"
```

Install the published gateway binary separately when you need coding-agent hook
and LLM gateway observability:
Install the gateway binary when you need coding-agent hook and LLM gateway
observability:

```bash
cargo install nemo-flow-cli
Expand Down
Loading
Loading