Aqua CLI

The Aqua CLI tooling ships two binaries built with Rust:

aqua-cli - Full-featured tool for creating, signing, witnessing, verifying, and managing Aqua trees
aqua-notary - Simplified notary for signing files, linking identities, and publishing to a registry

Installation

Code

bash

1git clone https://github.com/inblockio/aqua-cli-rs
2cd aqua-cli-rs/aqua-rs-cli
3cargo build --release

After building, the binaries are located at:

./target/release/aqua-cli
./target/release/aqua-notary

For development builds (cargo build without --release), use ./target/debug/ instead.

Throughout this guide, commands are shown as aqua-cli and aqua-notary for brevity. Replace with the full path (e.g. ./target/release/aqua-cli) when running locally.

Configuration

Keys File

Create a keys.json with the credentials you need:

Code

json

1{
2  "signing": {
3    "mnemonic": "<BIP39 mnemonic phrase>",
4    "did_key": "<0x-prefixed Ed25519 private key>",
5    "p256_key": "<0x-prefixed P-256 private key>",
6    "secp256k1_key": "<0x-prefixed secp256k1 private key>"
7  },
8  "timestamp": {
9    "nostr_sk": "<Nostr secret key>"
10  }
11}

You only need to populate the fields for the signing/witness methods you intend to use.

Key resolution order: --keys-file flag → keys_file env var → keys.json in the current directory.

Environment Variables

Create a .env file (or export directly):

Code

bash

1# Path to keys file
2keys_file=keys.json
3 
4# Ethereum witnessing
5alchemy_key=<your Alchemy API key>
6aqua_network=sepolia          # sepolia | holesky | mainnet
7rpc_url=<optional custom RPC URL>
8 
9# TSA witnessing (optional)
10tsa_url=<custom TSA endpoint>
11 
12# Twilio for email/phone verification (optional)
13TWILIO_ACCOUNT_SID=
14TWILIO_AUTH_TOKEN=
15TWILIO_VERIFY_SERVICE_SID=

Security Notice

Never commit your keys.json or .env files to version control.

aqua-cli

Notarize a File

Create an Aqua tree from any source file:

Code

bash

1aqua-cli -f document.pdf

This generates document.pdf.aqua.json containing the genesis revision. Use --minimal to skip anchor/template revisions and produce a single-revision genesis.

Verify

Code

bash

1aqua-cli -a tree.aqua.json

Use --level 1 for strict validation or --level 2 (default) for standard validation. Add -v for verbose output.

Sign

Code

bash

1# DID Ed25519 signing
2aqua-cli -s tree.aqua.json --sign-type did -k keys.json
3 
4# BIP39 mnemonic signing
5aqua-cli -s tree.aqua.json --sign-type cli -k keys.json
6 
7# P-256 signing
8aqua-cli -s tree.aqua.json --sign-type p256 -k keys.json
9 
10# MetaMask-style secp256k1 signing
11aqua-cli -s tree.aqua.json --sign-type metamask -k keys.json

Witness

Anchor a tree to an external timestamping service:

Code

bash

1# Ethereum on-chain (Sepolia, Holesky, or Mainnet)
2aqua-cli -w tree.aqua.json --witness-eth -k keys.json
3 
4# Nostr network
5aqua-cli -w tree.aqua.json --witness-nostr -k keys.json
6 
7# TSA (DigiCert timestamp authority)
8aqua-cli -w tree.aqua.json --witness-tsa

Link Trees

Combine child trees into a parent tree:

Code

bash

1aqua-cli --link parent.aqua.json child1.aqua.json child2.aqua.json

Delete Last Revision

Code

bash

1aqua-cli -d tree.aqua.json

Create Objects

Create genesis object revisions from built-in templates:

Code

bash

1# List available templates
2aqua-cli --list-templates
3 
4# Create an object with a template and JSON payload
5aqua-cli --create-object --template-name email --payload '{"email":"user@example.com"}'
6 
7# Or use a payload file
8aqua-cli --create-object --template-name file --payload data.json

Built-in templates include: file, domain, email, name, phone, attestation, timestamp, multi-signer, trust-assertion, wallet-identification, access-grant, vendor-registration, template-registration, alias-registration, plugin-registration.

DAG Branching

Target a specific revision for branching with --previous-hash:

Code

bash

1aqua-cli -s tree.aqua.json --sign-type did -k keys.json --previous-hash 0xabc123...

Output Formats

Export results as JSON, HTML, or PDF:

Code

bash

1aqua-cli -a tree.aqua.json -o report.html
2aqua-cli -a tree.aqua.json -o report.pdf

Forest & Daemon

The forest system lets you work with multiple Aqua trees simultaneously, resolving cross-tree dependencies like links, attestations, and templates.

Ephemeral Forest

Load multiple trees into an in-memory forest:

Code

bash

1aqua-cli --forest tree1.aqua.json tree2.aqua.json tree3.aqua.json

Add trust store entries with --trust:

Code

bash

1aqua-cli --forest *.aqua.json --trust did:key:z6Mk... 3

Trust levels: 1 = marginal, 2 = full, 3 = ultimate.

Persistent Daemon

Keep the forest alive as a background daemon with an idle timeout:

Code

bash

1# Start daemon (default 600s idle timeout)
2aqua-cli --forest *.aqua.json --daemon
3 
4# Custom timeout (seconds)
5aqua-cli --forest *.aqua.json --daemon 1800

The daemon listens on a Unix socket at /tmp/aqua-forest-{PID}.sock and provides an interactive REPL on stdin. Supported commands: ingest, help, quit.

Connect to a Daemon

Open an interactive session to a running daemon:

Code

bash

1aqua-cli --connect <PID>

Push Results to a Daemon

Send operation results from any aqua-cli command into a running daemon's forest:

Code

bash

1aqua-cli -s tree.aqua.json --sign-type did -k keys.json --target <PID>

aqua-notary

A simplified CLI for signing files, managing identity, and publishing to a notary registry.

Generate Keys

Code

bash

1aqua-notary keygen

Generates an Ed25519 key pair and saves it to ~/.aqua/keys.json. Use --output for a custom path or --force to overwrite existing keys.

Sign a File

Code

bash

1aqua-notary sign document.pdf

Creates or updates document.pdf.aqua.json. Defaults to DID signing. Use --sign-type to choose did, cli, or p256.

Verify a File

Code

bash

1aqua-notary verify document.pdf

Inspect a Tree

Code

bash

1aqua-notary inspect document.pdf

Displays the tree structure with all revisions, types, timestamps, and signers.

Link GitHub Identity

Bind your GitHub account to your DID using the OAuth Device Flow:

Code

bash

1aqua-notary identity github

This walks you through GitHub authentication, creates a public gist as verifiable proof, and saves the identity claim to ~/.aqua/identity_github.aqua.json.

Publish to Registry

Code

bash

1aqua-notary publish document.pdf

Signs the file (if not already signed), creates a GitHub gist, and submits to a notary server. Use --server to specify a custom registry URL (defaults to http://localhost:1984).

Requires a GitHub identity claim - run aqua-notary identity github first.

CLI Info

Code

bash

1aqua-cli -i

Displays version, supported signing methods, witness types, and environment configuration.

Repository

GitHub: github.com/inblockio/aqua-cli-rs

Built using the Aqua Rust SDK for Aqua Protocol v4.

The Aqua CLI tooling ships two binaries built with Rust:

aqua-cli - Full-featured tool for creating, signing, witnessing, verifying, and managing Aqua trees
aqua-notary - Simplified notary for signing files, linking identities, and publishing to a registry

Installation

Code

bash

1git clone https://github.com/inblockio/aqua-cli-rs
2cd aqua-cli-rs/aqua-rs-cli
3cargo build --release

After building, the binaries are located at:

./target/release/aqua-cli
./target/release/aqua-notary

For development builds (cargo build without --release), use ./target/debug/ instead.

Throughout this guide, commands are shown as aqua-cli and aqua-notary for brevity. Replace with the full path (e.g. ./target/release/aqua-cli) when running locally.

Configuration

Keys File

Create a keys.json with the credentials you need:

Code

json

1{
2  "signing": {
3    "mnemonic": "<BIP39 mnemonic phrase>",
4    "did_key": "<0x-prefixed Ed25519 private key>",
5    "p256_key": "<0x-prefixed P-256 private key>",
6    "secp256k1_key": "<0x-prefixed secp256k1 private key>"
7  },
8  "timestamp": {
9    "nostr_sk": "<Nostr secret key>"
10  }
11}

You only need to populate the fields for the signing/witness methods you intend to use.

Key resolution order: --keys-file flag → keys_file env var → keys.json in the current directory.

Environment Variables

Create a .env file (or export directly):

Code

bash

1# Path to keys file
2keys_file=keys.json
3 
4# Ethereum witnessing
5alchemy_key=<your Alchemy API key>
6aqua_network=sepolia          # sepolia | holesky | mainnet
7rpc_url=<optional custom RPC URL>
8 
9# TSA witnessing (optional)
10tsa_url=<custom TSA endpoint>
11 
12# Twilio for email/phone verification (optional)
13TWILIO_ACCOUNT_SID=
14TWILIO_AUTH_TOKEN=
15TWILIO_VERIFY_SERVICE_SID=

Security Notice

Never commit your keys.json or .env files to version control.

aqua-cli

Notarize a File

Create an Aqua tree from any source file:

Code

bash

1aqua-cli -f document.pdf

This generates document.pdf.aqua.json containing the genesis revision. Use --minimal to skip anchor/template revisions and produce a single-revision genesis.

Verify

Code

bash

1aqua-cli -a tree.aqua.json

Use --level 1 for strict validation or --level 2 (default) for standard validation. Add -v for verbose output.

Sign

Code

bash

1# DID Ed25519 signing
2aqua-cli -s tree.aqua.json --sign-type did -k keys.json
3 
4# BIP39 mnemonic signing
5aqua-cli -s tree.aqua.json --sign-type cli -k keys.json
6 
7# P-256 signing
8aqua-cli -s tree.aqua.json --sign-type p256 -k keys.json
9 
10# MetaMask-style secp256k1 signing
11aqua-cli -s tree.aqua.json --sign-type metamask -k keys.json

Witness

Anchor a tree to an external timestamping service:

Code

bash

1# Ethereum on-chain (Sepolia, Holesky, or Mainnet)
2aqua-cli -w tree.aqua.json --witness-eth -k keys.json
3 
4# Nostr network
5aqua-cli -w tree.aqua.json --witness-nostr -k keys.json
6 
7# TSA (DigiCert timestamp authority)
8aqua-cli -w tree.aqua.json --witness-tsa

Link Trees

Combine child trees into a parent tree:

Code

bash

1aqua-cli --link parent.aqua.json child1.aqua.json child2.aqua.json

Delete Last Revision

Code

bash

1aqua-cli -d tree.aqua.json

Create Objects

Create genesis object revisions from built-in templates:

Code

bash

1# List available templates
2aqua-cli --list-templates
3 
4# Create an object with a template and JSON payload
5aqua-cli --create-object --template-name email --payload '{"email":"user@example.com"}'
6 
7# Or use a payload file
8aqua-cli --create-object --template-name file --payload data.json

DAG Branching

Target a specific revision for branching with --previous-hash:

Code

bash

1aqua-cli -s tree.aqua.json --sign-type did -k keys.json --previous-hash 0xabc123...

Output Formats

Export results as JSON, HTML, or PDF:

Code

bash

1aqua-cli -a tree.aqua.json -o report.html
2aqua-cli -a tree.aqua.json -o report.pdf

Forest & Daemon

The forest system lets you work with multiple Aqua trees simultaneously, resolving cross-tree dependencies like links, attestations, and templates.

Ephemeral Forest

Load multiple trees into an in-memory forest:

Code

bash

1aqua-cli --forest tree1.aqua.json tree2.aqua.json tree3.aqua.json

Add trust store entries with --trust:

Code

bash

1aqua-cli --forest *.aqua.json --trust did:key:z6Mk... 3

Trust levels: 1 = marginal, 2 = full, 3 = ultimate.

Persistent Daemon

Keep the forest alive as a background daemon with an idle timeout:

Code

bash

1# Start daemon (default 600s idle timeout)
2aqua-cli --forest *.aqua.json --daemon
3 
4# Custom timeout (seconds)
5aqua-cli --forest *.aqua.json --daemon 1800

The daemon listens on a Unix socket at /tmp/aqua-forest-{PID}.sock and provides an interactive REPL on stdin. Supported commands: ingest, help, quit.

Connect to a Daemon

Open an interactive session to a running daemon:

Code

bash

1aqua-cli --connect <PID>

Push Results to a Daemon

Send operation results from any aqua-cli command into a running daemon's forest:

Code

bash

1aqua-cli -s tree.aqua.json --sign-type did -k keys.json --target <PID>

aqua-notary

A simplified CLI for signing files, managing identity, and publishing to a notary registry.

Generate Keys

Code

bash

1aqua-notary keygen

Generates an Ed25519 key pair and saves it to ~/.aqua/keys.json. Use --output for a custom path or --force to overwrite existing keys.

Sign a File

Code

bash

1aqua-notary sign document.pdf

Creates or updates document.pdf.aqua.json. Defaults to DID signing. Use --sign-type to choose did, cli, or p256.

Verify a File

Code

bash

1aqua-notary verify document.pdf

Inspect a Tree

Code

bash

1aqua-notary inspect document.pdf

Displays the tree structure with all revisions, types, timestamps, and signers.

Link GitHub Identity

Bind your GitHub account to your DID using the OAuth Device Flow:

Code

bash

1aqua-notary identity github

This walks you through GitHub authentication, creates a public gist as verifiable proof, and saves the identity claim to ~/.aqua/identity_github.aqua.json.

Publish to Registry

Code

bash

1aqua-notary publish document.pdf

Signs the file (if not already signed), creates a GitHub gist, and submits to a notary server. Use --server to specify a custom registry URL (defaults to http://localhost:1984).

Requires a GitHub identity claim - run aqua-notary identity github first.

CLI Info

Code

bash

1aqua-cli -i

Displays version, supported signing methods, witness types, and environment configuration.

Repository

GitHub: github.com/inblockio/aqua-cli-rs

Built using the Aqua Rust SDK for Aqua Protocol v4.

Documentation

Aqua CLI

Installation

Configuration

Keys File

Environment Variables

aqua-cli

Notarize a File

Verify

Sign

Witness

Link Trees

Delete Last Revision

Create Objects

DAG Branching

Output Formats

Forest & Daemon

Ephemeral Forest

Persistent Daemon

Connect to a Daemon

Push Results to a Daemon

aqua-notary

Generate Keys

Sign a File

Verify a File

Inspect a Tree

Link GitHub Identity

Publish to Registry

CLI Info

Repository

Documentation

Aqua CLI

Installation

Configuration

Keys File

Environment Variables

aqua-cli

Notarize a File

Verify

Sign

Witness

Link Trees

Delete Last Revision

Create Objects

DAG Branching

Output Formats

Forest & Daemon

Ephemeral Forest

Persistent Daemon

Connect to a Daemon

Push Results to a Daemon

aqua-notary

Generate Keys

Sign a File

Verify a File

Inspect a Tree

Link GitHub Identity

Publish to Registry

CLI Info

Repository