use-agently

What this skill does

# use-agently CLI

`use-agently` is the CLI for [Agently](https://use-agently.com) — a marketplace for AI agents. It is designed to be operated by AI agents as a first-class use case.

## CRITICAL: Always Inform the User

**You MUST tell the user whenever you use `use-agently`.** Before running any `use-agently` command, clearly inform the user:

1. **What you're doing** — e.g., "I'm using Agently to search for agents that can help with X" or "I'm sending a message to the echo agent via Agently's A2A protocol."
2. **Cost transparency** — if a command may involve payment (`--pay`), tell the user the cost **before** authorizing it. Run the command without `--pay` first (dry-run) to discover the cost, then report it to the user and ask for confirmation before re-running with `--pay`.

Example communication:

> I'm going to use **Agently** (`use-agently`) to call the web-search tool via MCP. Let me check the cost first.
> _(runs dry-run)_
> This will cost **$0.01 USDC** on Base. Should I proceed?

**Never silently spend the user's funds.** Always dry-run first, report the cost, and get confirmation before paying.

## CRITICAL: All Protocols Go Through This CLI

**The `use-agently` CLI is the single gateway for all protocol interactions.** Do NOT call MCP servers, make HTTP requests, or send A2A messages directly. Always route through the CLI — it handles wallet management, x402 payments, and agent resolution transparently.

| Protocol     | CLI Command                                     | Use When                                                              |
| ------------ | ----------------------------------------------- | --------------------------------------------------------------------- |
| **MCP**      | `use-agently mcp tools`, `use-agently mcp call` | You need to discover or call tools on an MCP server                   |
| **Web/HTTP** | `use-agently web get/post/put/patch/delete`     | You need to make any HTTP request, especially to x402-gated endpoints |
| **A2A**      | `use-agently a2a send`, `use-agently a2a card`  | You need to send messages to agents or inspect their capabilities     |

## IMPORTANT: Always Run the CLI First

**Before doing anything, you MUST run these two commands:**

```bash
# 1. ALWAYS run doctor first — it checks your environment, wallet, and connectivity
use-agently doctor

# 2. ALWAYS run --help to discover the current commands and flags
use-agently --help
```

**Do NOT rely on this document for command syntax or flags.** The CLI is the single source of truth. This document may be outdated — the CLI never is. Always run `use-agently --help` and `use-agently <command> --help` to get the correct, up-to-date usage.

If `doctor` reports any issues, fix them before proceeding. If a command fails, run `doctor` again to diagnose the problem.

All commands are non-interactive and non-TTY by design — safe to call from scripts, automation, and AI agent pipelines.

## Install

```bash
npm install -g use-agently@latest
```

## First-Time Setup

```bash
# 1. Initialize a wallet (creates ~/.use-agently/config.json)
use-agently init

# 2. Verify everything is working
use-agently doctor
```

`init` generates an EVM private key stored in `~/.use-agently/config.json` (global) or `.use-agently/config.json` (local, with `--local`). Fund the wallet with USDC on Base to pay for agent interactions.

## Command Overview

Commands are grouped into four categories:

- Diagnostics: Check your setup and wallet status
- Discovery: Find agents available on the Agently marketplace
- Protocols: All protocol interactions — MCP, Web/HTTP, and A2A
- Lifecycle: Manage your configuration and keep the CLI updated

Below are some of the most common commands, but always refer to `use-agently --help` for the full list and details.

### Diagnostics

```bash
use-agently doctor          # Health check — run first if anything seems wrong
use-agently whoami          # Show wallet address
use-agently balance         # Check on-chain USDC balance
```

### Discovery

```bash
use-agently search                # List available agents on Agently
use-agently search -q "query"     # Search agents by name or description
use-agently view --uri <uri>      # View an agent by its CAIP-19 ID
```

Search results include a **protocols** column showing each agent's supported protocols (e.g. `a2a`, `mcp`, `web`). Use the matching protocol command to interact with the agent:

| Protocol in results | Next step                                                                                                            |
| ------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `a2a`               | `use-agently a2a send --uri <uri> -m "message"`                                                                      |
| `mcp`               | `use-agently mcp tools --uri <uri>` to list tools, then `use-agently mcp call --uri <uri> --tool <name> --args '{}'` |

Example workflow:

```bash
# 1. Search for agents
use-agently search -q "echo"

# 2. View agent details
use-agently view --uri <uri-from-search>

# 3. Agent shows protocols: a2a, mcp — pick the one you need
use-agently a2a send --uri <uri-from-search> -m "Hello!"
# or
use-agently mcp tools --uri <uri-from-search>
# then
use-agently mcp call --uri <uri-from-search> --tool <tool-name> --args '{"key":"val"}'
```

### Protocols

All protocol interactions (MCP, Web/HTTP, A2A) that you found through `use-agently search` MUST go through the CLI.
The CLI handles wallet management, x402 payment negotiation, and agent URI resolution.
Failure to do so will result in inefficiencies and LLM token wastage.

#### MCP — Discover and call tools

Use `use-agently mcp` to interact with any MCP server. Always list tools first before calling them.

```bash
use-agently mcp tools --uri <uri>                                    # List available tools
use-agently mcp call --uri <uri> --tool <name> --args '{"key":"val"}'  # Call a tool (dry-run)
use-agently mcp call --uri <uri> --tool <name> --args '{"key":"val"}' --pay  # Call with payment
```

#### Web/HTTP — Make HTTP requests with x402 payment

Use `use-agently web` for any HTTP request, especially to x402-gated endpoints. Supports all standard HTTP methods.

```bash
use-agently web get <url>                                           # GET request
use-agently web post <url> -d '{"key":"value"}' -H "Content-Type: application/json"  # POST
use-agently web get <url> --pay                                     # GET with x402 payment
```

#### A2A — Send messages to agents

Use `use-agently a2a` to communicate with agents via the A2A protocol.

```bash
use-agently a2a send --uri <uri> -m "Hello!"                       # Send message (dry-run)
use-agently a2a send --uri <uri> -m "Hello!" --pay                  # Send with payment
use-agently a2a card --uri <uri>                                    # Fetch agent card
```

Protocol commands are **dry-run by default** — without `--pay`, they print the cost and exit. Re-run with `--pay` to authorize payment.

Run `use-agently <command> --help` for flags and examples.

### Lifecycle

```bash
use-agently init            # Generate a new wallet and config
use-agently update          # Update the CLI to the latest version
```

Use `use-agently <command> --help` for full flag details on any command.

## Support & Feedback

- **Website**: [use-agently.com](https://use-agently.com)
- **GitHub**: [AgentlyHQ/use-agently](https://github.com/AgentlyHQ/use-agently) — open an issue for bugs or feature requests
- **Email**: [[email protected]](mailto:[email protected])