@agentis-hq/cli 0.1.0 → 0.1.1

package/README.md

@@ -0,0 +1,283 @@
+# Agentis CLI
+
+Command line tools for Agentis, the financial infrastructure layer for AI agents on Solana.
+
+The CLI lets you create agent wallets, manage spend policies, pay MPP and x402 URLs, work with Umbra privacy flows, deposit idle USDC into Jupiter Earn, and scaffold x402 facilitators.
+
+![Agentis CLI help](./assets/agentis-help.png)
+
+> Add the screenshot at `packages/cli/assets/agentis-help.png` before publishing if it is not already present in the package.
+
+## Install
+
+Run without installing:
+
+```bash
+npx @agentis-hq/cli --help
+```
+
+Or install globally:
+
+```bash
+npm install -g @agentis-hq/cli
+agentis --help
+```
+
+With Bun:
+
+```bash
+bun x @agentis-hq/cli --help
+```
+
+## Backend URL
+
+By default, the CLI talks to the hosted Agentis API:
+
+```bash
+https://api.agentis.systems
+```
+
+To point the CLI at a local or self-hosted backend:
+
+```bash
+AGENTIS_API_URL=http://localhost:3001 agentis agent list
+```
+
+## Authentication
+
+Hosted wallets and hosted agents require an Agentis account key. The CLI gets one through the browser login flow and stores it in your OS keychain.
+
+```bash
+agentis login
+agentis whoami
+agentis logout
+```
+
+Local encrypted wallets do not require login.
+
+## Wallets
+
+Create a hosted wallet when logged in:
+
+```bash
+agentis wallet create --name my-agent
+```
+
+Create a local encrypted wallet:
+
+```bash
+agentis wallet create --name local-agent --local
+```
+
+List hosted and local wallets:
+
+```bash
+agentis wallet list
+```
+
+## Hosted Agents
+
+List agents:
+
+```bash
+agentis agent list
+```
+
+Create a hosted agent:
+
+```bash
+agentis agent create research-agent
+```
+
+Create an agent in Quasar on-chain policy mode:
+
+```bash
+agentis agent create policy-agent --onchain-policy
+```
+
+Check balances:
+
+```bash
+agentis agent balance research-agent
+```
+
+Send SOL. Amount is lamports by default:
+
+```bash
+agentis agent send research-agent <recipient-wallet> 1000000
+```
+
+Send using SOL units:
+
+```bash
+agentis agent send research-agent <recipient-wallet> 0.01 --sol
+```
+
+## Paid Fetch
+
+Fetch a URL and let Agentis automatically pay MPP or x402 payment requests through the selected hosted agent:
+
+```bash
+agentis fetch https://example.com/paid-data --agent research-agent
+```
+
+Use a different HTTP method:
+
+```bash
+agentis fetch https://example.com/paid-data --agent research-agent --method POST
+```
+
+## Policies
+
+Read an agent or local wallet policy:
+
+```bash
+agentis policy get research-agent
+```
+
+Set limits:
+
+```bash
+agentis policy set research-agent --max-per-tx 1 --daily 10 --budget 100
+```
+
+Allow or remove domains:
+
+```bash
+agentis policy set research-agent --allow api.example.com
+agentis policy set research-agent --disallow api.example.com
+```
+
+Stop or resume spending:
+
+```bash
+agentis policy set research-agent --kill
+agentis policy set research-agent --resume
+```
+
+Initialize on-chain policy PDAs for an on-chain policy agent after funding the wallet:
+
+```bash
+agentis policy init-onchain policy-agent
+```
+
+## Jupiter Earn
+
+Jupiter Earn support is mainnet-only. USDC amounts use UI units.
+
+Deposit USDC into Jupiter Earn:
+
+```bash
+agentis earn deposit research-agent --asset USDC --amount 1 --mainnet
+```
+
+Show positions:
+
+```bash
+agentis earn positions research-agent --mainnet
+agentis earn positions research-agent --mainnet --all
+```
+
+Sweep non-zero mainnet USDC balances across hosted agents into Jupiter Earn:
+
+```bash
+agentis earn sweep --dry-run
+agentis earn sweep --no-dry-run
+```
+
+## Umbra Privacy
+
+Umbra commands operate on hosted agent wallets.
+
+Register an agent:
+
+```bash
+agentis privacy register --agent private-agent
+```
+
+Check status and encrypted balance:
+
+```bash
+agentis privacy status --agent private-agent
+agentis privacy balance --agent private-agent
+```
+
+Deposit or withdraw encrypted balance:
+
+```bash
+agentis privacy deposit --agent private-agent --amount 1000000
+agentis privacy withdraw --agent private-agent --amount 500000
+```
+
+Create and claim receiver-claimable UTXOs:
+
+```bash
+agentis privacy create-utxo --agent private-agent --to <receiver-wallet> --amount 1000000
+agentis privacy scan --agent private-agent
+agentis privacy claim-latest --agent private-agent
+```
+
+## Facilitators
+
+Agentis can scaffold Kora-backed x402 facilitators and register them with the Agentis facilitator network.
+
+Create a facilitator project:
+
+```bash
+agentis facilitator create my-facilitator
+```
+
+Create with custom settings:
+
+```bash
+agentis facilitator create my-facilitator --dir ./facilitator --fee-bps 500 --listed
+```
+
+List facilitators:
+
+```bash
+agentis facilitator list
+```
+
+Publish a public URL and optionally opt into discovery:
+
+```bash
+agentis facilitator publish my-facilitator --url https://facilitator.example.com --listed
+```
+
+## Command Help
+
+Every command and subcommand supports `--help`:
+
+```bash
+agentis --help
+agentis wallet create --help
+agentis agent send --help
+agentis fetch --help
+agentis earn deposit --help
+agentis privacy create-utxo --help
+agentis facilitator publish --help
+```
+
+## Local Development
+
+From the monorepo:
+
+```bash
+cd packages/cli
+bun src/index.ts --help
+```
+
+Point at a local backend:
+
+```bash
+AGENTIS_API_URL=http://localhost:3001 bun src/index.ts agent list
+```
+
+## Notes
+
+- Hosted agent keys are shown only when created or regenerated.
+- CLI account keys are stored in the OS keychain.
+- Local wallet vaults live under `~/.agentis/wallets/`.
+- Jupiter Earn commands require mainnet and the `--mainnet` safety flag.
+- Umbra devnet flows are currently safest with SOL or wSOL.

package/dist/index.js

@@ -1273,6 +1273,254 @@ var green = "\x1B[38;5;114m";
 var muted = "\x1B[38;5;244m";
 var bold = "\x1B[1m";
 var reset = "\x1B[0m";
+var helpSpecs = {
+  login: {
+    usage: "agentis login",
+    description: "Authenticate with your Agentis account and store an account API key in your OS keychain."
+  },
+  logout: {
+    usage: "agentis logout",
+    description: "Remove stored Agentis CLI credentials from your OS keychain."
+  },
+  whoami: {
+    usage: "agentis whoami",
+    description: "Show the currently authenticated Agentis account key in masked form."
+  },
+  wallet: {
+    usage: "agentis wallet <command>",
+    description: "Create and list hosted or local Solana wallets.",
+    commands: [
+      ["create --name <name> [--local]", "create a hosted wallet, or a local encrypted wallet with --local"],
+      ["list", "list hosted and local wallets"]
+    ]
+  },
+  "wallet create": {
+    usage: "agentis wallet create --name <name> [--local]",
+    description: "Create a hosted Agentis wallet when logged in, or a local encrypted wallet when --local is provided.",
+    options: [
+      ["--name <name>", "wallet name"],
+      ["--local", "create a local encrypted wallet instead of a hosted Agentis wallet"],
+      ["-h, --help", "display help for command"]
+    ]
+  },
+  "wallet list": {
+    usage: "agentis wallet list",
+    description: "List hosted wallets from Agentis and local encrypted wallets on this machine.",
+    options: [["-h, --help", "display help for command"]]
+  },
+  agent: {
+    usage: "agentis agent <command>",
+    description: "Manage hosted agents and send funds from hosted or local wallets.",
+    commands: [
+      ["list", "list hosted agents"],
+      ["create <name> [--onchain-policy]", "create a hosted agent"],
+      ["balance <name-or-id>", "show SOL and token balances"],
+      ["send <name-or-id> <to> <amount> [options]", "send SOL from an agent or local wallet"]
+    ]
+  },
+  "agent list": {
+    usage: "agentis agent list",
+    description: "List hosted agents owned by your Agentis account.",
+    options: [["-h, --help", "display help for command"]]
+  },
+  "agent create": {
+    usage: "agentis agent create <name> [--onchain-policy]",
+    description: "Create a hosted agent wallet and return its wallet address and API key.",
+    options: [
+      ["--onchain-policy", "create the agent in Quasar on-chain policy mode"],
+      ["-h, --help", "display help for command"]
+    ]
+  },
+  "agent balance": {
+    usage: "agentis agent balance <name-or-id>",
+    description: "Show SOL and known SPL token balances for a hosted agent or local wallet.",
+    options: [["-h, --help", "display help for command"]]
+  },
+  "agent send": {
+    usage: "agentis agent send <name-or-id> <to> <amount> [options]",
+    description: "Send SOL from a hosted agent or local encrypted wallet. Amount is lamports by default.",
+    options: [
+      ["--sol", "treat amount as SOL instead of lamports"],
+      ["--token <mint>", "send an SPL token by mint address; currently not implemented"],
+      ["-h, --help", "display help for command"]
+    ]
+  },
+  fetch: {
+    usage: "agentis fetch <url> --agent <name-or-id> [options]",
+    description: "Fetch a URL and automatically pay MPP or x402 payment requests through the selected hosted agent.",
+    options: [
+      ["--agent <name-or-id>", "hosted agent to pay from"],
+      ["--method <method>", "HTTP method to use; defaults to GET"],
+      ["-h, --help", "display help for command"]
+    ]
+  },
+  earn: {
+    usage: "agentis earn <command>",
+    description: "Manage Jupiter Earn deposits and positions for hosted agent wallets.",
+    commands: [
+      ["deposit <agent> --asset USDC --amount <amount> --mainnet", "deposit mainnet USDC into Jupiter Earn"],
+      ["positions <agent> --mainnet [--all]", "show Jupiter Earn positions"],
+      ["sweep [--dry-run|--no-dry-run]", "sweep all hosted agents mainnet USDC into Jupiter Earn"]
+    ]
+  },
+  "earn deposit": {
+    usage: "agentis earn deposit <agent> --asset USDC --amount <amount> --mainnet",
+    description: "Deposit mainnet USDC from a hosted agent wallet into Jupiter Earn.",
+    options: [
+      ["--asset USDC", "asset to deposit; currently USDC"],
+      ["--amount <amount>", "UI amount, for example 1 for 1 USDC"],
+      ["--mainnet", "required safety flag"],
+      ["-h, --help", "display help for command"]
+    ]
+  },
+  "earn positions": {
+    usage: "agentis earn positions <agent> --mainnet [--all]",
+    description: "Show Jupiter Earn positions for a hosted agent wallet.",
+    options: [
+      ["--mainnet", "required safety flag"],
+      ["--all", "show empty vaults as well as non-zero positions"],
+      ["-h, --help", "display help for command"]
+    ]
+  },
+  "earn sweep": {
+    usage: "agentis earn sweep [--dry-run|--no-dry-run]",
+    description: "Read all hosted agents mainnet USDC balances and deposit non-zero balances into Jupiter Earn.",
+    options: [
+      ["--dry-run", "print the sweep plan only"],
+      ["--no-dry-run", "execute directly without first printing the dry-run plan"],
+      ["-h, --help", "display help for command"]
+    ]
+  },
+  privacy: {
+    usage: "agentis privacy <command> --agent <name-or-id>",
+    description: "Use Umbra privacy flows for hosted agent wallets.",
+    commands: [
+      ["status --agent <name-or-id>", "show Umbra registration status"],
+      ["register --agent <name-or-id>", "register with Umbra"],
+      ["balance --agent <name-or-id> [--mint <mint>]", "show encrypted balance"],
+      ["deposit --agent <name-or-id> --amount <atomic> [--mint <mint>]", "deposit into encrypted balance"],
+      ["withdraw --agent <name-or-id> --amount <atomic> [--mint <mint>]", "withdraw encrypted balance"],
+      ["create-utxo --agent <name-or-id> --to <wallet> --amount <atomic>", "create receiver-claimable UTXO"],
+      ["scan --agent <name-or-id>", "scan claimable UTXOs"],
+      ["claim-latest --agent <name-or-id>", "claim latest publicReceived UTXO"]
+    ]
+  },
+  "privacy status": {
+    usage: "agentis privacy status --agent <name-or-id>",
+    description: "Show direct Umbra account status for a hosted agent.",
+    options: [["--agent <name-or-id>", "hosted agent"], ["-h, --help", "display help for command"]]
+  },
+  "privacy register": {
+    usage: "agentis privacy register --agent <name-or-id> [options]",
+    description: "Register a hosted agent wallet with Umbra.",
+    options: [
+      ["--agent <name-or-id>", "hosted agent"],
+      ["--no-confidential", "disable confidential mode during registration"],
+      ["--no-anonymous", "disable anonymous mode during registration"],
+      ["-h, --help", "display help for command"]
+    ]
+  },
+  "privacy balance": {
+    usage: "agentis privacy balance --agent <name-or-id> [--mint <mint>]",
+    description: "Show encrypted Umbra balance for a hosted agent.",
+    options: [["--agent <name-or-id>", "hosted agent"], ["--mint <mint>", "token mint"], ["-h, --help", "display help for command"]]
+  },
+  "privacy deposit": {
+    usage: "agentis privacy deposit --agent <name-or-id> --amount <atomic> [--mint <mint>]",
+    description: "Deposit public funds into an encrypted Umbra balance.",
+    options: [["--agent <name-or-id>", "hosted agent"], ["--amount <atomic>", "token amount in atomic units"], ["--mint <mint>", "token mint"], ["-h, --help", "display help for command"]]
+  },
+  "privacy withdraw": {
+    usage: "agentis privacy withdraw --agent <name-or-id> --amount <atomic> [--mint <mint>]",
+    description: "Withdraw an encrypted Umbra balance to the public wallet balance.",
+    options: [["--agent <name-or-id>", "hosted agent"], ["--amount <atomic>", "token amount in atomic units"], ["--mint <mint>", "token mint"], ["-h, --help", "display help for command"]]
+  },
+  "privacy create-utxo": {
+    usage: "agentis privacy create-utxo --agent <name-or-id> --to <wallet> --amount <atomic> [--mint <mint>]",
+    description: "Create a receiver-claimable Umbra UTXO for another wallet.",
+    options: [["--agent <name-or-id>", "hosted agent"], ["--to <wallet>", "receiver wallet address"], ["--amount <atomic>", "token amount in atomic units"], ["--mint <mint>", "token mint"], ["-h, --help", "display help for command"]]
+  },
+  "privacy scan": {
+    usage: "agentis privacy scan --agent <name-or-id>",
+    description: "Scan Umbra for UTXOs claimable by the hosted agent.",
+    options: [["--agent <name-or-id>", "hosted agent"], ["-h, --help", "display help for command"]]
+  },
+  "privacy claim-latest": {
+    usage: "agentis privacy claim-latest --agent <name-or-id>",
+    description: "Claim the latest publicReceived Umbra UTXO for the hosted agent.",
+    options: [["--agent <name-or-id>", "hosted agent"], ["-h, --help", "display help for command"]]
+  },
+  facilitator: {
+    usage: "agentis facilitator <command>",
+    description: "Create, list, and publish Agentis x402 facilitator scaffolds.",
+    commands: [
+      ["create <name> [options]", "register and scaffold a Kora-backed x402 facilitator"],
+      ["list", "list registered facilitators"],
+      ["publish <name-or-id> --url <public-url> [--listed]", "publish public URL and discovery settings"]
+    ]
+  },
+  "facilitator create": {
+    usage: "agentis facilitator create <name> [options]",
+    description: "Register a facilitator in Agentis and scaffold a Kora-backed x402 facilitator project.",
+    options: [
+      ["--dir <path>", "output directory"],
+      ["--network <network>", "accepted network; defaults to Solana devnet CAIP-2"],
+      ["--mint <mint>", "accepted token mint; defaults to devnet USDC"],
+      ["--fee-bps <bps>", "seller prepaid fee rate; defaults to 500"],
+      ["--listed", "opt into public facilitator discovery"],
+      ["-h, --help", "display help for command"]
+    ]
+  },
+  "facilitator list": {
+    usage: "agentis facilitator list",
+    description: "List facilitators registered to your Agentis account.",
+    options: [["-h, --help", "display help for command"]]
+  },
+  "facilitator publish": {
+    usage: "agentis facilitator publish <name-or-id> --url <public-url> [--listed]",
+    description: "Set a facilitator public URL and optionally list it in public discovery.",
+    options: [
+      ["--url <public-url>", "public facilitator endpoint URL"],
+      ["--listed", "opt into public facilitator discovery"],
+      ["-h, --help", "display help for command"]
+    ]
+  },
+  policy: {
+    usage: "agentis policy <command>",
+    description: "Read, update, and initialize agent spend policies.",
+    commands: [
+      ["get <name-or-id>", "show agent policy"],
+      ["set <name-or-id> [flags]", "update agent policy"],
+      ["init-onchain <name-or-id>", "initialize Quasar policy PDAs after funding"]
+    ]
+  },
+  "policy get": {
+    usage: "agentis policy get <name-or-id>",
+    description: "Show policy settings for a hosted agent or local wallet.",
+    options: [["-h, --help", "display help for command"]]
+  },
+  "policy set": {
+    usage: "agentis policy set <name-or-id> [flags]",
+    description: "Update policy settings for a hosted agent or local wallet.",
+    options: [
+      ["--kill", "activate kill switch"],
+      ["--resume", "deactivate kill switch"],
+      ["--max-per-tx <usd>", "max spend per transaction"],
+      ["--hourly <usd>", "hourly spend limit"],
+      ["--daily <usd>", "daily spend limit"],
+      ["--monthly <usd>", "monthly spend limit"],
+      ["--budget <usd>", "total lifetime budget cap"],
+      ["--allow <domain>", "add domain to whitelist"],
+      ["--disallow <domain>", "remove domain from whitelist"],
+      ["-h, --help", "display help for command"]
+    ]
+  },
+  "policy init-onchain": {
+    usage: "agentis policy init-onchain <name-or-id>",
+    description: "Initialize Quasar policy PDAs for an on-chain policy hosted agent after the wallet is funded.",
+    options: [["-h, --help", "display help for command"]]
+  }
+};
 function showHelp() {
   console.log(`${blue}${bold}
  \u2588\u2588\u2588\u2588\u2588\u2557  \u2588\u2588\u2588\u2588\u2588\u2588\u2557 \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2557\u2588\u2588\u2588\u2557   \u2588\u2588\u2557\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2557\u2588\u2588\u2557\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2557
@@ -1344,7 +1592,42 @@ ${green}${bold}Commands:${reset}
     --disallow <domain>                    remove domain from whitelist
 `);
 }
+function hasHelpFlag(values) {
+  return values.includes("--help") || values.includes("-h");
+}
+function helpPath(values) {
+  return values.filter((value) => value !== "--help" && value !== "-h").slice(0, 2).join(" ");
+}
+function printRows(title, rows) {
+  console.log(`
+${green}${bold}${title}:${reset}`);
+  for (const [left, right] of rows) {
+    console.log(`  ${left.padEnd(38)} ${right}`);
+  }
+}
+function showCommandHelp(path) {
+  if (!path) {
+    showHelp();
+    return;
+  }
+  const spec = helpSpecs[path] ?? helpSpecs[path.split(" ")[0]];
+  if (!spec) {
+    showHelp();
+    return;
+  }
+  console.log(`${bold}Usage:${reset} ${spec.usage}
+`);
+  console.log(spec.description);
+  if (spec.commands) printRows("Commands", spec.commands);
+  if (spec.options) printRows("Options", spec.options);
+  if (spec.examples) printRows("Examples", spec.examples.map((example) => [example, ""]));
+  console.log();
+}
 async function main() {
+  if (!cmd || hasHelpFlag(args)) {
+    showCommandHelp(helpPath(args));
+    return;
+  }
   switch (cmd) {
     case "login":
       await login();

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@agentis-hq/cli",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "type": "module",
   "bin": {
-    "agentis": "./dist/index.js"
+    "agentis": "dist/index.js"
   },
   "description": "Agentis CLI",
   "exports": {
@@ -12,6 +12,8 @@
   "files": [
     "dist",
     "templates",
+    "assets",
+    "README.md",
     "package.json"
   ],
   "scripts": {