@perfolio/cli-dev

Command-line interface for Perfolio (DEV build) — 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 is the development build. It targets the Perfolio dev environment (api-dev.perfolio.ai / app-dev.perfolio.ai) and installs the binary as perfolio-dev. For production, use the @perfolio/cli package.

This CLI is the substrate for the perfolio-cli-dev 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-dev --version

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

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-dev when prompted and choose your agent(s). The skill lives at skills/perfolio-cli-dev/SKILL.md and only needs Node 18+ — it shells out to npx @perfolio/cli-dev@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-dev login

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

# 3. Check your holdings
perfolio-dev balance

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

# 5. Borrow $1,000 cash against your gold
perfolio-dev 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-dev |

Backend URLs are configurable via PERFOLIO_API_URL, PERFOLIO_FIAT_URL, PERFOLIO_WIDGET_URL (default to the dev environment).

Commands

Auth & session

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

Discovery

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

Balances & positions

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

Market data

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

Trade (cash ⇄ asset)

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

Borrow & collateral

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

Account (read-only + settings)

perfolio-dev kyc status                          KYC verification state
perfolio-dev fiat quote --amount 500 --currency AED   Cash-out quote (quote only)
perfolio-dev beneficiaries                       Payout bank accounts
perfolio-dev settings set [--currency AED] [--gold-unit g|oz] [--country AE] [--display usd|local]
perfolio-dev 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-dev balance / perfolio-dev 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-dev 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-dev login writes a bearer token to ~/.perfolio/credentials-dev with 0600 perms (a SEPARATE file from the production @perfolio/cli's ~/.perfolio/credentials, so the two never collide). The CLI reads it on every call. perfolio-dev 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.