Developer Guides
Using the AD4M CLI

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.

run requires an admin credential. Whoever presents it has every capability and skips the handshake, which is how scripts, CI pipelines and management UIs (the Launcher generates one on each start) talk to the executor. Pass it through the environment, so it does not show up in ps or the shell history:

export AD4M_ADMIN_CREDENTIAL="$(cat /path/to/admin-credential)"
ad4m-executor run

Without a credential, or with an empty one, run exits with an error naming both ways out. For tests and local development there is an explicit opt-out:

ad4m-executor run --insecure-no-admin-credential   # or AD4M_INSECURE_NO_ADMIN_CREDENTIAL=true

In that mode an empty token is the operator on a loopback-bound API: any client that can reach the executor's loopback port, including a proxy or tunnel on the same host that sets no forwarding header, has full admin access. On a network-bound API (--localhost false, or TLS) a caller with no token is anonymous. Never use it on an executor other users or other machines can reach.

Configuration Parameters

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

# Basic configuration
ad4m-executor run \
  --port 12000 \
  --app-data-path ./data \
  --run-dapp-server true
# --port: API port (default: 12000)
# AD4M_ADMIN_CREDENTIAL (or --admin-credential): required, see above
# --app-data-path: Custom data directory (default: ~/.ad4m)
# --run-dapp-server: Run the DApp server (default: false)
 
# Holochain-related configuration
ad4m-executor run \
  --hc-admin-port 1234 \
  --hc-app-port 8888 \
  --hc-use-bootstrap true \
  --hc-use-proxy true \
  --hc-proxy-url url \
  --hc-bootstrap-url url
# --hc-admin-port: Holochain admin interface port (default: 1234)
# --hc-app-port: Holochain app interface port (default: 8888)
# --hc-use-bootstrap: Use bootstrap service (default: true)
# --hc-use-proxy: Use proxy for Holochain (default: true)
# --hc-proxy-url: Custom proxy URL
# --hc-bootstrap-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:

# Both need AD4M_ADMIN_CREDENTIAL in the environment (see above)
# First executor (default ports)
ad4m-executor run
 
# Second executor (custom ports)
ad4m-executor run \
  --port 14000 \
  --hc-admin-port 2234 \
  --hc-app-port 9888 \
  --app-data-path ~/.ad4m2
# --port: Different API port
# --hc-admin-port: Different Holochain admin port
# --hc-app-port: Different Holochain app port
# --app-data-path: Separate data directory

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

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

Basic Usage

  1. Initialize a new AD4M instance:
ad4m-executor init

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

  1. Start the executor with an admin credential:
export AD4M_ADMIN_CREDENTIAL="$(cat /path/to/admin-credential)"
ad4m-executor run
  1. (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

  1. First, ensure you have an executor running (see above).

  2. For a fresh installation, generate a new agent:

ad4m agent generate

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

  1. On subsequent starts, unlock your agent:
ad4m agent unlock
  1. 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.

  1. Create a new perspective:
ad4m perspectives create
  1. List all perspectives:
ad4m perspectives
  1. Add links to a perspective:
ad4m perspectives add-link <perspective-UUID> "Alice" "knows" "Bob"
  1. Query links:
ad4m perspectives query-links <perspective-UUID> --source "Alice"
  1. 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.

  1. List installed languages:
ad4m languages all
  1. Get language details:
ad4m languages by-address <language-address>
  1. 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.

  1. Create a neighborhood:
ad4m neighbourhoods create <perspective-UUID> <link-language>

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

  1. Join an existing neighborhood:
ad4m neighbourhoods join <neighbourhood-url>

Runtime Management

Monitor and manage your AD4M node:

  1. View runtime information:
ad4m runtime info
  1. Manage trusted agents:
# Add trusted agents
ad4m runtime add-trusted-agents did:key:123...
 
# List trusted agents
ad4m runtime trusted-agents
  1. Manage friends:
# Add friends
ad4m runtime add-friends did:key:123...
 
# List friends
ad4m runtime friends
  1. View logs:
ad4m log

Expression Management

Work with language-specific expressions:

  1. Create an expression:
ad4m expression create <language-address> '{"key": "value"}'
  1. 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
MCP Server (AI Agent Integration)Executor config file