Merge pull request #93 from kinode-dao/da/terminal-update

Da/terminal update

src/SUMMARY.md

@@ -20,6 +20,7 @@
 - [HTTP Server & Client](./http_server_and_client.md)
 - [Files](./files.md)
 - [Databases](./databases.md)
+- [Terminal](./terminal.md)
 
 # Process Standard Library
 

src/chess_app/chess_engine.md

@@ -131,9 +131,8 @@ Below, you'll find the full code for the CLI version of the app.
 You can build it and install it on a node using `kit`.
 You can interact with it in the terminal, primitively, like so (assuming your first node is `fake.os` and second is `fake2.os`):
 ```
-/a our@my_chess:my_chess:template.os
-/m {"NewGame": {"white": "fake.os", "black": "fake2.os"}}
-/m {"Move": {"game_id": "fake2.os", "move_str": "e2e4"}}
+m our@my_chess:my_chess:template.os '{"NewGame": {"white": "fake.os", "black": "fake2.os"}}'
+m our@my_chess:my_chess:template.os '{"Move": {"game_id": "fake2.os", "move_str": "e2e4"}}'
 ```
 (If you want to make a more ergonomic CLI app, consider parsing `body` as a string...)
 

src/cookbook/file_transfer.md

@@ -278,7 +278,7 @@ kit s -p 8081
 and then placing files in the `/vfs/file_transfer:file_transfer/files/` directory of the second (the `--home` dir path is specified as an argument to `boot-fake-node`), and sending a request from the first:
 
 ```
-/m fake2.os@file_transfer:file_transfer:template.os "ListFiles"
+m fake2.os@file_transfer:file_transfer:template.os "ListFiles"
 ```
 
 You should see a printed response.
@@ -1189,7 +1189,7 @@ There you have it!
 Try and run it, you can download a file with the command
 
 ```
-/m our@file_transfer:file_transfer:template.os {"Download": {"name": "dawg.jpeg", "target": "fake2.os@file_transfer:file_transfer:template.os"}}
+m our@file_transfer:file_transfer:template.os '{"Download": {"name": "dawg.jpeg", "target": "fake2.os@file_transfer:file_transfer:template.os"}}'
 ```
 
 replacing node name and file name!

src/cookbook/writing_scripts.md

@@ -71,3 +71,15 @@ For instance, the `echo` script is published as part of `terminal:sys`, so you c
 ```bash
 echo:terminal:sys Hello World!
 ```
+
+## Aliasing a Script
+If you are going to be calling your script very often, you can alias it to something shorter like so:
+```bash
+alias echo echo:terminal:sys
+```
+so now you can call `echo` like `echo Hello World!`.
+
+To remove the alias, simply run:
+```bash
+alias echo
+```

src/kit/boot-fake-node.md

@@ -23,7 +23,7 @@ kit boot-fake-node -h /tmp/kinode-fake-node-2 -p 8081 -f fake2.os
 
 # Send a message from fake2.os to fake.os
 # In the terminal of fake2.os:
-/hi fake.os hello!
+hi fake.os hello!
 
 # You should see "hello!" in the first node's terminal
 ```

src/my_first_app/chapter_1.md

@@ -282,13 +282,13 @@ kit start-package -p 8081
 To send a chat message from the first node, run the following in its terminal:
 
 ```
-/m our@my_chat_app:my_chat_app:template.os {"Send": {"target": "fake2.os", "message": "hello world"}}
+m our@my_chat_app:my_chat_app:template.os '{"Send": {"target": "fake2.os", "message": "hello world"}}'
 ```
 
 and replying, from the other terminal:
 
 ```
-/m our@my_chat_app:my_chat_app:template.os {"Send": {"target": "fake.os", "message": "wow, it works!"}}
+m our@my_chat_app:my_chat_app:template.os '{"Send": {"target": "fake.os", "message": "wow, it works!"}}'
 ```
 
 Messages can also be injected from the outside.

src/my_first_app/chapter_3.md

@@ -191,13 +191,13 @@ At this point, you can use the terminal to test your message types!
 First, try a hello. Get the address of your process by looking at the "started" printout that came from it in the terminal.
 As a reminder, these values are set in the `metadata.json` and `manifest.json` package files.
 ```bash
-/m our@<your_process>:<your_package>:<your_publisher> {"Hello": "hey there"}
+m our@<your_process>:<your_package>:<your_publisher> '{"Hello": "hey there"}'
 ```
 
 You should see the message text printed. Next, try a goodbye.
 This will cause the process to exit.
 ```bash
-/m our@<your_process>:<your_package>:<your_publisher> "Goodbye"
+m our@<your_process>:<your_package>:<your_publisher> '"Goodbye"'
 ```
 
 If you try to send another Hello now, nothing will happen, because the process has exited [(assuming you have set `on_exit: "None"`; with `on_exit: "Restart"` it will immediately start up again)](./chapter_2.md#aside-on_exit).

src/quick-start.md

@@ -39,10 +39,10 @@ kit inject-message my_chat_app:my_chat_app:template.os '{"Send": {"target": "fak
 
 # Or, from the terminal running one of the fake nodes:
 ## First fake node terminal:
-/m our@my_chat_app:my_chat_app:template.os {"Send": {"target": "fake2.os", "message": "hello world"}}
+m our@my_chat_app:my_chat_app:template.os '{"Send": {"target": "fake2.os", "message": "hello world"}}'
 
 ## Second fake node terminal:
-/m our@my_chat_app:my_chat_app:template.os {"Send": {"target": "fake.os", "message": "wow, it works!"}}
+m our@my_chat_app:my_chat_app:template.os '{"Send": {"target": "fake.os", "message": "wow, it works!"}}'
 ```
 
 ## Next steps

src/terminal.md

@@ -0,0 +1,79 @@
+# Terminal
+
+## Basic Usage and Utilities
+
+All commands in the terminal are calling scripts - a special kind of process.
+KinodeOS comes pre-loaded with a number of scripts useful for debugging and everyday use.
+These scripts are fully named `<SCRIPT>:terminal:sys` e.g `hi:terminal:sys`, but the distro [aliases](#alias---alias-a-script-name) these to short names, in this case just `hi`, for convenience.
+
+
+### `hi` - ping another kinode
+```bash
+Usage: hi <KNS_ID> <MESSAGE>
+Arguments:
+  <KNS_ID>  id of the node you want to message, e.g. some-node.os
+  <MESSAGE> any string
+Example:
+hi other-node.os Hello other-node.os! how are you?
+```
+
+### `m` - message a process
+```bash
+Usage: m <ADDRESS> <BODY>
+Arguments:
+  <ADDRESS> kns addresss 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
+```
+
+### `top` - display information about processes
+```bash
+Usage: top [PROCESS_ID]
+Arguments:
+  [PROCESS_ID] optional process id, just print information about this process
+Example:
+  top
+    - this prints all information for all processes
+  top terminal:terminal:sys
+    - this prints information for just the requested process
+```
+
+### `alias` - alias a script name
+```bash
+Usage: alias <NAME> [SCRIPT]
+Arguments:
+  <NAME>   the name you want to assign the script to
+  [SCRIPT] the script-id
+Example:
+  alias my-script my-script:my-package:my-name.os
+    - this lets you call my-script in the terminal as a shorthand
+  alias my-script
+    - this removes the my-script alias
+```
+
+### `cat` - print the contents of a file in your vfs
+```bash
+Usage: cat <FILE_PATH>
+Arguments:
+  <FILE_PATH> the file path in your vfs
+Example:
+  cat terminal:sys/pkg/scripts.json
+```
+
+### `echo` - print the argument
+`echo` is mostly an example script for developers to look at.
+```bash
+Usage: echo <MESSAGE>
+Arguments:
+  <MESSAGE> any string
+Example:
+  echo Hello World!
+```
+
+For more information on writing your own scripts, see the [cookbook](./cookbook/writing_scripts.md).