CLI Reference

AGENIUM includes a command-line interface for common operations.

Installation

The CLI is automatically installed with the package:

bash

npm install -g agenium

Or use npx without installing:

bash

npx agenium <command>

Global Options

bash

agenium <command> [options]

Options:
  --help, -h              Show help
  --config, -c <file>     Config file (default: ./agenium.json)
  --version, -v           Show version

Commands

`init`

Initialize a new agent in the current directory.

bash

agenium init

What it does:

Creates agenium.json configuration file
Creates .agenium/ data directory
Generates a unique agent ID

Output:

Initializing Agenium agent...

✅ Created agenium.json
✅ Created ./.agenium/

Agent ID: agent-1a2b3c4d5e

Next steps:
  1. Edit agenium.json to configure your agent
  2. Run: agenium status
  3. Connect: agenium connect agent://target

Generated config:

json

{
  "agentId": "agent-1a2b3c4d5e",
  "version": "0.1.0",
  "dataDir": "./.agenium",
  "dnsServer": "185.204.169.26",
  "dnsPort": 3000,
  "metricsPort": 9090,
  "metricsHost": "127.0.0.1",
  "timeouts": {
    "dnsLookupMs": 10000,
    "handshakeMs": 10000,
    "requestMs": 30000
  }
}

Options:

None

Exit codes:

0 - Success
1 - Error (e.g., agenium.json already exists)

`resolve`

Resolve an agent URI to its endpoint via DNS.

bash

agenium resolve <agent://uri>

Arguments:

<agent://uri> - Agent URI to resolve (e.g., agent://search)

Examples:

bash

# Resolve by full URI
agenium resolve agent://search

# Resolve by name (agent:// prefix optional)
agenium resolve search

Output:

Resolving agent://search...
✅ Resolved: search
  Endpoint: https://search.agenium.net:8443
  Host:     search.agenium.net:8443
  PubKey:   sLCkXG4FN7N4gH5K...
  Caps:     messaging, streaming

Error output:

Resolving agent://unknown...
❌ Could not resolve: agent://unknown
  NOT_FOUND: Agent 'unknown' not found in registry

Exit codes:

0 - Successfully resolved
1 - Resolution failed

`connect`

Connect to a remote agent (with DNS resolution).

bash

agenium connect <agent://uri>

Arguments:

<agent://uri> - Agent URI to connect to

Examples:

bash

agenium connect agent://bob
agenium connect search

Output:

Connecting to agent://bob...
  Resolving DNS...
✅ Resolved: bob.example.com:8443

⚠️  Full connection not yet implemented in CLI.
   Use the Node.js API for programmatic connections:

   import { createAgent } from "agenium";
   const agent = await createAgent({ agentId: "agent-1a2b3c4d5e" });
   const session = await agent.connect("agent://bob");

Requirements:

agenium.json must exist (run agenium init first)

Exit codes:

0 - DNS resolution successful
1 - Error (DNS failed or no config)

`status`

Show local agent status and configuration.

bash

agenium status

Output:

Agenium Status

  Agent ID:    agent-1a2b3c4d5e
  Version:     0.1.0
  Data Dir:    ./.agenium
  DNS Server:  185.204.169.26
  Metrics:     127.0.0.1:9090
  Bug Reports: http://localhost:3100/api/bug-reports
  Database:    ✅ ./.agenium/sessions.db

Connectivity:
  DNS Server:  ✅ Reachable (127ms)

Error output:

❌ No agenium.json found. Run: agenium init

Requirements:

agenium.json must exist

Exit codes:

0 - Status retrieved
1 - No configuration found

`e2e`

Run end-to-end integration tests.

bash

agenium e2e

What it does:

Runs the full E2E test suite
Tests DNS resolution, handshake, messaging, persistence
Verifies all components work together

Output:

Running Agenium E2E Tests...

✅ DNS Resolution
✅ Handshake
✅ Request/Response
✅ Event delivery
✅ Session persistence
✅ Outbox delivery

All tests passed!

Requirements:

Must run from AGENIUM source directory
Test file e2e-test.ts must exist

Exit codes:

0 - All tests passed
1 - Tests failed or not found

`version`

Show AGENIUM version.

bash

agenium version
# or
agenium --version
agenium -v

Output:

agenium v0.1.0

Exit codes:

0 - Always succeeds

`help`

Show help information.

bash

agenium help
# or
agenium --help
agenium -h

Output:

╔════════════════════════════════════════════╗
║           AGENIUM CLI v0.1.0              ║
╚════════════════════════════════════════════╝

Usage: agenium <command> [options]

Commands:
  init                    Initialize a new agent in current directory
  resolve <agent://uri>   Resolve agent URI to IP:port via DNS
  connect <agent://uri>   Connect to a remote agent
  status                  Show local agent status
  e2e                     Run end-to-end integration tests
  version                 Show version

Options:
  --help, -h              Show this help
  --config, -c <file>     Config file (default: ./agenium.json)

Examples:
  agenium init
  agenium resolve agent://alice
  agenium connect agent://bob
  agenium status
  agenium e2e

Documentation: https://github.com/agenium/agenium

Configuration File

The agenium.json file contains agent configuration:

Schema

json

{
  "agentId": "string",
  "version": "string",
  "dataDir": "string",
  "dnsServer": "string",
  "metricsPort": "number",
  "metricsHost": "string",
  "bugReportServer": "string",
  "timeouts": {
    "dnsLookupMs": "number",
    "handshakeMs": "number",
    "requestMs": "number"
  }
}

Example

json

{
  "agentId": "agent-abc123",
  "version": "0.1.0",
  "dataDir": "./.agenium",
  "dnsServer": "http://185.204.169.26:3000",
  "metricsPort": 9090,
  "metricsHost": "127.0.0.1",
  "bugReportServer": "https://bugs.agenium.net/api/bug-reports",
  "timeouts": {
    "dnsLookupMs": 10000,
    "handshakeMs": 10000,
    "requestMs": 30000
  }
}

Fields

Field	Type	Description
`agentId`	string	Unique agent identifier
`version`	string	AGENIUM version
`dataDir`	string	Data directory for SQLite databases
`dnsServer`	string	DNS server URL or IP
`metricsPort`	number	Prometheus metrics port
`metricsHost`	string	Metrics bind host
`bugReportServer`	string	Bug reporting endpoint
`timeouts.dnsLookupMs`	number	DNS lookup timeout (ms)
`timeouts.handshakeMs`	number	TLS handshake timeout (ms)
`timeouts.requestMs`	number	Request timeout (ms)

Exit Codes

All commands follow standard exit code conventions:

Code	Meaning
`0`	Success
`1`	Error (general)
`2`	Invalid arguments

Environment Variables

`AGENIUM_CONFIG`

Override default config file location:

bash

export AGENIUM_CONFIG=/path/to/config.json
agenium status

`AGENIUM_DATA_DIR`

Override data directory:

bash

export AGENIUM_DATA_DIR=/path/to/data
agenium status

`AGENIUM_DNS_SERVER`

Override DNS server:

bash

export AGENIUM_DNS_SERVER=https://custom-dns.example.com
agenium resolve agent://bob

Scripting Examples

Bash Script

bash

#!/bin/bash

# Initialize agent
if ! agenium init; then
  echo "Failed to initialize agent"
  exit 1
fi

# Check DNS connectivity
if ! agenium status; then
  echo "DNS server unreachable"
  exit 1
fi

# Resolve target
if ! agenium resolve agent://target; then
  echo "Target agent not found"
  exit 1
fi

echo "All checks passed!"

Docker Integration

dockerfile

FROM node:20-alpine

WORKDIR /app

# Install AGENIUM globally
RUN npm install -g agenium

# Initialize agent
RUN agenium init

# Copy custom config
COPY agenium.json ./

# Start application
CMD ["node", "app.js"]

Troubleshooting

Command Not Found

bash

agenium: command not found

Solution:

bash

# Install globally
npm install -g agenium

# Or use npx
npx agenium <command>

Permission Denied

bash

Error: EACCES: permission denied, mkdir '.agenium'

Solution:

bash

# Run with appropriate permissions
sudo agenium init

# Or change directory ownership
sudo chown -R $USER .

Config Not Found

bash

❌ No agenium.json found. Run: agenium init

Solution:

bash

# Run init first
agenium init

# Or specify config file
agenium status --config /path/to/config.json

CLI Reference ​

Installation ​

Global Options ​

Commands ​

init ​

resolve ​

connect ​

status ​

e2e ​

version ​

help ​

Configuration File ​

Schema ​

Example ​

Fields ​

Exit Codes ​

Environment Variables ​

AGENIUM_CONFIG ​

AGENIUM_DATA_DIR ​

AGENIUM_DNS_SERVER ​

Scripting Examples ​

Bash Script ​

Docker Integration ​

Troubleshooting ​

Command Not Found ​

Permission Denied ​

Config Not Found ​

See Also ​

CLI Reference

Installation

Global Options

Commands

`init`

`resolve`

`connect`

`status`

`e2e`

`version`

`help`

Configuration File

Schema

Example

Fields

Exit Codes

Environment Variables

`AGENIUM_CONFIG`

`AGENIUM_DATA_DIR`

`AGENIUM_DNS_SERVER`

Scripting Examples

Bash Script

Docker Integration

Troubleshooting

Command Not Found

Permission Denied

Config Not Found

See Also