Skip to content

Commit

Permalink
Improve ad4m cli crate description and readme
Browse files Browse the repository at this point in the history
  • Loading branch information
lucksus committed Mar 22, 2024
1 parent f9c6a07 commit 7eaa034
Show file tree
Hide file tree
Showing 2 changed files with 73 additions and 27 deletions.
8 changes: 4 additions & 4 deletions cli/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -4,12 +4,12 @@ name = "ad4m"
version = "0.9.0-rc8"

edition = "2021"
authors = ["Nicolas Luck <[email protected]>"]
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"

Expand Down
92 changes: 69 additions & 23 deletions cli/README.md
Original file line number Diff line number Diff line change
@@ -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).

0 comments on commit 7eaa034

Please sign in to comment.