@myndhyve/cli

The MyndHyve CLI is the primary developer interface for MyndHyve. Authenticate, chat with AI agents, manage projects, automate workflows, control messaging connectors, and bridge device-bound platforms — all from the terminal.

Requirements

• Node.js 20+
• MyndHyve account
• Platform-specific prerequisites for relay channels (see below)

Installation

npm install -g @myndhyve/cli

Development

This package consumes WOP wire-format types and helpers from @myndhyve/wop, the TypeScript SDK published from the open Workflow Orchestration Protocol spec corpus at github.com/myndhyve/wop. That package resolves from npm — npm install works from any clean checkout, no sibling-repo setup required.

MyndHyve-engine-specific wire types (the wider 12-member WorkflowRunStatus emission union, WorkflowDetail, WorkflowSummary, trigger identifiers, etc.) live inline at src/types/wire-format.ts — they describe what the MyndHyve engine specifically emits and aren't part of the open WOP spec.

git clone https://github.com/myndhyve/myndhyve-cli.git
cd myndhyve-cli
npm install
npm run typecheck && npm test

Quick Start

# 1. Authenticate with MyndHyve
myndhyve-cli auth login

# 2. List your projects
myndhyve-cli projects list

# 3. Set active project context
myndhyve-cli use <project-id>

# 4. Start an AI chat session
myndhyve-cli chat

Commands

myndhyve-cli
├── auth                         # Authentication
│   ├── login                    # Authenticate with MyndHyve
│   ├── logout                   # Clear stored credentials
│   ├── status                   # Show current auth state
│   └── token                    # Print access token (for scripting)
│
├── chat [agent] [--hyve=X]      # Interactive AI chat session
│
├── projects                     # Project management
│   ├── list                     # List all projects
│   ├── create                   # Create a new project
│   ├── open <id>                # Open project in browser
│   ├── delete <id>              # Delete a project
│   └── info <id>                # Show project details
│
├── hyves                        # Hyve management
│   ├── list                     # List available hyves
│   └── info <id>                # Show hyve details
│
├── use <project-id>             # Set active project context
├── unuse                        # Clear active context
├── whoami                       # Show user + active project
│
├── messaging                    # Cloud messaging operations
│   ├── connectors list          # List messaging connectors
│   ├── connectors status <id>   # Show connector status
│   ├── connectors test <id>     # Send a test message
│   ├── connectors enable <id>   # Enable a connector
│   ├── connectors disable <id>  # Disable a connector
│   ├── policies get <id>        # Get connector policies
│   ├── policies set <id>        # Set connector policies
│   ├── routing list             # List routing rules
│   ├── routing add              # Add a routing rule
│   ├── routing remove <id>      # Remove a routing rule
│   ├── logs [--since=1h]        # Query delivery logs
│   ├── sessions list            # List active sessions
│   ├── sessions inspect <key>   # Inspect a session
│   ├── sessions close <key>     # Close a session
│   ├── identity list            # List identities
│   ├── identity link <id>       # Link a peer to identity
│   └── identity unlink <id>     # Unlink a peer
│
├── workflows                    # Workflow automation
│   ├── list                     # List workflows for a hyve
│   ├── info <id>                # Show workflow details
│   ├── run <id> [--input=JSON]  # Trigger a workflow run
│   ├── runs [--status=X]        # List workflow runs
│   ├── status <runId>           # Show run status
│   ├── logs <runId> [--follow]  # Stream run event logs
│   ├── artifacts list <runId>   # List run artifacts
│   ├── artifacts get <id>       # Download an artifact
│   ├── approve <runId>          # Approve a pending run
│   ├── reject <runId>           # Reject a pending run
│   └── revise <runId>           # Request revision on a run
│
├── relay                        # Device-bound messaging relay
│   ├── setup                    # Register a new relay device
│   ├── start [--daemon]         # Start the relay agent
│   ├── stop                     # Stop the relay daemon
│   ├── status                   # Show relay device status
│   ├── login                    # Authenticate with platform
│   ├── logout                   # Clear credentials
│   ├── logs [--follow]          # View relay daemon logs
│   └── uninstall                # Remove all relay data
│
└── dev                          # Developer tools
    ├── doctor                   # Check environment health
    ├── ping                     # Test cloud connectivity
    ├── envelope create          # Create a test envelope
    ├── envelope validate        # Validate an envelope
    ├── webhook test             # Generate a test webhook event
    ├── webhook events           # List available event types
    └── config export|import     # Manage CLI config

Global Options

| Option | Description | |--------|-------------| | --json | Machine-readable JSON output (scriptable) | | --verbose | Show debug-level logging | | --help | Show help for any command | | --version | Show CLI version |

auth

# Browser-based login
myndhyve-cli auth login

# Check authentication state
myndhyve-cli auth status

# Print token for scripting (e.g., curl -H "Authorization: Bearer $(myndhyve-cli auth token)")
myndhyve-cli auth token

chat

# Start an interactive AI chat
myndhyve-cli chat

# Chat with a specific agent
myndhyve-cli chat marketing-advisor

# Chat within a specific hyve context
myndhyve-cli chat --hyve landing-page

workflows

# List workflows for a hyve
myndhyve-cli workflows list --hyve landing-page

# Trigger a workflow run with input
myndhyve-cli workflows run copy-generator --input '{"prompt": "Write hero copy"}'

# Stream run logs in real time
myndhyve-cli workflows logs run-abc --follow

# Approve a human-in-the-loop checkpoint
myndhyve-cli workflows approve run-abc

messaging

# List your connectors
myndhyve-cli messaging connectors list

# Query recent delivery logs
myndhyve-cli messaging logs --since 1h

# Test a connector
myndhyve-cli messaging connectors test whatsapp-prod

dev

# Run environment diagnostics
myndhyve-cli dev doctor

# Test connectivity to MyndHyve Cloud
myndhyve-cli dev ping

# Create and validate test envelopes
myndhyve-cli dev envelope create --channel whatsapp --text "Hello"
myndhyve-cli dev envelope validate < envelope.json

# Generate mock webhook events
myndhyve-cli dev webhook test --channel signal --event message

Supported Relay Platforms

WhatsApp

Uses Baileys (unofficial WhatsApp Web API).

Prerequisites: None beyond Node.js.

Authentication: Scan a QR code in your terminal during myndhyve-cli relay login.

Warning: WhatsApp bridging uses an unofficial API. Your WhatsApp account may be at risk of being banned. Use a secondary number if possible.

Signal

Uses signal-cli JSON-RPC bridge.

Prerequisites:

# macOS
brew install signal-cli

# Linux (snap)
sudo snap install signal-cli

# Other: Download from github.com/AsamK/signal-cli/releases

Authentication: Register or link your Signal account during myndhyve-cli relay login.

iMessage

Uses the imsg RPC tool for macOS Messages.app integration.

Prerequisites:

# macOS only
brew install --cask imsg

Platform: macOS only. Requires an active Apple ID signed into Messages.

Architecture

┌──────────────────────────────────────────────────────────┐
│                       @myndhyve/cli                      │
│                                                          │
│  ┌─────────┐ ┌──────────┐ ┌───────────┐ ┌───────────┐  │
│  │  Auth   │ │   Chat   │ │ Projects  │ │ Workflows │  │
│  └────┬────┘ └────┬─────┘ └─────┬─────┘ └─────┬─────┘  │
│       └──────┬────┴─────────────┴──────────────┘        │
│              ▼                                           │
│  ┌──────────────────────────────────────────────────┐   │
│  │           MyndHyve API Client                    │   │
│  │  POST /auth    POST /chat    GET /projects       │   │
│  │  GET /hyves    POST /runs    GET /connectors     │   │
│  └──────────────────────┬───────────────────────────┘   │
│                         ▼                               │
│           MyndHyve Cloud Functions                      │
│     (hyveApi, aiProxy, messagingGateway)                │
│                                                          │
│  ┌──────────────────────────────────────────────────┐   │
│  │         Relay Agent (Device-Bound)               │   │
│  │  ┌──────────┐ ┌────────┐ ┌─────────────┐        │   │
│  │  │ WhatsApp │ │ Signal │ │  iMessage   │        │   │
│  │  │(Baileys) │ │(signal │ │(AppleScript/│        │   │
│  │  │          │ │  -cli) │ │  imsg RPC)  │        │   │
│  │  └────┬─────┘ └───┬────┘ └──────┬──────┘        │   │
│  │       └──────┬────┴──────────────┘               │   │
│  │              ▼                                    │   │
│  │   ┌──────────────────────┐                       │   │
│  │   │  Message Normalizer  │                       │   │
│  │   │ → ChatIngressEnvelope│                       │   │
│  │   └──────────┬───────────┘                       │   │
│  └──────────────┼────────────────────────────────────┘  │
│                 ▼                                        │
│  ┌──────────────────────────────────────────────────┐   │
│  │        Relay Protocol Client                     │   │
│  │  POST /inbound   POST /heartbeat                 │   │
│  │  GET  /outbound  POST /ack                       │   │
│  └──────────────────┬───────────────────────────────┘   │
│                     ▼                                    │
│         MyndHyve Cloud Functions                        │
│      (messagingRelayGateway)                            │
└──────────────────────────────────────────────────────────┘

Configuration

Config is stored at ~/.myndhyve-cli/config.json:

{
  "server": {
    "baseUrl": "https://us-central1-myndhyve.cloudfunctions.net/messagingRelayGateway"
  },
  "reconnect": {
    "maxAttempts": "Infinity",
    "initialDelayMs": 1000,
    "maxDelayMs": 300000
  },
  "heartbeat": {
    "intervalSeconds": 30
  },
  "outbound": {
    "pollIntervalSeconds": 5,
    "maxPerPoll": 10
  },
  "logging": {
    "level": "info"
  }
}

Data Directory

All CLI data is stored in ~/.myndhyve-cli/:

~/.myndhyve-cli/
├── config.json          # Configuration
├── context.json         # Active project context (from `use`)
├── device.json          # Device registration (relayId, token)
├── relay.pid            # Daemon PID file
├── logs/
│   └── relay.log        # Daemon log file
└── auth/
    ├── credentials.json # MyndHyve auth tokens
    └── {channel}/       # Platform-specific auth state

Troubleshooting

| Issue | Solution | |-------|----------| | auth login hangs | Check firewall/proxy settings, try --verbose | | Daemon won't start | Check myndhyve-cli relay status, ensure no stale PID file | | WhatsApp QR code not showing | Ensure terminal supports Unicode, try --verbose | | Signal: "command not found" | Install signal-cli and ensure it's in PATH | | iMessage: "not supported" | iMessage only works on macOS with Apple ID | | Connection drops | Check network, daemon auto-reconnects with backoff | | Activation code expired | Run myndhyve-cli relay setup again to get a new code |

Development

# Install dependencies
npm install

# Build (generates dist/index.js + dist/index.d.ts)
npm run build

# Run tests (1,700+ test cases)
npm test

# Type check
npm run typecheck

# Watch mode
npm run dev

Release Process

# 1. Bump version
npm version patch  # or minor, major

# 2. Push with tag — GitHub Actions publishes to npm
git push && git push --tags

License

MIT