Improve ad4m cli crate description and readme

cli/Cargo.toml

@@ -4,12 +4,12 @@ name = "ad4m"
 version = "0.9.0-rc8"
 
 edition = "2021"
-authors = ["Nicolas Luck <nicolas@coasys.org>"]
-description = "A command-line interface to AD4M (i.e. the AD4M executor) - https://ad4m.dev"
-keywords = ["ad4m", "perspect3vism", "cli"]
+authors = ["Nicolas Luck <nicolas.luck@coasys.org>"]
+description = "Executables for running, developing and debugging an ADAM node/agent"
+keywords = ["ad4m", "coasys", "cli", "holochain"]
 license = "CAL-1.0"
 homepage = "https://ad4m.dev"
-repository = "https://github.com/perspect3vism/ad4m"
+repository = "https://github.com/coasys/ad4m"
 documentation = "https://docs.ad4m.dev"
 readme = "README.md"
 

cli/README.md

@@ -1,65 +1,111 @@
-# AD4M command-line interface
+# AD4M Executables
 
 ![](screenshots/banner.png)
 
-This is a cmd-tool (`ad4m`) that uses the Rust implementation of the AD4M GraphQL interface wrapper (https://crates.io/crates/ad4m-client).
-As such, it's a command-line based generic UI intended for development and scripting use and remote-controlling
-of AD4M and all it's features.
+This package contains command line tools for the Agent-Centric Distributed Application Meta-ontology (ADAM, aka AD4M), a framework for building interoperable, decentralized applications. It provides developers with the tools to control and script the functionalities of AD4M, leveraging the power of the Rust implementation of the AD4M GraphQL interface wrapper.
 
-## Build
+The purpose of these CLIs is development, scripting, and remote control of AD4M features,
+as well as programatic setup and running of ADAM agents.
+
+## Installation
+
+Install AD4M using Cargo, Rust's package manager:
 ```
-cargo build
+cargo install ad4m
 ```
 
-## Start & Run AD4M Agent
+This command installs two binaries:
+- `ad4m`: The client for interacting with the executor.
+- `ad4m-executor`: The executor that runs the AD4M agent.
 
-Ad4m comes with two binaries
-- `ad4m` - one for using the client to interact with execuror
-- `ad4m-executor` - one for running the executor
-
-## Usage with executor
+## Getting Started
 
+Initialize the AD4M executor with:
 ```
 ad4m-executor init
 ```
 
+This will create a new agent/config directory in ~/.ad4m.
+
+Run the executor (i.e. the ADAM agent/node) using:
 ```
 ad4m-executor run
 ```
 
-## Usage with client
+## Interacting with AD4M
+
+Use the `ad4m` client to interact with the executor. Here are some common commands:
+
+### Generate and unlock agent
+A fresh install will first need a new agent to be created, which requires a password
+which is used to encrypt the agent's keys:
+
+```
+ad4m agent generate
+```
+
+This command will prompt for a new password.
+Future runs of the executor require the wallet to be unlocked with
+
+```
+ad4m agent unlock
+```
+providing the same password.
+
 
 Show all perspectives:
 ```
 ad4m perspectives
 ```
 
+### Query Perspectives
 ![](screenshots/perspectives.png)
 
-Query links of a perspective:
+Query links of a perspective by its UUID:
 ```
-ad4m perspectives query-links 359a0a8f-fecc-43a3-9c18-27ee1e41efe2
+ad4m perspectives query-links <perspective-UUID>
 ```
 
 ![](screenshots/query-links.png)
 
-Watch changes of a perspective:
+Watch changes of a perspective in real-time:
 ```
-ad4m perspectives watch 359a0a8f-fecc-43a3-9c18-27ee1e41efe2
+ad4m perspectives watch <perspective-UUID>
 ```
+
+### Creating neighbourhoods
 ![](screenshots/watch.png)
 
-Clone and publish a language
+Clone and publish a language from a template:
 ```
-ad4m languages apply-template-and-publish QmeBD9n9Z5yZsegxArToww5zmwtPpojXN6zXJsi7WwMUa8
+ad4m languages apply-template-and-publish <language-template-hash>
 ```
 
-Publish Perspective as Neighbourhood
+Publish a perspective as a Neighbourhood:
 ```
-ad4m neighbourhoods create da0333e9-275d-4b57-8851-0d1678d75a1c QmNrp4iKy1TAHqwQb2SZtApA2EYHK4UhRfgvV1mfJKEJSP
+ad4m neighbourhoods create <perspective-UUID> <neighbourhood-template-hash>
 ```
 
-See help for all the other commands:
+For a full list of commands and their explanations, use:
 ```
-ad4m
+ad4m --help
 ```
+
+## Contributing
+
+Contributions to AD4M are welcome! Please read our contributing guidelines and submit pull requests to our repository.
+
+## License
+
+AD4M is licensed under the [CAL-1.0](LICENSE).
+
+## Screenshots
+
+![](screenshots/banner.png)
+
+![](screenshots/query-links.png)
+![](screenshots/watch.png)
+
+## More Information
+
+For more information on AD4M and ADAM, visit our [official website](https://ad4m.dev) or check out the [core documentation](https://docs.ad4m.dev).