💻 YAMO CLI

The Command Line Interface for the YAMO Protocol. Now powered by @yamo/core.

📦 Installation

# Global installation (recommended)
npm install -g @yamo/cli

# Or use npx (no installation needed)
npx @yamo/cli <command>

⚙️ Configuration

Set environment variables or create a .env file:

CONTRACT_ADDRESS=0x3c9440fa8d604E732233ea17095e14be1a53b015
RPC_URL=https://ethereum-sepolia-rpc.publicnode.com
PRIVATE_KEY=0xYOUR_PRIVATE_KEY

# IPFS Settings (optional)
USE_REAL_IPFS=false
PINATA_JWT=your_pinata_jwt_if_using_real_ipfs

Networks

Sepolia Testnet (default):

• Contract: 0x3c9440fa8d604E732233ea17095e14be1a53b015
• RPC: https://ethereum-sepolia-rpc.publicnode.com (free public RPC)

Local Development:

• Contract: Deploy using @yamo/contracts
• RPC: http://127.0.0.1:8545

📖 Commands

yamo init <agent_name>

Creates a new block.yamo template.

# With global install
yamo init MyAgent

# With npx
npx @yamo/cli init MyAgent

yamo hash <file>

Calculates the content hash formatted for blockchain submission.

yamo hash block.yamo

yamo submit <file>

Submits a block to the chain.

• --ipfs: Uploads content to IPFS. If the YAMO file contains output: file.json;, it will automatically create a Deep Bundle containing both the trace and the artifact.
• -e, --encrypt: Encrypts the IPFS bundle using AES-256-GCM.
• -k, --key <string>: The passphrase for encryption (or use YAMO_ENCRYPTION_KEY env var).

# Basic submission
yamo submit block.yamo

# With IPFS
yamo submit block.yamo --ipfs

# With encryption
yamo submit block.yamo --ipfs --encrypt --key "my-secret"

yamo audit <blockId>

Performs a cryptographic integrity check.

1. Fetches block data from the chain.
2. Downloads content from IPFS.
3. Re-hashes the content locally.
4. Asserts LocalHash === ChainHash.

• -k, --key <string>: Passphrase to decrypt the content if the bundle is encrypted.

# Audit without encryption
yamo audit block_001

# Audit encrypted content
yamo audit block_001 --key "my-secret"

yamo config <action> [key] [value]

Manage local configuration and secrets persistently. Actions: set, get, list, remove. Values are stored in ~/.yamo/config.json. Sensitive keys (e.g., PRIVATE_KEY) are masked in list.

# Set a configuration value
yamo config set PRIVATE_KEY 0x...

# List current configuration
yamo config list

# Get a specific value
yamo config get RPC_URL

yamo download-bundle <cid>

Downloads a complete YAMO bundle (file + artifacts) from IPFS.

• -o, --output <path>: Output directory path.
• -k, --key <string>: Decryption key if the bundle is encrypted.

yamo download-bundle Qm... -o ./downloads/my-bundle

yamo bridge <subcommand>

Interact with the YAMO bridge/cluster. Requires YAMO_BRIDGE_URL to be set.

• kernels: List connected kernels and their capabilities.
• status: Show bridge cluster status.
• invoke <skill> --payload <json>: Invoke a skill via the bridge.

yamo bridge status
yamo bridge kernels
yamo bridge invoke my-skill -p '{"input": "test"}'

🔒 Encryption

YAMO v1.0 supports optional client-side encryption for IPFS bundles.

• Algorithm: AES-256-GCM (Authenticated Encryption).
• Key Derivation: Keys are derived from your passphrase using scrypt with a random salt.
• Metadata: Encrypted bundles include an encryption_metadata.json file with the salt and IVs. The actual content is opaque.

Example Encrypted Workflow:

# Submit with encryption
yamo submit task.yamo --ipfs --encrypt --key "my-secret"

# Audit encrypted block
yamo audit block_001 --key "my-secret"

🧪 Testing

Run all tests:

npm test

Run specific test suite:

npm test -- test/hash.test.js

Test Coverage:

• Unit tests: 22 tests (hash, init, validation utilities, format utilities, constants)
• Integration tests: 8 tests (CLI interface, error handling)
• E2E tests: 2 tests (basic workflows)
• Security tests: 13 tests (path traversal protection)
• Validation tests: 3 tests (blockId format)
• Auto-fetch tests: 5 tests (previousBlock resolution)
• Health checks: 2 tests (test suite validation)

Total: 54+ tests with 100% pass rate