Cloud Agent CLI

Command-line control plane for AgentMeld cloud agents using the existing MCP API at /api/mcp.

Endpoint Resolution

The CLI endpoint is resolved in this order:

1. --endpoint <url>
2. CLOUDMCP_URL
3. Default: https://agentmeld.com/api/mcp

If a base URL is provided (for example https://agentmeld.com), the CLI normalizes it to /api/mcp.

Quick Start

From repository root:

bun run cloud-agent-cli -- help

Package global install (once published):

npm install -g agentmeld-cloud-cli
# or
bun add -g agentmeld-cloud-cli

Env variables:

• CLOUDMCP_API_KEY for authentication
• CLOUDMCP_URL for endpoint base (or full /api/mcp URL)

Optional global env file (works from any directory):

• ~/.config/agentmeld-cloud-cli/.env
• ~/.agentmeld-cloud-cli/.env

Or set a custom one with --env-file <path> or AGENTMELD_CLI_ENV_FILE.

Override with flags:

bun run cloud-agent-cli -- --api-key cmcp_... --endpoint https://agentmeld.com run --task-type research --description "Analyze MCP adoption trends"

Global Install (Any Directory)

Install a global command:

bun run cloud-agent-cli:install-global

This creates agentmeld-cloud in ~/.local/bin (or $AGENTMELD_CLI_BIN_DIR) pointing to this CLI.

Package Build/Publish

Build distributable JS:

bunx tsc -p tools/cloud-agent-cli/tsconfig.build.json

Dry-run package contents:

cd tools/cloud-agent-cli
npm pack --dry-run

Publish:

cd tools/cloud-agent-cli
npm publish

Commands

run          Delegate and wait until terminal state
delegate     Delegate task (async by default)
status       Fetch task status
wait         Poll task until terminal status
retry        Retry terminal task
cancel       Cancel queued/running task
events       Fetch ordered lifecycle events
list-agents  List available cloud agent types
list-tools   List MCP tools exposed by server
invoke       Agent-oriented JSON invocation entrypoint

Examples

Run a task with polling:

bun run cloud-agent-cli -- run \
  --task-type coding \
  --description "Draft an incremental migration plan from REST to GraphQL"

Async delegation + explicit wait:

bun run cloud-agent-cli -- delegate \
  --task-type multi_agent \
  --description "Compare 3 deployment strategies with risks and recommendation" \
  --agents researcher,analyst,writer \
  --mode collaborative \
  --wait

Check status:

bun run cloud-agent-cli -- status --task-id <task_id>

Retry with one focused change:

bun run cloud-agent-cli -- retry \
  --task-id <task_id> \
  --change "Include concrete rollout checkpoints and rollback criteria" \
  --wait

Inspect task events:

bun run cloud-agent-cli -- events --task-id <task_id> --limit 200

JSON output for automation:

bun run cloud-agent-cli -- --json status --task-id <task_id>

Agent invocation mode via stdin JSON:

echo '{
  "tool": "delegate_task",
  "arguments": {
    "task_type": "analysis",
    "description": "Create a concise architecture risk summary."
  },
  "wait": true,
  "interval": 5,
  "timeout": 180
}' | bun run cloud-agent-cli -- invoke --stdin-json

run with stdin payload:

cat <<'JSON' | bun run cloud-agent-cli -- run --stdin-json
{
  "task_type": "coding",
  "description": "Propose a phased database migration strategy",
  "agent_config": {
    "agents": ["coder", "analyst"],
    "collaboration_mode": "parallel",
    "max_duration": 300
  },
  "context": {
    "background": "Service uses Postgres and Redis."
  }
}
JSON

Integration Test

Runs an end-to-end flow:

1. delegate
2. wait
3. events

Command:

bun run cloud-agent-cli:test

If CLOUDMCP_API_KEY is not set, the test exits with a skip message.