Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat: add docs for the CLI #81

Merged
merged 3 commits into from
Oct 28, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions pages/developers/_meta.json
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@
},
"blueprints": "Blueprints",
"services": "Use Cases",
"cli": "Tangle CLI",
"-- gadget-tutorial": {
"type": "separator",
"title": "Blueprint (AVS) Tutorials"
Expand Down
5 changes: 5 additions & 0 deletions pages/developers/cli/_meta.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
{
"installation": "Installation",
"quickstart": "Quickstart",
"reference": "Reference"
}
33 changes: 33 additions & 0 deletions pages/developers/cli/installation.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
---
title: Installation
---

# Tangle CLI Installation

There are multiple sources to install the CLI from:

1. Using the installation script (stable)

> The script supports Linux, MacOS, and Windows (WSL2)

```shell
$ curl --proto '=https' --tlsv1.2 -LsSf https://github.com/tangle-network/gadget/releases/download/cargo-tangle/v0.1.1-beta.7/cargo-tangle-installer.sh | sh
```

2. From [crates.io](https://crates.io) (stable)

```shell
$ cargo install cargo-tangle --force
```

3. From source (nightly)

```shell
$ cargo install cargo-tangle --git https://github.com/tangle-network/gadget --force
```

You can verify your installation with:

```shell
$ cargo tangle --version
```
48 changes: 48 additions & 0 deletions pages/developers/cli/quickstart.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,48 @@
---
title: Quickstart
---

# Tangle CLI Quickstart

## Pre-requisites

- [git](https://git-scm.org)
- Tangle CLI, see [installation](./installation.mdx)

## Creating a New Project

1. Open your terminal and run:

```shell
$ cargo tangle blueprint create --name <blueprint-name>
```

2. Follow the prompts to set up your project.

{/* TODO: Add a GIF */}
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can this not be added yet?


### Project Structure

After creation, your project will have the following structure:

```
<blueprint-name>/
├── src/
│ ├── lib.rs
│ └── main.rs
├── Cargo.toml
├── README.md
└── ...
```

## Deploying your Blueprint

Once you're ready to deploy your blueprint, simply:

```shell
export SIGNER="//Alice"
export EVM_SIGNER="0xcb6df9de1efca7a3998a8ead4e02159d5fa99c3e0d4fd6432667390bb4726854"
cargo tangle blueprint deploy
```

See [deploy command reference](./reference.mdx#deploy) for all options.
80 changes: 80 additions & 0 deletions pages/developers/cli/reference.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,80 @@
---
title: Reference
---

# Tangle CLI Reference

## Blueprint

The primary subcommand, used for building, testing, and deploying blueprints.

- Aliases: `bp`

Usage:

```shell
$ cargo tangle blueprint <subcommand>
```

### Subcommands

Note that unless specified, all arguments are optional.

#### Create

Creates a new blueprint

- Name: `create`
- Aliases: `c`
- Options:
- `--name` (**required**): The name of the blueprint
- `--repo`: The repo to pull the template from, by default this uses the hello world [blueprint template](https://github.com/tangle-network/blueprint-template)
- `--path`: The path to copy a template from, no default value

Usage:

Create a blueprint using the default template

```shell
$ cargo tangle blueprint create --name <name>
```

Create a blueprint using another template from git

```shell
$ cargo tangle blueprint create --name <name> --repo <git-repo-url>
```

#### Deploy

Deploy a blueprint to Tangle

- Name: `deploy`
- Aliases: `d`
- Options:
- `rpc-url`: The tangle RPC URL to use (default: `wss://rpc.tangle.tools`)
- `package`: The package to deploy, useful when using workspaces
- Environment Variables:
- `SIGNER` (**required**): The SURI of the Subtrate signer account
- `EVM_SIGNER` (**required**): The SURI of the EVM signer account

Usage:

Deploy a blueprint to a local Tangle node:

```bash
export SIGNER="//Alice"
export EVM_SIGNER="0xcb6df9de1efca7a3998a8ead4e02159d5fa99c3e0d4fd6432667390bb4726854"
cargo tangle blueprint deploy --rpc-url <rpc-url>
```

Where `<rpc-url>` will likely be `ws://localhost:9944`.

#### Generate Keys

- Name: `generate-keys`
- Options:
- `key-type` (alias: `k`) (**required**): The key type to generate (sr25519, ecdsa, bls_bn254, ed25519, bls381)
- `path` (alias: `p`): The path to write the generated keypair to. If not provided, the keypair will be written solely to stdout
- `seed` (alias: `s`): The SURI/seed to generate the keypair from. If not provided, a random keypair will be generated
- `show-secret`: Denotes that the Private Key should also be printed to stdout. If not provided, only the public key will be printed
54 changes: 8 additions & 46 deletions pages/developers/getting-started.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -13,47 +13,15 @@ Before you begin, ensure you have the following installed:
- [Rust](https://www.rust-lang.org/tools/install)
- [Forge](https://getfoundry.sh)
- [Tangle](https://github.com/tangle-network/tangle?tab=readme-ov-file#-getting-started-)
- `cargo-tangle` CLI tool
- [`cargo-tangle`](./cli/installation.mdx) CLI tool

To install the Tangle CLI, run:
## Creating my First Blueprint

```bash
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/tangle-network/gadget/releases/download/cargo-tangle/v0.1.1-beta.7/cargo-tangle-installer.sh | sh
```

Alternatively, install from source:

```bash
cargo install cargo-tangle --git https://github.com/tangle-network/gadget --force
```

## Creating a New Project

1. Open your terminal and run:

```bash
cargo tangle blueprint create --name hello-world-blueprint
```

2. Follow the prompts to set up your project.
See the [CLI Quickstart](./cli/quickstart.mdx) for instructions on creating a [blueprint](./blueprints.mdx).

## Project Structure
### Key Files

After creation, your project will have the following structure:

```
hello-world-blueprint/
├── src/
│ ├── lib.rs
│ └── main.rs
├── Cargo.toml
├── README.md
└── <other files>
```

Let's look at the key files:

### src/lib.rs
#### src/lib.rs

This file contains the core logic of your Blueprint, including job definitions, report structures, and event listeners. Here's an example of a simple "Hello World" job:

Expand Down Expand Up @@ -82,7 +50,7 @@ pub fn say_hello(who: Option<String>) -> Result<String, Infallible> {

This job takes an optional `who` parameter and returns a greeting.

### src/main.rs
#### src/main.rs

This file serves as the entry point for your Actively Validated Service (AVS) node. It sets up the runtime environment, initializes the necessary components, and starts the event watcher. Here's a breakdown of its key responsibilities:

Expand Down Expand Up @@ -151,15 +119,9 @@ cargo build

This command compiles your Rust code and checks for any errors.

## Deploying Your Blueprint

To deploy your Blueprint to the Tangle network, use:

```bash
cargo tangle gadget deploy
```
### Deploying Your Blueprint

This command will package your Blueprint and deploy it to the Tangle network test environment.
See [deploying your blueprint](./cli/quickstart.mdx#deploying-your-blueprint).

## Next Steps

Expand Down
Loading