hyperware-ai · Gohlub · Jul 3, 2025 · Jul 18, 2025 · Aug 20, 2025 · Sep 4, 2025
diff --git a/README.md b/README.md
@@ -141,7 +141,8 @@ Hyperware processes can handle four types of requests, specified by attributes:
 |-----------|-------------|
 | `#[local]` | Handles local (same-node) requests |
 | `#[remote]` | Handles remote (cross-node) requests |
-| `#[http]` | Handles ALL HTTP requests (GET, POST, PUT, DELETE, etc.) |
+| `#[http]` | Handles ALL HTTP requests (GET, POST, PUT, DELETE, etc.)  |
+| `#[terminal]` | Handles terminal requests from the system terminal |
 | `#[eth]` | Handles Ethereum subscription updates from your RPC provider |
 
 These attributes can be combined to make a handler respond to multiple request types:
@@ -164,9 +165,83 @@ fn handle_any_http(&mut self) -> String {
 fn get_status(&mut self) -> String {
     format!("Status: {}", self.counter)
 }
+
+#[terminal]
+fn handle_terminal_command(&mut self, command: String) -> String {
+    match command.as_str() {
+        "status" => format!("Counter: {}", self.counter),
+        "reset" => {
+            self.counter = 0;
+            "Counter reset".to_string()
+        }
+        _ => "Unknown command".to_string()
+    }
+}
+```
+
+#### Messaging Terminal Handlers
+
+To send messages to terminal handlers from the Hyperdrive terminal, use the `m` command:
+
+```bash
+m - message a process
+Usage: m <ADDRESS> <BODY>
+Arguments:
+  <ADDRESS> hns address e.g. some-node.os@process:pkg:publisher.os
+  <BODY>    json payload wrapped in single quotes, e.g. '{"foo": "bar"}'
+Options:
+  -a, --await <SECONDS> await the response, timing out after SECONDS
+Example:
+  m -a 5 our@foo:bar:baz '{"some payload": "value"}'
+    - this will await the response and print it out
+  m our@foo:bar:baz '{"some payload": "value"}'
+    - this one will not await the response or print it out
 ```
 
-The function arguments and the return values _have_ to be serializable with `Serde`.
+For terminal handlers, the JSON body should match the generated request enum variant. Here's a complete example:
+
+**Handler Implementation:**
+```rust
+#[terminal]
+fn handle_terminal_command(&mut self, command: String) {
+    match command.as_str() {
+        "status" => kiprintln!("Counter: {}", self.counter),
+        "reset" => {
+            self.counter = 0;
+            kiprintln!("Counter reset");
+        },
+        "increment" => {
+            self.counter += 1;
+            kiprintln!("Counter incremented to: {}", self.counter);
+        },
+        "help" => kiprintln!("Available commands: status, reset, increment, help"),
+        _ => kiprintln!("Unknown command. Type 'help' for available commands.")
+    }
+}
+```
+
+**Messaging the Terminal Handler:**
+```bash
+# Get current status (output will be printed to terminal)
+m our@my-process:my-package:my-publisher.os '{"HandleTerminalCommand": "status"}'
+
+# Reset the counter (output will be printed to terminal)
+m our@my-process:my-package:my-publisher.os '{"HandleTerminalCommand": "reset"}'
+
+# Increment counter (output will be printed to terminal)
+m our@my-process:my-package:my-publisher.os '{"HandleTerminalCommand": "increment"}'
+
+# Get help (output will be printed to terminal)
+m our@my-process:my-package:my-publisher.os '{"HandleTerminalCommand": "help"}'
+```
+
+**Important Notes:**
+- Terminal handlers should **not** have a return value 
+- All output should be handled with `kiprintln!()` or logging functions
+
+```
+
+The function arguments _have_ to be serializable with `Serde`, but return values are not used.
 
 #### HTTP Method Support and Smart Routing
 
@@ -600,6 +675,18 @@ impl AsyncRequesterState {
         self.request_count
     }
 
+    #[terminal]
+    fn handle_terminal(&mut self, command: String) -> String {
+        match command.as_str() {
+            "stats" => format!("Requests processed: {}", self.request_count),
+            "clear" => {
+                self.request_count = 0;
+                "Request count cleared".to_string()
+            }
+            _ => "Available commands: stats, clear".to_string()
+        }
+    }
+
     #[ws]
     fn websocket(&mut self, channel_id: u32, message_type: WsMessageType, blob: LazyLoadBlob) {
         // Process WebSocket messages
@@ -1406,6 +1493,9 @@ async fn get_user(&mut self, id: u64) -> User { ... }
 #[local]
 #[remote]
 fn update_settings(&mut self, settings: Settings, apply_now: bool) -> bool { ... }
+
+#[terminal]
+fn execute_command(&mut self, cmd: String) -> String { ... }
 ```
 
 The macro generates these enums:
@@ -1414,11 +1504,13 @@ The macro generates these enums:
 enum Request {
     GetUser(u64),
     UpdateSettings(Settings, bool),
+    ExecuteCommand(String),
 }
 
 enum Response {
     GetUser(User),
     UpdateSettings(bool),
+    ExecuteCommand(String),
 }
 ```