feat: Add CLI argument parsing for agent selection and initial messages (#44)

## Summary

This PR adds command-line argument parsing to nori-cli, allowing users
to specify the agent and initial message from the command line.

### Changes

- **Add clap dependency**: Added clap v4 with derive feature for CLI
argument parsing
- **New CLI module**: Created `src/cli.rs` with `Cli` struct and agent
name mapping functions
- **Main function updates**: Modified `main.rs` to parse CLI args,
validate agent names, and read from stdin when piped
- **Run app updates**: Updated `run_app` to accept optional
`agent_index` and `initial_message` parameters
- **Comprehensive tests**: Added `tests/cli_args_test.rs` with tests for
all CLI parsing scenarios
- **Documentation updates**: Updated docs in both `src/docs.md` and
`tests/docs.md`

### Usage Examples

```bash
# Use specific agent
nori-cli --agent claude

# Use specific agent with initial message
nori-cli --agent codex "Hello world"

# Pipe input as initial message
echo "Hello from stdin" | nori-cli

# Short flag for agent
nori-cli -a mock "Test message"
```

### Features

- Agent selection via `--agent` or `-a` flag (claude, codex, claudecode,
mock)
- Initial message as positional argument or via stdin piping
- Case-insensitive agent name matching
- Input validation with helpful error messages
- CLI arguments take precedence over stdin when both provided

Author: CSRessel

Cargo.lock

@@ -26,6 +26,7 @@ async-stream = "0.3"
 which = "7.0"
 opener = "0.7"
 unicode-width = "0.2"
+clap = { version = "4", features = ["derive"] }
 tui-components = { path = "./tui-components" }
  agent-client-protocol = "0.7.0"
  tuicore = { git = "https://github.com/CSRessel/terminal-input-debug", rev = "a2f66fd" }

Cargo.toml

@@ -0,0 +1,30 @@
+use clap::Parser;
+
+#[derive(Parser, Debug, PartialEq)]
+#[command(name = "nori-cli")]
+#[command(about = "A TUI for interacting with AI agents", long_about = None)]
+pub struct Cli {
+    /// Select the agent to use (claude, claudecode, codex, mock)
+    #[arg(short, long)]
+    pub agent: Option<String>,
+
+    /// Initial message to send (or read from stdin)
+    pub message: Option<String>,
+}
+
+/// Map agent name to backend index
+/// Returns None if agent name is invalid
+pub fn agent_name_to_index(name: &str) -> Option<usize> {
+    match name.to_lowercase().as_str() {
+        "claude" => Some(0),
+        "codex" => Some(1),
+        "claudecode" => Some(2),
+        "mock" => Some(3),
+        _ => None,
+    }
+}
+
+/// Get list of valid agent names
+pub fn valid_agent_names() -> Vec<&'static str> {
+    vec!["claude", "codex", "claudecode", "mock"]
+}

src/cli.rs

@@ -20,13 +20,14 @@ Core application modules implementing the TUI's architecture: application state
 ```rust
 pub mod app;          // Model, Message, and update logic
 pub mod backends;     // AgentBackend trait and implementations
+pub mod cli;          // CLI argument parsing and agent name mapping
 pub mod conversation; // JSONL parsing and event rendering
 pub mod ui;           // Rendering functions for each mode
 ```
 
 **Entry Point** (@/src/main.rs):
-- `main()`: Sets up terminal (raw mode, Viewport::Inline(8)), runs async event loop, restores terminal on exit with cursor positioning to next line before disabling raw mode to ensure shell prompt appears cleanly below TUI content
-- `run_app()`: Core event loop using tokio::select! to handle messages and render at ~30 fps interval - includes mpsc channel for syncing `last_ctrl_c_time` to event handler task, conditionally increments `loading_frame` counter during streaming when using legacy spinner (only when `use_codex_components = false`)
+- `main()`: Parses CLI arguments via clap::Parser, validates agent name (exits with error if invalid), reads from stdin if piped, then sets up terminal (raw mode, Viewport::Inline(8)), runs async event loop, restores terminal on exit with cursor positioning to next line before disabling raw mode to ensure shell prompt appears cleanly below TUI content
+- `run_app(agent_index, initial_message)`: Core event loop using tokio::select! to handle messages and render at ~30 fps interval - accepts optional agent_index to skip agent selection screen and optional initial_message to pre-fill textarea - includes mpsc channel for syncing `last_ctrl_c_time` to event handler task, conditionally increments `loading_frame` counter during streaming when using legacy spinner (only when `use_codex_components = false`)
 - `handle_event_simple()` / `handle_key_simple()`: Convert crossterm key events to Message based on current mode - Ctrl-C detection happens FIRST before overlay/install prompt checks to ensure double Ctrl-C always works
 - `get_backend()`: Factory function that returns appropriate backend (Claude or Codex) based on selected_agent_index
 - `spawn_and_stream()`: Consumes backend stream using tokio::select! to multiplex stream consumption with cancellation signal - when cancelled, stream is dropped and child process cleanup happens via Drop semantics
@@ -57,6 +58,14 @@ pub mod ui;           // Rendering functions for each mode
 - `render_event()`: Converts ConversationEvent into styled ratatui Lines - UserMessage renders with cyan `[user]` prefix, StatusMessage renders with green `[status]` prefix, StreamCancelled renders "Interrupted" in red, other events render with type-specific prefixes and colors
 - `should_render_event()`: Filters events based on debug mode - SystemEvent and UnknownEvent are considered debug events (hidden when `show_debug: false`), all other events (UserMessage, AssistantMessage, ResultSummary, StderrOutput, StreamCancelled, StatusMessage) are always visible
 
+**CLI Argument Parsing** (@/src/cli.rs):
+- `Cli` struct: Derives clap::Parser for command-line argument parsing with two optional fields - `agent: Option<String>` for agent selection and `message: Option<String>` for initial message
+- `agent_name_to_index(name)`: Maps agent name strings to backend array indices - supports "claude" (0), "codex" (1), "claudecode" (2), "mock" (3) - case-insensitive matching via .to_lowercase(), returns None for invalid names
+- `valid_agent_names()`: Returns Vec of valid agent names for error messages
+- Agent selection via CLI bypasses TUI selection screen by setting `model.selected_agent_index` directly in run_app()
+- Stdin detection via `io::stdin().is_terminal()` from std::io::IsTerminal trait - reads piped input with `read_to_string()` before TUI initialization
+- CLI message argument takes precedence over stdin when both provided
+
 **Backend Abstraction** (@/src/backends.rs):
 - `AgentBackend` trait: `spawn_stream(prompt, cancel_token) -> Pin<Box<dyn Stream<Item = ConversationEvent>>>` and metadata methods
 - Accepts CancellationToken for cooperative cancellation - backends receive token but child process cleanup happens via Drop
@@ -101,7 +110,16 @@ Cancellation Path
 
 ### Things to Know
 
-**Terminal Cleanup Sequence** (@/src/main.rs:27-31):
+**CLI Argument Initialization Flow** (@/src/main.rs:31-68):
+- CLI parsing happens before terminal initialization to allow early exit on invalid agent names
+- Agent validation uses fail-fast strategy: invalid agent name prints error and exits with code 1 before TUI setup
+- Stdin detection via `!io::stdin().is_terminal()` checks if input is piped before consuming stdin with `read_to_string()`
+- Reading stdin consumes the entire input stream before TUI initialization - cannot read stdin after terminal is in raw mode
+- Message precedence: CLI argument (--message) takes priority over piped stdin via `cli.message.or(stdin_message)`
+- Agent selection bypass: when agent_index is Some, skips TUI agent selection screen by pre-populating `model.selected_agent_index`
+- Textarea pre-fill: initial_message sets textarea content via `.set_text()` before event loop starts
+
+**Terminal Cleanup Sequence** (@/src/main.rs):
 - Cleanup happens in specific order: move cursor to next line, disable raw mode, call ratatui::restore()
 - `MoveToNextLine(1)` from crossterm positions cursor below TUI content before raw mode is disabled
 - Without cursor positioning, shell prompt would appear in middle of painted TUI area with Viewport::Inline(8)

src/docs.md

@@ -2,6 +2,7 @@ pub mod acp_runner;
 pub mod app;
 pub mod autocomplete;
 pub mod backends;
+pub mod cli;
 pub mod commands;
 pub mod conversation;
 pub mod ui;

src/lib.rs

@@ -2,6 +2,7 @@ mod acp_runner;
 mod app;
 mod autocomplete;
 mod backends;
+mod cli;
 mod commands;
 mod conversation;
 mod ui;
@@ -11,32 +12,83 @@ use crate::autocomplete::update_autocomplete_state;
 use crate::backends::{
     AgentBackend, claude::ClaudeBackend, claude_code_acp::ClaudeCodeAcpBackend, mock::MockBackend,
 };
+use crate::cli::{Cli, agent_name_to_index, valid_agent_names};
 use crate::commands::{CommandRegistry, parse_slash_command};
 use crate::conversation::{ConversationEvent, render_event, should_render_event};
 
 use _tuicore::{TerminalWriter, TuiApp};
+use clap::Parser;
 use color_eyre::Result;
 use futures::StreamExt;
 use ratatui::crossterm::event::{self, Event, KeyCode, KeyEvent, KeyEventKind};
 use ratatui::prelude::CrosstermBackend;
+use std::io::{self, IsTerminal, Read};
 use std::thread;
 use tokio::sync::mpsc;
 use tokio::time::{Duration, interval};
 
 #[tokio::main]
 async fn main() -> Result<()> {
+    // Parse CLI arguments
+    let cli = Cli::parse();
+
+    // Validate agent name if provided
+    let agent_index = if let Some(ref agent_name) = cli.agent {
+        match agent_name_to_index(agent_name) {
+            Some(index) => Some(index),
+            None => {
+                eprintln!("Error: Invalid agent name '{agent_name}'");
+                eprintln!("Valid agents: {}", valid_agent_names().join(", "));
+                std::process::exit(1);
+            }
+        }
+    } else {
+        None
+    };
+
+    // Read from stdin if available (piped input)
+    let stdin_message = if !io::stdin().is_terminal() {
+        let mut buffer = String::new();
+        io::stdin().read_to_string(&mut buffer)?;
+        if !buffer.trim().is_empty() {
+            Some(buffer.trim().to_string())
+        } else {
+            None
+        }
+    } else {
+        None
+    };
+
+    // Determine initial message (CLI arg takes precedence over stdin)
+    let initial_message = cli.message.or(stdin_message);
+
     let mut tui_app = TuiApp::builder("nori-cli").inline(20).build();
 
     let mut terminal = tui_app.init()?;
-    run_app(&mut terminal).await?;
+    run_app(&mut terminal, agent_index, initial_message).await?;
 
     tui_app.restore()?;
     // Optional terminal.insert_before here, for an exit status/usage message!
     Ok(())
 }
 
-async fn run_app(terminal: &mut ratatui::Terminal<CrosstermBackend<TerminalWriter>>) -> Result<()> {
+async fn run_app(
+    terminal: &mut ratatui::Terminal<CrosstermBackend<TerminalWriter>>,
+    agent_index: Option<usize>,
+    initial_message: Option<String>,
+) -> Result<()> {
     let mut model = Model::default();
+
+    // Set agent index if provided via CLI
+    if let Some(index) = agent_index {
+        model.selected_agent_index = Some(index);
+    }
+
+    // Pre-fill textarea with initial message if provided
+    if let Some(message) = initial_message {
+        model.textarea.set_text(&message);
+    }
+
     let (tx, mut rx) = mpsc::unbounded_channel::<Message>();
 
     // Create command registry

src/main.rs

@@ -0,0 +1,72 @@
+use clap::Parser;
+use nori_cli::cli::Cli;
+
+#[test]
+fn test_agent_long_flag() {
+    let cli = Cli::try_parse_from(&["prog", "--agent", "claude"]).unwrap();
+    assert_eq!(cli.agent, Some("claude".to_string()));
+    assert_eq!(cli.message, None);
+}
+
+#[test]
+fn test_agent_short_flag() {
+    let cli = Cli::try_parse_from(&["prog", "-a", "codex"]).unwrap();
+    assert_eq!(cli.agent, Some("codex".to_string()));
+    assert_eq!(cli.message, None);
+}
+
+#[test]
+fn test_message_only() {
+    let cli = Cli::try_parse_from(&["prog", "Hello world"]).unwrap();
+    assert_eq!(cli.agent, None);
+    assert_eq!(cli.message, Some("Hello world".to_string()));
+}
+
+#[test]
+fn test_agent_and_message() {
+    let cli = Cli::try_parse_from(&["prog", "--agent", "mock", "Test message"]).unwrap();
+    assert_eq!(cli.agent, Some("mock".to_string()));
+    assert_eq!(cli.message, Some("Test message".to_string()));
+}
+
+#[test]
+fn test_no_arguments() {
+    let cli = Cli::try_parse_from(&["prog"]).unwrap();
+    assert_eq!(cli.agent, None);
+    assert_eq!(cli.message, None);
+}
+
+// Agent name mapping tests
+use nori_cli::cli::agent_name_to_index;
+
+#[test]
+fn test_agent_name_claude() {
+    assert_eq!(agent_name_to_index("claude"), Some(0));
+}
+
+#[test]
+fn test_agent_name_codex() {
+    assert_eq!(agent_name_to_index("codex"), Some(1));
+}
+
+#[test]
+fn test_agent_name_claudecode() {
+    assert_eq!(agent_name_to_index("claudecode"), Some(2));
+}
+
+#[test]
+fn test_agent_name_mock() {
+    assert_eq!(agent_name_to_index("mock"), Some(3));
+}
+
+#[test]
+fn test_agent_name_case_insensitive() {
+    assert_eq!(agent_name_to_index("Claude"), Some(0));
+    assert_eq!(agent_name_to_index("CODEX"), Some(1));
+}
+
+#[test]
+fn test_agent_name_invalid() {
+    assert_eq!(agent_name_to_index("invalid"), None);
+    assert_eq!(agent_name_to_index(""), None);
+}

tests/cli_args_test.rs

@@ -17,6 +17,19 @@ Test suite for the agent-router-tui application, covering state machine transiti
 
 ### Core Implementation
 
+**CLI Argument Parsing Tests** (@/tests/cli_args_test.rs):
+- `test_agent_long_flag()`: Verifies --agent flag parses correctly with agent name
+- `test_agent_short_flag()`: Verifies -a short flag parses correctly
+- `test_message_only()`: Verifies positional message argument without agent flag
+- `test_agent_and_message()`: Verifies both --agent and message arguments together
+- `test_no_arguments()`: Verifies empty CLI args parse to None values
+- `test_agent_name_claude()`: Verifies "claude" maps to index 0
+- `test_agent_name_codex()`: Verifies "codex" maps to index 1
+- `test_agent_name_claudecode()`: Verifies "claudecode" maps to index 2
+- `test_agent_name_mock()`: Verifies "mock" maps to index 3
+- `test_agent_name_case_insensitive()`: Verifies agent name matching is case-insensitive
+- `test_agent_name_invalid()`: Verifies invalid agent names return None from agent_name_to_index()
+
 **Ctrl-C Handling Tests** (@/tests/ctrl_c_handling_test.rs):
 - `test_first_ctrl_c_clears_textarea_and_shows_hint()`: Verifies first Ctrl-C press behavior
   - Adds text to textarea via .insert_str()
@@ -170,6 +183,16 @@ Test suite for the agent-router-tui application, covering state machine transiti
 - Extracts text field from AssistantMessage
 - Verifies contract between backends and main loop: backends output Claude CLI format, parse_jsonl_event() produces ConversationEvent
 
+**CLI Argument Test Coverage** (@/tests/cli_args_test.rs):
+- Comprehensive tests for clap::Parser argument parsing (11 tests total)
+- Tests both long (--agent) and short (-a) flag forms
+- Tests positional message argument parsing
+- Tests combination of agent flag and message argument
+- Tests empty argument scenario (no flags or args)
+- Agent name mapping tests verify all four backends (claude, codex, claudecode, mock)
+- Case-insensitive matching tests verify .to_lowercase() behavior
+- Invalid agent name test verifies None return for unknown agents
+
 **Conversation Module Test Coverage**:
 - Comprehensive tests for all ConversationEvent variants (21 tests total including UserMessage, StreamCancelled, StatusMessage, and filtering logic)
 - Edge cases: malformed JSON, missing fields, multiple text blocks, empty details
@@ -208,6 +231,8 @@ Test suite for the agent-router-tui application, covering state machine transiti
 - No integration test for actual stream cancellation with long-running process - test_cancel_stream_during_streaming only tests state machine
 - No integration test for Ctrl-C priority over overlays/install prompts - tests only verify Model state transitions, not actual key event routing in handle_key_simple
 - No test for main loop quit detection (Some → None timestamp transition) - would require full event loop integration
+- No integration tests for CLI argument flow - stdin reading, agent validation with exit code, agent selection bypass, textarea pre-fill - only unit tests for clap parsing and agent name mapping
+- No test for CLI message precedence (CLI arg vs stdin) - would require mocking stdin and command-line args together
 
 **CI Integration**:
 - Tests run on every PR via @/.github/workflows/pr-ci.yml