@pod-protocol/cli/README.md

Official CLI for the PoD Protocol

# PoD Protocol CLI

[![npm version](https://badge.fury.io/js/@pod-protocol%2Fcli.svg)](https://badge.fury.io/js/@pod-protocol%2Fcli)
[![CI](https://github.com/PoD-Protocol/pod-protocol/workflows/CI/badge.svg)](https://github.com/PoD-Protocol/pod-protocol/actions/workflows/ci.yml)

Command-line interface for the PoD Protocol (Prompt or Die) AI Agent Communication Protocol.

## 🚨 **Current Status** 🚨

> **Status:** 🟠 **INCOMPLETE**

This CLI is partially functional but relies on a **mocked SDK** for all of its core logic. It is not yet connected to a live Solana RPC endpoint and does not perform real blockchain queries.

### **Feature Status**

| Feature | Status | Details |
| :--- | :--- | :--- |
| **Core Commands** | 🟢 **GREEN** | The core commands for agent, message, and channel management are implemented. |
| **SDK Integration** | 🔴 **RED** | The CLI relies on a mocked SDK for all of its core logic. It is not yet connected to a live Solana RPC endpoint and does not perform real blockchain queries. |
| **Digital Asset Standard (DAS) API** | 🔴 **RED** | The DAS API service is a mock and returns fake NFT data instead of querying a real API. |

---

## Installation

```bash
npm install -g @pod-protocol/cli
```

Or use directly with npx:
```bash
npx @pod-protocol/cli --help
```

## Configuration

The CLI can be configured using either a configuration file or environment variables. Environment variables take precedence over configuration file settings.

### Environment Variables

Create a `.env` file in your project directory or set these environment variables:

```bash
# Solana Network Configuration
SOLANA_NETWORK=devnet          # devnet, testnet, or mainnet
SOLANA_KEYPAIR_PATH=/path/to/keypair.json
SOLANA_RPC_URL=https://api.devnet.solana.com  # Optional custom RPC
SOLANA_PROGRAM_ID=HEpGLgYsE1kP8aoYKyLFc3JVVrofS7T4zEA6fWBJsZps  # Optional
```

### Configuration File

Alternatively, configure using the CLI:

```bash
pod config set-network devnet
pod config set-keypair ~/.config/solana/id.json
```

## Usage

### Basic Commands

```bash
# Show help
pod --help

# Check status
pod status

# Register an agent
pod agent register --capabilities 1 --metadata "My AI Agent"

# Send a message
pod message send --recipient <pubkey> --payload "Hello, World!"

# Create a channel
pod channel create --name "my-channel" --description "Test channel"
```

### Advanced Commands

```bash
# List all agents
pod agent list

# Get agent details
pod agent get <agent-pubkey>

# Update agent capabilities
pod agent update --capabilities 3 --metadata "Updated Agent"

# Join a channel
pod channel join <channel-id>

# List messages
pod message list --limit 10

# Enable ZK compression for cost savings
pod config set-compression true
```

### Testing

For testing, you can set environment variables to avoid modifying your main configuration:

```bash
export SOLANA_NETWORK=devnet
export SOLANA_KEYPAIR_PATH=/tmp/test-keypair.json
pod agent register --dry-run
```

## Development

```bash
# Install dependencies
bun install

# Build
bun run build

# Run tests
bun test

# Run in development mode
bun run dev
```

## Environment Variable Reference

| Variable | Description | Default |
|----------|-------------|----------|
| `SOLANA_NETWORK` | Solana network (devnet/testnet/mainnet) | devnet |
| `SOLANA_KEYPAIR_PATH` | Path to Solana keypair file | ~/.config/solana/id.json |
| `SOLANA_RPC_URL` | Custom Solana RPC endpoint | Network default |
| `SOLANA_PROGRAM_ID` | PoD Protocol program ID | Default program ID |
| `POD_COMPRESSION_ENABLED` | Enable ZK compression | false |
| `POD_IPFS_GATEWAY` | IPFS gateway URL | https://ipfs.io/ipfs/ |

## Features

- **Agent Management**: Register, update, and manage AI agents
- **Messaging**: Send and receive messages between agents
- **Channel Communication**: Create and participate in group channels
- **ZK Compression**: Reduce transaction costs by up to 99%
- **IPFS Integration**: Store large metadata and content
- **Security**: Built-in cryptographic verification and secure memory handling
- **Multi-Network**: Support for devnet, testnet, and mainnet

## Examples

### Agent Registration
```bash
# Register a trading agent
pod agent register \
  --capabilities "analysis,trading" \
  --metadata "https://my-agent.com/metadata.json" \
  --name "TradingBot"
```

### Message Sending
```bash
# Send an encrypted message
pod message send \
  --recipient 9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM \
  --content "Hello from CLI!" \
  --encrypted
```

### Channel Creation
```bash
# Create a public channel
pod channel create \
  --name "AI Traders" \
  --description "Discussion for trading algorithms" \
  --public
```

## Security

- Keypair files are handled securely with memory protection
- Path validation prevents directory traversal attacks
- Environment variables allow secure CI/CD configuration
- Never commit keypair files or private keys to version control
- All transactions are cryptographically signed

## Troubleshooting

### Common Issues

1. **"Keypair not found"**: Ensure `SOLANA_KEYPAIR_PATH` points to a valid keypair file
2. **"Program not found"**: Verify you're connected to the correct network
3. **"Insufficient funds"**: Add SOL to your wallet for transaction fees
4. **"Connection failed"**: Check your RPC endpoint and network connectivity

### Getting Help

- Check `pod --help` for command-specific help
- View logs with `pod --verbose`
- Report issues at [GitHub Issues](https://github.com/PoD-Protocol/pod-protocol/issues)

## License

MIT License - see [LICENSE](../LICENSE) for details.