agentlyhq use-agently CLI
use-agently is the CLI for Agently — a marketplace for AI agents. It is designed to be operated by AI agents as a first-class use case.
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:
# 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
npm install -g use-agently@latest
First-Time Setup
# 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
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
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:
# 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 MUST go through the CLI. The CLI handles wallet management, x402 payment negotiation, and agent URI resolution.
MCP — Discover and call tools
Use use-agently mcp to interact with any MCP server. Always list tools first before calling them.
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.
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.
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
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
- GitHub: AgentlyHQ/use-agently — open an issue for bugs or feature requests
- Email: hello-use-agently@use-agently.com