AD4M Command Line Tools

AD4M provides two command-line tools that enable developers to work with AD4M in headless and scripting scenarios:

ad4m-executor: A full AD4M node implementation (similar to the Launcher but without UI)
ad4m: A client tool for interacting with any AD4M executor

Installation

For build and installation instructions, please refer to the CLI README (opens in a new tab).

The AD4M Executor

The ad4m-executor binary runs a complete AD4M node, making it ideal for:

Server deployments
Automated testing
CI/CD pipelines
Headless applications
System integration

Unlike the Launcher which provides a GUI, the executor is designed for command-line and programmatic interaction.

Authentication & Security

The executor uses a secure authentication handshake system. When a client attempts to connect, the executor generates a random number that must be used to complete the authentication. This number is printed in the executor's logs.

For automated scenarios where manual authentication is impractical, you can provide an admin credential that bypasses the handshake:

ad4m-executor run --admin-credential your-secret-here

This is particularly useful for:

Scripts managing the executor
CI/CD pipelines
Integration testing
Management UIs (the Launcher uses this internally)

Configuration Parameters

The executor supports various configuration parameters to customize its behavior. Here are the key parameters:

# Basic configuration
ad4m-executor run \
  --gql-port 12000 \           # Main GraphQL API port (default: 4000)
  --admin-credential secret \   # Bypass authentication handshake
  --app-data-path ./data \     # Custom data directory (default: ~/.ad4m)
  --run-dapp-server true       # Run the DApp server (default: false)
 
# Holochain-related configuration
  --hc-admin-port 1234 \       # Holochain admin interface port (default: 1234)
  --hc-app-port 8888 \         # Holochain app interface port (default: 8888)
  --hc-use-bootstrap true \    # Use bootstrap service (default: true)
  --hc-use-proxy true \        # Use proxy for Holochain (default: true)
  --hc-proxy-url url \         # Custom proxy URL
  --hc-bootstrap-url url       # Custom bootstrap URL

Running Multiple Executors

For development and testing, you might want to run multiple AD4M executors on the same machine. Here's how to configure two executors to run simultaneously:

# First executor (default ports)
ad4m-executor run
 
# Second executor (custom ports)
ad4m-executor run \
  --gql-port 14000 \           # Different GraphQL port
  --hc-admin-port 2234 \       # Different Holochain admin port
  --hc-app-port 9888 \         # Different Holochain app port
  --app-data-path ~/.ad4m2     # Separate data directory

When connecting to the second executor with the client, specify the custom GraphQL port:

ad4m --executor-url http://localhost:14000 agent me

Basic Usage

Initialize a new AD4M instance:

ad4m-executor init

This creates the necessary directory structure and configuration in ~/.ad4m.

Start the executor:

ad4m-executor run

(Optional) Run local Holochain services:

ad4m-executor run-local-hc-services

This starts the bootstrap and signaling services required by Holochain-based languages.

The AD4M Client: A Tutorial

The ad4m client tool provides a complete interface to interact with a running executor. Let's explore its features through practical examples.

Getting Started

First, ensure you have an executor running (see above).
For a fresh installation, generate a new agent:

ad4m agent generate

This will prompt you for a password to encrypt your agent's keys.

On subsequent starts, unlock your agent:

ad4m agent unlock

View your agent's information:

ad4m agent me

This shows your DID, public perspective, and messaging capabilities.

Working with Perspectives

Perspectives are semantic spaces where you can store and query linked data.

Create a new perspective:

ad4m perspectives create

List all perspectives:

ad4m perspectives

Add links to a perspective:

ad4m perspectives add-link <perspective-UUID> "Alice" "knows" "Bob"

Query links:

ad4m perspectives query-links <perspective-UUID> --source "Alice"

Watch for real-time changes:

ad4m perspectives watch <perspective-UUID>

Interactive Data Manipulation

The REPL provides an interactive environment for working with perspective data:

ad4m perspectives repl <perspective-UUID>

In the REPL, you can:

# Add links
add Alice knows Bob

# Query with variables
?Person knows Bob

# Create subjects
new Person(alice)
subject(alice)[name] = "Alice Smith"
subject(alice)[interests] <= "coding"

# View subject data
subject(alice)

# Run Prolog queries
friend(X, Y), hobby(Y, 'coding')

Managing Languages

Languages in AD4M are pluggable protocols that define how data is stored and shared.

List installed languages:

ad4m languages all

Get language details:

ad4m languages by-address <language-address>

Publish a new language:

ad4m languages publish ./my-language --name "My Language" --description "A custom language"

Building Communities with Neighborhoods

Neighborhoods are shared spaces built on perspectives and languages.

Create a neighborhood:

ad4m neighbourhoods create <perspective-UUID> <link-language>

This publishes your perspective as a shared space others can join.

Join an existing neighborhood:

ad4m neighbourhoods join <neighbourhood-url>

Runtime Management

Monitor and manage your AD4M node:

View runtime information:

ad4m runtime info

Manage trusted agents:

# Add trusted agents
ad4m runtime add-trusted-agents did:key:123...
 
# List trusted agents
ad4m runtime trusted-agents

Manage friends:

# Add friends
ad4m runtime add-friends did:key:123...
 
# List friends
ad4m runtime friends

View logs:

ad4m log

Expression Management

Work with language-specific expressions:

Create an expression:

ad4m expression create <language-address> '{"key": "value"}'

Retrieve expressions:

# Get parsed expression
ad4m expression get <url>
 
# Get raw data
ad4m expression get-raw <url>

Advanced Features

For development and testing:

# Generate bootstrap seed
ad4m dev generate-bootstrap <agent-path> <passphrase> <seed-proto>
 
# Test expression language
ad4m dev publish-and-test-expression-language <language-path> <data>

For a complete list of commands and their options:

ad4m --help
ad4m <command> --help

Local AI inference with AD4M Modules