feat: add non-interactive mode for health checks and scripting (#314)

* feat: add non-interactive mode for health checks and scripting

Add --no-interactive flag to ahnlich-cli to enable:
- Docker health checks using CLI commands
- Scripting and automation via stdin
- Clean, parseable output (ANSI codes stripped)

Implementation:
- Added --no-interactive flag to CLI config
- Implemented run_non_interactive() method that reads from stdin
- Added strip_ansi_codes() helper for clean output
- Created integration tests
- Updated README with comprehensive documentation

* chore: add superpowers folder to gitignore

* test: add integration tests for non-interactive CLI mode

Add comprehensive integration tests that provision real servers:
- DB agent tests (PING, INFOSERVER, LISTSTORES, multiple commands)
- AI agent tests (PING, INFOSERVER, LISTSTORES, multiple commands)
- Error handling tests (connection refused, invalid command)

Implementation:
- Added dev-dependencies (db, ai, utils) for server provisioning
- Created test infrastructure with helper functions
- Fixed stdin EOF handling using spawn_blocking
- AI server now provisions with DB backend (required for most commands)
- All tests include 10s timeout protection
- Tests validate ANSI stripping works (non-interactive mode)

Tests use programmatic server provisioning with OS-selected ports
for isolation and parallel execution.

* docs: add health check examples for non-interactive CLI mode

* fix: check stdin before connecting in non-interactive mode

* fix: wrap stdin reading in spawn_blocking to prevent deadlock

- Prevents blocking the async runtime when reading from stdin
- Fixes timeout issues in integration tests
- Allows proper EOF signaling from parent processes

Author: deven96

.gitignore

@@ -35,3 +35,4 @@ profiling.json*
 #npm residue
 node_modules/
 .DS_Store
+docs/superpowers/

README.md

@@ -209,6 +209,45 @@ services:
 
 ```
 
+Below is an example `docker-compose.yaml` configuration with health checks using the CLI in non-interactive mode:
+
+```yaml
+
+services:
+  ahnlich_db:
+    image: ghcr.io/deven96/ahnlich-db:latest
+    command: >
+      "ahnlich-db run --host 0.0.0.0"
+    ports:
+      - "1369:1369"
+    healthcheck:
+      test: ["CMD-SHELL", "echo 'PING' | ahnlich-cli ahnlich --agent db --host 127.0.0.1 --port 1369 --no-interactive"]
+      interval: 10s
+      timeout: 5s
+      retries: 3
+      start_period: 5s
+
+  ahnlich_ai:
+    image: ghcr.io/deven96/ahnlich-ai:latest
+    command: >
+      "ahnlich-ai run --db-host ahnlich_db --host 0.0.0.0 \
+      --supported-models all-minilm-l6-v2"
+    ports:
+      - "1370:1370"
+    depends_on:
+      ahnlich_db:
+        condition: service_healthy
+    healthcheck:
+      test: ["CMD-SHELL", "echo 'PING' | ahnlich-cli ahnlich --agent ai --host 127.0.0.1 --port 1370 --no-interactive"]
+      interval: 10s
+      timeout: 5s
+      retries: 3
+      start_period: 10s
+
+```
+
+The `--no-interactive` flag allows the CLI to accept commands via stdin and exit immediately after processing, making it ideal for Docker health checks, CI/CD pipelines, and automated scripts.
+
 ### Execution Providers (Ahnlich AI)
 
 - `CUDA`: Only supports >= CUDAv12 and might need to `sudo apt install libcudnn9-dev-cuda-12`

ahnlich/Cargo.lock

@@ -24,3 +24,8 @@ ahnlich_types = { path = "../types", version = "*"  }
 serde_json.workspace = true
 serde.workspace = true
 tonic.workspace = true
+
+[dev-dependencies]
+db = { path = "../db" }
+ai = { path = "../ai" }
+utils = { path = "../utils", version = "*" }

ahnlich/cli/Cargo.toml

@@ -34,6 +34,59 @@ ahnlich_cli ahnlich --agent db --host 127.0.0.1 --port 1369
 ahnlich_cli ahnlich --agent ai --host 127.0.0.1 --port 1370
 ```
 
+### Non-Interactive Mode
+
+For scripting, health checks, and automation, use `--no-interactive` to read commands from stdin:
+
+```bash
+# Simple health check
+echo 'PING' | ahnlich-cli ahnlich --agent db --host 127.0.0.1 --port 1369 --no-interactive
+
+# From a file
+cat commands.txt | ahnlich-cli ahnlich --agent ai --host 127.0.0.1 --port 1370 --no-interactive
+
+# Heredoc
+ahnlich-cli ahnlich --agent db --host 127.0.0.1 --port 1369 --no-interactive << EOF
+PING
+LISTSTORES
+EOF
+```
+
+#### Docker Health Check
+
+Use non-interactive mode for Docker health checks:
+
+```yaml
+healthcheck:
+  test: ["CMD-SHELL", "echo 'PING' | ahnlich-cli ahnlich --agent db --host 127.0.0.1 --port 1369 --no-interactive"]
+  interval: 10s
+  timeout: 5s
+  retries: 3
+```
+
+#### Exit Codes
+
+- `0`: Success
+- `1`: Error (connection failure, invalid command, etc.)
+
+#### Output
+
+Non-interactive mode produces clean output without colors or prompts, suitable for parsing:
+
+```bash
+$ echo 'PING' | ahnlich-cli --no-interactive ...
+Success
+```
+
+Errors are written to stderr:
+
+```bash
+$ echo 'INVALID' | ahnlich-cli --no-interactive ...
+Error: Unknown command 'INVALID'
+$ echo $?
+1
+```
+
 ## Querying the DB
 
 The CLI accepts a range of commands for database operations. Commands are written in the following format:

ahnlich/cli/README.md

@@ -31,4 +31,8 @@ pub struct AhnlichCliConfig {
     /// Host to connect to Ahnlich AI or DB
     #[arg(long)]
     pub port: Option<u16>,
+
+    /// Run in non-interactive mode (read commands from stdin)
+    #[arg(long, default_value_t = false)]
+    pub no_interactive: bool,
 }

ahnlich/cli/src/config/cli.rs

@@ -8,22 +8,61 @@ async fn main() -> std::io::Result<()> {
 
     match cli.commands {
         ahnlich_cli::config::cli::Commands::Ahnlich(config) => {
-            let client = AgentClient::create_client(config.agent, &config.host, config.port)
+            // In non-interactive mode, check for input first before connecting
+            if config.no_interactive {
+                // Read stdin in a blocking task to avoid blocking the async runtime
+                let input_raw = tokio::task::spawn_blocking(|| {
+                    use std::io::Read;
+                    let mut input = String::new();
+                    io::stdin().read_to_string(&mut input)?;
+                    Ok::<String, io::Error>(input)
+                })
                 .await
-                .map_err(io::Error::other)?;
+                .map_err(|e| io::Error::other(format!("Failed to join task: {}", e)))??;
 
-            if !client
-                .is_valid_connection()
-                .await
-                .map_err(io::Error::other)?
-            {
-                return Err(io::Error::other(format!(
-                    "Connected Server is not a valid {client} Server"
-                )));
+                let input = input_raw.trim();
+
+                if input.is_empty() {
+                    eprintln!("Error: No input provided");
+                    std::process::exit(1);
+                }
+
+                // Now connect and execute
+                let client = AgentClient::create_client(config.agent, &config.host, config.port)
+                    .await
+                    .map_err(io::Error::other)?;
+
+                if !client
+                    .is_valid_connection()
+                    .await
+                    .map_err(io::Error::other)?
+                {
+                    return Err(io::Error::other(format!(
+                        "Connected Server is not a valid {client} Server"
+                    )));
+                }
+
+                let term = Term::new(client);
+                term.execute_non_interactive(input).await?;
+            } else {
+                let client = AgentClient::create_client(config.agent, &config.host, config.port)
+                    .await
+                    .map_err(io::Error::other)?;
+
+                if !client
+                    .is_valid_connection()
+                    .await
+                    .map_err(io::Error::other)?
+                {
+                    return Err(io::Error::other(format!(
+                        "Connected Server is not a valid {client} Server"
+                    )));
+                }
+
+                let term = Term::new(client);
+                term.welcome_message()?;
+                term.run().await?;
             }
-            let term = Term::new(client);
-            term.welcome_message()?;
-            term.run().await?;
         }
     }
     Ok(())

ahnlich/cli/src/main.rs

@@ -305,4 +305,83 @@ impl Term {
         disable_raw_mode()?;
         Ok(())
     }
+
+    /// Run in non-interactive mode: read from stdin, execute, output results
+    ///
+    /// Behavior:
+    /// - Reads all input from stdin until EOF
+    /// - Executes queries via the client
+    /// - Outputs clean results to stdout (no colors, no prompts)
+    /// - Errors go to stderr
+    /// - Exits with code 1 on error, 0 on success
+    pub async fn execute_non_interactive(&self, input: &str) -> io::Result<()> {
+        // Execute queries
+        match self.client.parse_queries(input).await {
+            Ok(responses) => {
+                // Output clean results (strip ANSI color codes)
+                for msg in responses {
+                    println!("{}", strip_ansi_codes(&msg));
+                }
+                Ok(())
+            }
+            Err(err) => {
+                // Error to stderr, exit with error code
+                eprintln!("{}", err);
+                std::process::exit(1);
+            }
+        }
+    }
+}
+
+/// Strip ANSI color codes from a string for clean output
+fn strip_ansi_codes(s: &str) -> String {
+    let mut result = String::new();
+    let mut chars = s.chars();
+
+    while let Some(ch) = chars.next() {
+        if ch == '\x1b' {
+            // Skip ANSI escape sequence
+            if chars.next() == Some('[') {
+                // Skip until we hit a letter (end of escape sequence)
+                for ch in chars.by_ref() {
+                    if ch.is_ascii_alphabetic() {
+                        break;
+                    }
+                }
+            }
+        } else {
+            result.push(ch);
+        }
+    }
+
+    result
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_strip_ansi_codes_no_codes() {
+        let input = "Hello World";
+        assert_eq!(strip_ansi_codes(input), "Hello World");
+    }
+
+    #[test]
+    fn test_strip_ansi_codes_with_color() {
+        let input = "\x1b[32mSuccess\x1b[0m";
+        assert_eq!(strip_ansi_codes(input), "Success");
+    }
+
+    #[test]
+    fn test_strip_ansi_codes_multiple_colors() {
+        let input = "\x1b[31mError:\x1b[0m \x1b[32mDetails\x1b[0m";
+        assert_eq!(strip_ansi_codes(input), "Error: Details");
+    }
+
+    #[test]
+    fn test_strip_ansi_codes_empty() {
+        let input = "";
+        assert_eq!(strip_ansi_codes(input), "");
+    }
 }