feat: redesign CLI per USE-45 - space subcommands, --uri/--url options, new commands

Co-authored-by: fuxingloh <4266087+fuxingloh@users.noreply.github.com>

Author: Copilot

CLAUDE.md

@@ -36,7 +36,7 @@ All top-level commands use Turborepo (`turbo`) to orchestrate across packages.
 bun run --filter localhost-aixyz dev
 
 # Terminal 2 — send a message via the CLI
-use-agently a2a http://localhost:3000 -m "Hello!"
+use-agently a2a send --uri http://localhost:3000 -m "Hello!"
 ```
 
 The agent exposes a free endpoint (`accepts: { scheme: "free" }`), so no wallet balance is needed. Set `OPENAI_API_KEY` in `packages/localhost-aixyz/.env.local` before starting the dev server.
@@ -108,20 +108,19 @@ Commands are grouped into four categories. New commands must be placed in one of
 
 ### Subcommand Pattern
 
-Commands that have subcommands use a **colon separator**: `<command>:<subcommand>`.
+Commands that have subcommands use a **space separator**: `<command> <subcommand>`.
 
 ```
-use-agently marketplace:agents "query"
-use-agently a2a:card "uri"
-use-agently web:get "url"
+use-agently a2a send --uri "uri"
+use-agently a2a card --uri "uri"
+use-agently mcp tools --uri "uri"
+use-agently mcp call "tool" "args" --uri "uri"
+use-agently web get --uri "url"
 ```
 
-Shorthands (aliases) are allowed for frequently used commands:
+### URI / URL Interchangeability
 
-```
-use-agently m "query"           # alias for: use-agently marketplace
-use-agently m:agents "query"    # alias for: use-agently marketplace:agents
-```
+All protocol commands accept both `--uri` and `--url` as equivalent options. Either flag resolves to the same value.
 
 ### Full Command Reference
 
@@ -138,39 +137,33 @@ use-agently balance                # Show on-chain wallet balance
 #### Discovery
 
 ```bash
-use-agently marketplace            # List all agents/tools/skills on the marketplace
-use-agently marketplace "query"    # Search the marketplace
-use-agently marketplace:agents "query"   # Search agents specifically
-use-agently marketplace:tools "query"    # Search tools specifically
-use-agently marketplace:skills "query"   # Search skills specifically
-
-# Shorthands
-use-agently m "query"
-use-agently m:agents "query"
-use-agently m:tools "query"
-use-agently m:skills "query"
+use-agently agents                 # List all agents on the marketplace
+use-agently search [query]         # Search the marketplace
+use-agently search [query] --protocol a2a,mcp,web  # Filter by protocol(s)
 ```
 
 #### Operations
 
 ```bash
 use-agently init                   # Initialize a wallet and config
-use-agently config                 # Show or edit current configuration
 use-agently update                 # Update the CLI to the latest version
-use-agently wallets                # List and manage configured wallets
 ```
 
 #### Protocols
 
 ```bash
-use-agently erc-8004 "uri"         # Resolve an ERC-8004 agent URI
-use-agently a2a "uri/url"          # Send a message to an agent via A2A protocol
-use-agently a2a:card "uri/url"     # Fetch and display the A2A agent card
-use-agently mcp "uri/url"          # Connect to an MCP server
-
-use-agently web "url"              # HTTP GET (default method)
-use-agently web:get "url"          # HTTP GET
-use-agently web:put "url"          # HTTP PUT
+use-agently erc-8004 --uri "uri"                    # Resolve an ERC-8004 agent URI
+use-agently a2a send --uri "uri/url" -m "message"   # Send a message via A2A protocol
+use-agently a2a card --uri "uri/url"                # Fetch and display the A2A agent card
+use-agently mcp tools --uri "uri/url"               # List tools on an MCP server
+use-agently mcp call "tool" ["args"] --uri "uri/url" # Call a tool on an MCP server
+
+use-agently web get    --uri "url"                  # HTTP GET
+use-agently web post   --uri "url" -d '{"k":"v"}'  # HTTP POST
+use-agently web put    --uri "url" -d '{"k":"v"}'  # HTTP PUT
+use-agently web delete --uri "url"                  # HTTP DELETE
+use-agently web head   --uri "url"                  # HTTP HEAD
+use-agently web patch  --uri "url" -d '{"k":"v"}'  # HTTP PATCH
 ```
 
 ### Design Rules for New Commands
@@ -191,7 +184,7 @@ use-agently web:put "url"          # HTTP PUT
 
 5. **Structured output** — use exit codes to signal success/failure. For `--output json`, emit valid JSON to stdout so agents can parse results.
 
-6. **Colon subcommand convention** — use `command:subcommand` (colon separator) for protocol variants and marketplace filters. Register these as Commander.js commands named `"command:subcommand"`.
+6. **Space subcommand convention** — use `command subcommand` (space separator) for protocol variants. Do not use colon separators.
 
 ## Documentation
 

README.md

@@ -29,7 +29,7 @@ use-agently balance
 use-agently agents
 
 # Send a message to an agent (use the URI from `use-agently agents`)
-use-agently a2a <agent-uri> -m "Hello, agent!"
+use-agently a2a send --uri <agent-uri> -m "Hello, agent!"
 ```
 
 ## Commands
@@ -94,19 +94,67 @@ List available agents on Agently.
 use-agently agents
 ```
 
+### `search`
+
+Search the Agently marketplace for agents, optionally filtering by query and/or protocol.
+
+```bash
+use-agently search
+use-agently search "echo"
+use-agently search --protocol a2a
+use-agently search "assistant" --protocol "a2a,mcp"
+```
+
 ### `a2a`
 
-Send a message to an agent via the A2A protocol. The `<agent-uri>` is the identifier shown by `use-agently agents` (e.g. `echo-agent`). The CLI resolves it to `https://use-agently.com/<agent-uri>/`. Payments are handled automatically via x402 when agents require them.
+Interact with agents via the A2A protocol. Both `--uri` and `--url` are accepted. The identifier is resolved to `https://use-agently.com/<agent-uri>/` if it is not a full URL. Payments are handled automatically via x402 when agents require them.
+
+```bash
+# Send a message
+use-agently a2a send --uri <agent-uri> -m "What can you do?"
+
+# Fetch the agent card
+use-agently a2a card --uri <agent-uri>
+```
+
+### `mcp`
+
+Connect to an MCP server to list or call tools.
+
+```bash
+# List tools
+use-agently mcp tools --uri http://localhost:3000
+
+# Call a tool
+use-agently mcp call echo '{"message":"hello"}' --uri http://localhost:3000
+```
+
+### `erc-8004`
+
+Resolve an ERC-8004 agent URI and display its details from the Agently marketplace.
+
+```bash
+use-agently erc-8004 --uri eip155:8453/erc-8004:0x1234/1
+```
+
+### `web`
+
+Make HTTP requests. Supports all standard HTTP methods. Both `--uri` and `--url` are accepted.
 
 ```bash
-use-agently a2a <agent-uri> -m "What can you do?"
+use-agently web get    --uri https://example.com/api
+use-agently web post   --uri https://example.com/api -d '{"key":"value"}'
+use-agently web put    --uri https://example.com/api -d '{"key":"value"}'
+use-agently web delete --uri https://example.com/api
+use-agently web head   --uri https://example.com/api
+use-agently web patch  --uri https://example.com/api -d '{"key":"value"}'
 ```
 
 ## 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` fetches the agent directory from Agently, showing names, descriptions, supported protocols, and URIs.
-3. **Communication** — `a2a` 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.
+2. **Discovery** — `agents` and `search` fetch 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
 

packages/use-agently/src/cli.ts

@@ -3,8 +3,11 @@ import { initCommand } from "./commands/init";
 import { whoamiCommand } from "./commands/whoami";
 import { balanceCommand } from "./commands/balance";
 import { agentsCommand } from "./commands/agents";
-import { a2aCommand, a2aCardCommand } from "./commands/a2a";
+import { searchCommand } from "./commands/search";
+import { a2aCommand } from "./commands/a2a";
 import { mcpCommand } from "./commands/mcp";
+import { erc8004Command } from "./commands/erc8004";
+import { webCommand } from "./commands/web";
 import { doctorCommand } from "./commands/doctor";
 import { updateCommand } from "./commands/update";
 
@@ -30,11 +33,13 @@ cli.addCommand(balanceCommand.helpGroup("Diagnostics"));
 
 // Discovery
 cli.addCommand(agentsCommand.helpGroup("Discovery"));
+cli.addCommand(searchCommand.helpGroup("Discovery"));
 
 // Protocols
 cli.addCommand(a2aCommand.helpGroup("Protocols"));
-cli.addCommand(a2aCardCommand.helpGroup("Protocols"));
 cli.addCommand(mcpCommand.helpGroup("Protocols"));
+cli.addCommand(erc8004Command.helpGroup("Protocols"));
+cli.addCommand(webCommand.helpGroup("Protocols"));
 
 // Lifecycle
 cli.addCommand(initCommand.helpGroup("Lifecycle"));

packages/use-agently/src/commands/a2a.test.ts

@@ -51,33 +51,65 @@ describe("a2a command", () => {
     const out = captureOutput();
 
     test("text output", async () => {
-      await cli.parseAsync(["test", "use-agently", "a2a", agent.getAgentUrl() + "/free-echo/", "-m", "hello world"]);
+      await cli.parseAsync([
+        "test",
+        "use-agently",
+        "a2a",
+        "send",
+        "--uri",
+        agent.getAgentUrl() + "/free-echo/",
+        "-m",
+        "hello world",
+      ]);
       expect(out.stdout).toBe("hello world");
     });
 
     test("streams text output 10 times", async () => {
-      await cli.parseAsync(["test", "use-agently", "a2a", agent.getAgentUrl() + "/free-echo-10/", "-m", "hi"]);
+      await cli.parseAsync([
+        "test",
+        "use-agently",
+        "a2a",
+        "send",
+        "--uri",
+        agent.getAgentUrl() + "/free-echo-10/",
+        "-m",
+        "hi",
+      ]);
       // free-echo-10 streams the message back 10 times with 200ms delays between each chunk
       const expected = "hi\nhi\nhi\nhi\nhi\nhi\nhi\nhi\nhi\nhi";
       expect(out.stdout).toBe(expected);
     }, 15000);
+
+    test("--url alias works", async () => {
+      await cli.parseAsync([
+        "test",
+        "use-agently",
+        "a2a",
+        "send",
+        "--url",
+        agent.getAgentUrl() + "/free-echo/",
+        "-m",
+        "hello url",
+      ]);
+      expect(out.stdout).toBe("hello url");
+    });
   });
 });
 
-describe("a2a:card command", () => {
+describe("a2a card command", () => {
   describe("cli", () => {
     const out = captureOutput();
 
     test("text output returns agent card fields", async () => {
-      await cli.parseAsync(["test", "use-agently", "a2a:card", agent.getAgentUrl()]);
+      await cli.parseAsync(["test", "use-agently", "a2a", "card", "--uri", agent.getAgentUrl()]);
       const card = out.yaml as Record<string, unknown>;
       expect(card).toHaveProperty("name");
       expect(card).toHaveProperty("description");
       expect(card).toHaveProperty("url");
     });
 
     test("json output returns agent card as JSON", async () => {
-      await cli.parseAsync(["test", "use-agently", "-o", "json", "a2a:card", agent.getAgentUrl()]);
+      await cli.parseAsync(["test", "use-agently", "-o", "json", "a2a", "card", "--uri", agent.getAgentUrl()]);
       const card = out.json as Record<string, unknown>;
       expect(card).toHaveProperty("name");
       expect(card).toHaveProperty("description");

packages/use-agently/src/commands/a2a.ts

@@ -58,15 +58,37 @@ function extractStreamEventText(event: any): string {
   return "";
 }
 
+function resolveUriOption(options: { uri?: string; url?: string }, commandName: string): string {
+  const value = options.uri || options.url;
+  if (!value) {
+    throw new Error(
+      `Missing required option --uri for '${commandName}'.\nExpected a URL or agent URI, e.g. --uri https://example.com/agent or --uri echo-agent`,
+    );
+  }
+  return value;
+}
+
 export const a2aCommand = new Command("a2a")
+  .description("Interact with agents via the A2A protocol")
+  .action(function () {
+    (this as Command).outputHelp();
+  });
+
+const a2aSendCommand = new Command("send")
   .description("Send a message to an agent via A2A protocol")
-  .argument("<agent>", "Agent URI")
+  .option("--uri <value>", "Agent URI or URL (e.g. https://example.com/agent or echo-agent)")
+  .option("--url <value>", "Agent URI or URL (alias for --uri)")
   .requiredOption("-m, --message <text>", "Message to send")
-  .action(async (agentUri: string, options: { message: string }) => {
+  .addHelpText(
+    "after",
+    '\nExamples:\n  use-agently a2a send --uri https://example.com/agent -m "Hello!"\n  use-agently a2a send --uri echo-agent -m "Hello!"',
+  )
+  .action(async (options: { uri?: string; url?: string; message: string }) => {
+    const agentInput = resolveUriOption(options, "a2a send");
     const config = await getConfigOrThrow();
     const wallet = loadWallet(config.wallet);
     const paymentFetch = createPaymentFetch(wallet);
-    const agentUrl = resolveAgentUrl(agentUri);
+    const agentUrl = resolveAgentUrl(agentInput);
     const client = await createA2AClient(agentUrl, paymentFetch as typeof fetch);
 
     const stream = client.sendMessageStream({
@@ -96,16 +118,21 @@ export const a2aCommand = new Command("a2a")
     }
   });
 
-export const a2aCardCommand = new Command("a2a:card")
+const a2aCardSubCommand = new Command("card")
   .description("Fetch and display the A2A agent card")
-  .argument("<agent>", "Agent URL or URI (e.g. https://example.com/agent or my-agent)")
+  .option("--uri <value>", "Agent URI or URL (e.g. https://example.com/agent or echo-agent)")
+  .option("--url <value>", "Agent URI or URL (alias for --uri)")
   .addHelpText(
     "after",
-    "\nExamples:\n  use-agently a2a:card https://example.com/agent\n  use-agently a2a:card my-agent",
+    "\nExamples:\n  use-agently a2a card --uri https://example.com/agent\n  use-agently a2a card --uri echo-agent",
   )
-  .action(async (agentInput: string, _options: Record<string, never>, command: Command) => {
+  .action(async (options: { uri?: string; url?: string }, command: Command) => {
+    const agentInput = resolveUriOption(options, "a2a card");
     const agentUrl = resolveAgentUrl(agentInput);
     const resolver = new DefaultAgentCardResolver();
     const card = await resolver.resolve(agentUrl);
     output(command, card);
   });
+
+a2aCommand.addCommand(a2aSendCommand);
+a2aCommand.addCommand(a2aCardSubCommand);