@perfolio/cli

Command-line interface for Perfolio — manage a gold-backed, multi-asset portfolio from the terminal. Buy and sell assets, borrow cash against them, and check balances and positions, all in plain language.

This CLI is the substrate for the perfolio agent skill: every capability is a subcommand, so an agent can manage a portfolio without constructing HTTP requests.

Plain language, not crypto jargon

You never type tickers, token addresses, chains, or market IDs. You speak in four everyday words:

| You say | Under the hood | |-------------|----------------| | gold | XAUT | | cash | USDT | | bitcoin | WBTC | | ethereum| WETH |

Every trade is buy/sell an asset for cash. Every loan is borrow cash against an asset. That's the whole mental model.

Install

Project-scoped (recommended — never install globally):

npx @perfolio/cli --version

Environment: this build targets the Perfolio production environment (api.perfolio.ai / app.perfolio.ai). Override any endpoint with PERFOLIO_API_URL, PERFOLIO_FIAT_URL, PERFOLIO_WIDGET_URL, or PERFOLIO_APP_URL (e.g. point at api-dev.perfolio.ai for dogfooding).

Install as an agent skill

To give a coding agent (Claude Code, Codex, Cursor, …) the ability to drive this CLI, install the bundled skill with the universal skills CLI:

npx skills@latest add Billion-Impact/perfolio-cli

Pick perfolio-cli when prompted and choose your agent(s). The skill lives at skills/perfolio-cli/SKILL.md and only needs Node 18+ — it shells out to npx @perfolio/cli@latest, so there's nothing else to set up. Once installed, just ask your agent things like "buy $50 of gold" or "what's my balance".

Quick start

# 1. Authenticate (opens the browser for email-OTP login)
perfolio login

# 2. See what you can hold and where you can borrow
perfolio assets
perfolio markets

# 3. Check your holdings
perfolio balance

# 4. Buy $500 of gold (and wait for confirmation)
perfolio buy gold --amount 500 --wait

# 5. Borrow $1,000 cash against your gold
perfolio borrow --against gold --amount 1000 --wait

Global flags

| Flag | Env var | Notes | |---|---|---| | --json | — | machine-readable JSON output (use this from agents/scripts) | | --creds-file <path> | PERFOLIO_CREDS_FILE | override ~/.perfolio/credentials |

Backend URLs are configurable via PERFOLIO_API_URL, PERFOLIO_FIAT_URL, PERFOLIO_WIDGET_URL (default to production).

Commands

Auth & session

perfolio login [--force]      Authenticate via browser handshake
perfolio logout               Clear local credentials
perfolio whoami               Show the authenticated account
perfolio status               Login + agent-access (session-key) health
perfolio session grant        One-time browser approval to enable autonomous operations
perfolio session status       Agent-access status

Discovery

perfolio assets               Assets you can hold (gold, cash, bitcoin, ethereum)
perfolio markets              Where you can borrow cash against your assets, with max LTV

Balances & positions

perfolio balance              Your holdings across all assets
perfolio portfolio            Net value and allocation
perfolio loans                All open "cash borrowed against X" positions
perfolio position --against gold   Detail for one loan (collateral, debt, LTV)

Market data

perfolio prices               Current prices for gold, bitcoin, ethereum, cash
perfolio rate [--against gold]     Borrow rate + stats for a market

Trade (cash ⇄ asset)

perfolio quote --from cash --to gold --amount 500    Preview a trade
perfolio buy  <asset> --amount <cash> [--wait]       Buy an asset with cash
perfolio sell <asset> --amount <n>   [--wait]        Sell an asset for cash
perfolio convert --from <asset> --to <asset> --amount <n> [--wait]

Borrow & collateral

perfolio borrow  --against <asset> --amount <cash> [--wait]
perfolio repay   --against <asset> --amount <cash> [--wait]
perfolio add-collateral    --asset <asset> --amount <n> [--wait]
perfolio remove-collateral --asset <asset> --amount <n> [--wait]
perfolio leverage --asset <asset> --deposit <n> --borrow <cash> [--wait]
perfolio close   --against <asset> [--yes] [--wait]

Account (read-only + settings)

perfolio kyc status                          KYC verification state
perfolio fiat quote --amount 500 --currency AED   Cash-out quote (quote only)
perfolio beneficiaries                       Payout bank accounts
perfolio settings set [--currency AED] [--gold-unit g|oz] [--country AE] [--display usd|local]
perfolio gifts                               Gifts sent and received

Amounts are decimals

You always pass human decimals (0.5, 500, 1.25). For cash-denominated flags (--amount on buy/borrow/repay, --borrow on leverage) the number is dollars of cash. The backend converts to on-chain units; you never touch wei.

Submitted ≠ confirmed

A submitted transaction is not a completed one. Without --wait, write commands print the operation id and tell you to verify with perfolio balance / perfolio loans. With --wait, the CLI polls until the operation reaches completed or failed and reports the verified outcome. A pending result is never reported as success.

Agent access (session keys)

Trades and borrows run with a Biconomy session key — no per-operation signature. The first time you run one, the backend may return "agent access required" (HTTP 428). Set it up once:

perfolio session grant

This opens a one-time browser approval. After that, the agent operates autonomously. Reads (balance, assets, prices, …) only need login.

What this CLI does NOT do (v1)

• Withdraw-to-bank execution and any user-signed transfer (use the web app)
• Sending gifts (read-only gifts only)
• Card operations
• Non-canonical asset variants (cbBTC, wstETH, USDC) as commands
• Non-Ethereum chains

Credentials

perfolio login writes a bearer token to ~/.perfolio/credentials with 0600 perms. The CLI reads it on every call. perfolio logout clears it. No private keys ever touch the CLI — signing is either session-key (agent signer, backend-held) or excluded.

Architecture

src/
├── lib/              # pure, exported — downstream tooling imports this
│   ├── client.ts     # PerfolioClient (typed over the backend routes)
│   ├── config.ts     # creds file I/O (0600) + base URLs
│   ├── assets.ts     # friendly-name ⇄ symbol resolver (registry-driven)
│   ├── amounts.ts    # decimal validation + display formatting
│   ├── relay.ts      # browser-handshake login + relay polling
│   ├── errors.ts     # backend-code → friendly message
│   └── types.ts
└── cli/
    ├── index.ts      # commander entry + global flags
    ├── helpers.ts    # auth-aware client factory + printers
    ├── verify.ts     # --wait tx verification
    └── commands/     # one file per command group

The lib/ module is exported from the package so downstream tooling (e.g. an MCP server) can import the client directly instead of shelling out to the CLI.