use-agently 0.28.0 → 0.30.0

package/README.md

@@ -7,6 +7,7 @@ Manage local EVM wallets, discover agents, and communicate with them via the [A2
 ## Install
 
 ```bash
+npx skills add https://github.com/agentlyhq/use-agently --skill use-agently
 npm install -g use-agently@latest
 ```
 
@@ -25,10 +26,13 @@ use-agently whoami
 # Check your on-chain balance
 use-agently balance
 
-# List available agents
-use-agently agents
+# Browse available agents
+use-agently search
+
+# Search for agents by intent
+use-agently search -q "echo"
 
-# Send a message to an agent (use the URI from `use-agently agents`)
+# Send a message to an agent (use the URI from `use-agently search`)
 use-agently a2a send --uri <agent-uri> -m "Hello, agent!"
 ```
 
@@ -86,23 +90,15 @@ use-agently balance
 use-agently balance --rpc https://mainnet.base.org
 ```
 
-### `agents`
-
-List available agents on Agently.
-
-```bash
-use-agently agents
-```
-
 ### `search`
 
-Search the Agently marketplace for agents, optionally filtering by query and/or protocol.
+Search the Agently marketplace for agents, optionally filtering by query and/or protocol. Running without a query lists all available agents.
 
 ```bash
-use-agently search
-use-agently search "echo"
-use-agently search --protocol a2a
-use-agently search "assistant" --protocol "a2a,mcp"
+use-agently search                              # Browse all agents
+use-agently search -q "echo"                    # Search by intent
+use-agently search --protocol a2a               # Filter by protocol
+use-agently search -q "assistant" --protocol "a2a,mcp"  # Combine query and protocol filter
 ```
 
 ### `a2a`
@@ -147,7 +143,7 @@ use-agently web get https://paid-api.example.com/resource
 ## How It Works
 
 1. **Wallet** — `init` generates an EVM private key stored locally. This wallet signs x402 payment headers when agents charge for their services.
-2. **Discovery** — `agents` and `search` fetch the agent directory from Agently, showing names, descriptions, supported protocols, and URIs.
+2. **Discovery** — `search` fetches the agent directory from Agently, showing names, descriptions, supported protocols, and URIs.
 3. **Communication** — `a2a send` takes an agent URI (e.g. `echo-agent`), constructs the URL as `https://use-agently.com/<agent-uri>/`, resolves the A2A card, opens a JSON-RPC or REST transport, and sends your message. If the agent returns a 402 Payment Required, the x402 fetch wrapper automatically signs and retries the request.
 
 ## Development

package/build/bin.js

@@ -91828,7 +91828,7 @@ function PayTransaction(wallet) {
 // ../use-agently-sdk/package.json
 var package_default = {
   name: "@use-agently/sdk",
-  version: "0.28.0",
+  version: "0.30.0",
   description: "Core SDK for the Agently platform — wallet management, A2A, MCP, x402 payments",
   homepage: "https://github.com/AgentlyHQ/use-agently/tree/main/packages/use-agently-sdk",
   bugs: {
@@ -96483,7 +96483,9 @@ Config: ~/.use-agently/config.json (global), .use-agently/config.json (local)`).
 });
 
 // src/commands/whoami.ts
-var whoamiCommand = new Command("whoami").description("Show current wallet info").showHelpAfterError(true).action(async (_options, command) => {
+var whoamiCommand = new Command("whoami").description("Show current wallet info").showHelpAfterError(true).addHelpText("after", `
+Examples:
+  use-agently whoami`).action(async (_options, command) => {
   const config2 = await getConfigOrThrow();
   const wallet = loadWallet(config2.wallet);
   output(command, {
@@ -96493,7 +96495,9 @@ var whoamiCommand = new Command("whoami").description("Show current wallet info"
 });
 
 // src/commands/balance.ts
-var balanceCommand = new Command("balance").description("Check wallet balance on-chain").option("--rpc <url>", "Custom RPC URL").showHelpAfterError(true).action(async (options, command) => {
+var balanceCommand = new Command("balance").description("Check wallet balance on-chain").option("--rpc <url>", "Custom RPC URL").showHelpAfterError(true).addHelpText("after", `
+Examples:
+  use-agently balance`).action(async (options, command) => {
   const config2 = await getConfigOrThrow();
   const wallet = loadWallet(config2.wallet);
   const result = await getBalance2(wallet.address, { rpc: options.rpc });
@@ -96502,7 +96506,7 @@ var balanceCommand = new Command("balance").description("Check wallet balance on
 // package.json
 var package_default2 = {
   name: "use-agently",
-  version: "0.28.0",
+  version: "0.30.0",
   description: "Use Agently CLI",
   homepage: "https://use-agently.com",
   bugs: "https://github.com/AgentlyHQ/use-agently/issues",
@@ -96526,7 +96530,7 @@ var package_default2 = {
     test: "bun test"
   },
   dependencies: {
-    "@use-agently/sdk": "0.28.0",
+    "@use-agently/sdk": "0.30.0",
     boxen: "^8.0.1",
     "cli-table3": "^0.6.5",
     commander: "^14.0.3",
@@ -96672,49 +96676,13 @@ function handleSpendLimitError(err) {
   handleErrorAndExit("Spend Limit Exceeded", err.message, "red");
 }
 
-// src/commands/agents.ts
-var agentsCommand = new Command("agents").description("List available agents on Agently").action(async (_options, command) => {
-  const format = getOutputFormat(command);
-  const result = await search(defaultClient);
-  const items = result.hits.map(({ id, name, description, protocols }) => ({ id, name, description, protocols }));
-  if (items.length === 0) {
-    outputNoResults(format);
-    return;
-  }
-  if (format === "tui") {
-    renderAgentsTable(items);
-  } else {
-    outputJsonCollection(items);
-  }
-});
-function formatId(id) {
-  const match = id.match(/^(.*?\/erc8004:)(0x[0-9a-fA-F]+)(\/\d+)$/);
-  if (match)
-    return `${match[1]}
-${match[2]}
-${match[3]}`;
-  return id;
-}
-function renderAgentsTable(items) {
-  const maxWidth = getMaxWidth();
-  const idSegmentWidth = Math.max(...items.flatMap((item) => formatId(item.id).split(`
-`).map((line) => line.length))) + 2;
-  const protoWidth = 12;
-  const nameDescWidth = maxWidth - idSegmentWidth - protoWidth - 10;
-  const table = new import_cli_table3.default({
-    wordWrap: true,
-    wrapOnWordBoundary: true,
-    colWidths: [idSegmentWidth, nameDescWidth, protoWidth],
-    head: ["id", "agent (name & description)", "protocols"]
-  });
-  for (const item of items) {
-    table.push([formatId(item.id), `${boldBlue(item.name)}
-${item.description}`, (item.protocols ?? []).join(", ")]);
-  }
-  console.log(table.toString());
-}
-
 // src/commands/search.ts
+var SUPPORTED_PROTOCOLS = ["a2a", "mcp"];
+function getHealthyProtocols(protocol) {
+  if (!protocol)
+    return [];
+  return SUPPORTED_PROTOCOLS.filter((name) => protocol[name]?.healthy === true);
+}
 var searchCommand = new Command("search").description("Search the Agently marketplace for agents").option("-q, --query <text>", "Search query to filter agents by name or description").option("-p, --protocol <protocols>", "Filter by protocol(s), comma-separated (e.g. a2a,mcp)").showHelpAfterError(true).addHelpText("after", [
   "",
   "Examples:",
@@ -96734,18 +96702,21 @@ var searchCommand = new Command("search").description("Search the Agently market
   const format = getOutputFormat(command);
   const protocol = options.protocol ? options.protocol.split(",").map((p) => p.trim().toLowerCase()) : undefined;
   const result = await search(defaultClient, { q: options.query, protocol });
-  const items = result.hits.map(({ id, name, description, protocols }) => ({ id, name, description, protocols }));
+  const items = result.hits.map((hit) => {
+    const protocols = getHealthyProtocols(hit.protocol);
+    return { id: hit.id, name: hit.name, description: hit.description, protocols };
+  }).filter((item) => item.protocols.length > 0);
   if (items.length === 0) {
     outputNoResults(format);
     return;
   }
   if (format === "tui") {
-    renderAgentsTable2(items);
+    renderAgentsTable(items);
   } else {
     outputJsonCollection(items);
   }
 });
-function formatId2(id) {
+function formatId(id) {
   const match = id.match(/^(.*?\/erc8004:)(0x[0-9a-fA-F]+)(\/\d+)$/);
   if (match)
     return `${match[1]}
@@ -96753,9 +96724,9 @@ ${match[2]}
 ${match[3]}`;
   return id;
 }
-function renderAgentsTable2(items) {
+function renderAgentsTable(items) {
   const maxWidth = getMaxWidth();
-  const idSegmentWidth = Math.max(...items.flatMap((item) => formatId2(item.id).split(`
+  const idSegmentWidth = Math.max(...items.flatMap((item) => formatId(item.id).split(`
 `).map((line) => line.length))) + 2;
   const protoWidth = 12;
   const nameDescWidth = maxWidth - idSegmentWidth - protoWidth - 10;
@@ -96766,7 +96737,7 @@ function renderAgentsTable2(items) {
     head: ["id", "agent (name & description)", "protocols"]
   });
   for (const item of items) {
-    table.push([formatId2(item.id), `${boldBlue(item.name)}
+    table.push([formatId(item.id), `${boldBlue(item.name)}
 ${item.description}`, (item.protocols ?? []).join(", ")]);
   }
   console.log(table.toString());
@@ -96794,7 +96765,10 @@ async function resolveTransactionMode(pay) {
   }
   return { client: defaultClient, mode: DryRunTransaction };
 }
-var a2aCommand = new Command("a2a").description("Send messages and fetch agent cards via the A2A protocol").action(function() {
+var a2aCommand = new Command("a2a").description("Send messages and fetch agent cards via the A2A protocol").addHelpText("after", `
+Examples:
+  use-agently a2a send --uri <uri> -m "Hello!"
+  use-agently a2a card --uri <uri>`).action(function() {
   this.outputHelp();
 });
 var a2aSendCommand = new Command("send").description("Send a message to an agent via A2A protocol").requiredOption("-u, --uri <value>", "Agent URL or CAIP-19 ID (e.g. https://example.com/agent or eip155:8453/erc8004:0x1234/1)").requiredOption("-m, --message <text>", "Message to send").option("--pay", "Authorize payment if the agent requires it (default: dry-run, shows cost only)").showHelpAfterError(true).addHelpText("after", `
@@ -96858,7 +96832,10 @@ function checkSpendLimit(err, maxSpendPerCall) {
     throw new SpendLimitExceeded(amountInDollars, maxSpendPerCall);
   }
 }
-var mcpCommand = new Command("mcp").description("Discover and call tools on MCP servers (always list tools before calling)").action(function() {
+var mcpCommand = new Command("mcp").description("Discover and call tools on MCP servers (always list tools before calling)").addHelpText("after", `
+Examples:
+  use-agently mcp tools --uri <uri>
+  use-agently mcp call --uri <uri> --tool <name> --args '{"key":"value"}'`).action(function() {
   this.outputHelp();
 });
 var mcpToolsCommand = new Command("tools").description("List available tools on an MCP server").requiredOption("-u, --uri <value>", "MCP server URL or CAIP-19 ID").showHelpAfterError(true).addHelpText("after", `
@@ -97215,15 +97192,20 @@ function createMethodSubcommand(method, description, hasBody) {
   const cmd = new Command(method).description(description).argument("<url>", "Full URL to request (e.g. https://api.example.com/data)").showHelpAfterError(true);
   addSharedOptions(cmd, hasBody);
   const bodyExample = hasBody ? ` -d '{"key":"value"}' -H "Content-Type: application/json"` : "";
+  const payExample = !hasBody ? `
+  use-agently web ${method} https://api.example.com/paid-endpoint --pay` : "";
   cmd.addHelpText("after", `
 Examples:
-  use-agently web ${method} https://api.example.com/data${bodyExample} -v`);
+  use-agently web ${method} https://api.example.com/data${bodyExample} -v${payExample}`);
   cmd.action(async (url2, options, command) => {
     await executeHttpRequest(method, url2, options, command);
   });
   return cmd;
 }
-var webCommand = new Command("web").description("Make HTTP requests with automatic x402 payment support (GET, POST, PUT, PATCH, DELETE)").action(function() {
+var webCommand = new Command("web").description("Make HTTP requests with automatic x402 payment support (GET, POST, PUT, PATCH, DELETE)").addHelpText("after", `
+Examples:
+  use-agently web get https://api.example.com/data
+  use-agently web post https://api.example.com/data -d '{"key":"value"}' --pay`).action(function() {
   this.outputHelp();
 });
 webCommand.addCommand(createMethodSubcommand("get", "Make an HTTP GET request", false));
@@ -97234,6 +97216,9 @@ webCommand.addCommand(createMethodSubcommand("delete", "Make an HTTP DELETE requ
 
 // src/commands/doctor.ts
 var doctorCommand = new Command("doctor").description("Run environment checks and report any issues").option("--rpc <url>", "Custom RPC URL to use for network check").showHelpAfterError(true).addHelpText("after", `
+Examples:
+  use-agently doctor
+
 Config: ~/.use-agently/config.json (global), .use-agently/config.json (local)`).action(async (options, command) => {
   const checks3 = [];
   const config2 = await loadConfig();
@@ -97357,7 +97342,10 @@ var updateCommand = new Command("update").description("Update use-agently to the
 });
 
 // src/commands/wallet.ts
-var walletCommand = new Command("wallet").description("Manage wallet settings (spend limits)").action(function() {
+var walletCommand = new Command("wallet").description("Manage wallet settings (spend limits)").addHelpText("after", `
+Examples:
+  use-agently wallet spend
+  use-agently wallet spend set-max 0.5`).action(function() {
   this.outputHelp();
 });
 var spendCommand = new Command("spend").description("View or manage wallet spend limits").showHelpAfterError(true).addHelpText("after", `
@@ -97395,7 +97383,6 @@ cli.name("use-agently").description("Agently is the way AI coordinate and transa
 cli.addCommand(doctorCommand.helpGroup("Diagnostics"));
 cli.addCommand(whoamiCommand.helpGroup("Diagnostics"));
 cli.addCommand(balanceCommand.helpGroup("Diagnostics"));
-cli.addCommand(agentsCommand.helpGroup("Discovery"));
 cli.addCommand(searchCommand.helpGroup("Discovery"));
 cli.addCommand(viewCommand.helpGroup("Discovery"));
 cli.addCommand(a2aCommand.helpGroup("Protocols"));
@@ -97404,6 +97391,28 @@ cli.addCommand(webCommand.helpGroup("Protocols"));
 cli.addCommand(initCommand.helpGroup("Lifecycle"));
 cli.addCommand(walletCommand.helpGroup("Lifecycle"));
 cli.addCommand(updateCommand.helpGroup("Lifecycle"));
+cli.addHelpText("after", `
+Getting started: use-agently init → use-agently doctor → use-agently search
+
+Quick Reference:
+
+  Send a message or fetch an agent card via A2A:
+    a2a send -u <uri> -m <message> [--pay]
+    a2a card -u <uri>
+
+  List or call tools on an MCP server:
+    mcp tools -u <uri>
+    mcp call  -u <uri> --tool <name> [--args <json>] [--pay]
+
+  HTTP requests with x402 payment support:
+    web get|post|put|patch|delete <url> [-d <body>] [-H <header>] [-v] [--pay]
+
+  Manage wallet spend limits:
+    wallet spend
+    wallet spend set-max <value>
+
+  <uri> = HTTP URL or CAIP-19 ID (e.g. eip155:8453/erc8004:0x…/1)
+  Run "use-agently <command> -h" for full option details.`);
 function enableGlobalOptionsInHelp(cmd) {
   for (const sub of cmd.commands) {
     sub.configureHelp({ showGlobalOptions: true });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "use-agently",
-  "version": "0.28.0",
+  "version": "0.30.0",
   "description": "Use Agently CLI",
   "homepage": "https://use-agently.com",
   "bugs": "https://github.com/AgentlyHQ/use-agently/issues",
@@ -24,7 +24,7 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@use-agently/sdk": "0.28.0",
+    "@use-agently/sdk": "0.30.0",
     "boxen": "^8.0.1",
     "cli-table3": "^0.6.5",
     "commander": "^14.0.3",