Lipafy CLI (npx lipafy)

The Lipafy CLI is a terminal toolkit and cURL wrapper designed for developers, DevOps scripts, and automated agent pipelines. It allows you to check balances, settle PayBills, execute instant @tag transfers, and run authenticated requests directly from your terminal.

⚡ Quick Start (Zero-Install)

You can run the Lipafy CLI immediately without global installation:

npx lipafy whoami

Global Installation (Optional)

npm install -g lipafy

🔑 Authentication

npx lipafy login

This prompts for your API key (lip_live_... or lip_test_...) and securely stores your token in ~/.lipafy/credentials.json.

npx lipafy login --token lip_live_your_api_key_here

3. CI/CD & Environment Variables

For non-interactive environments (GitHub Actions, Docker containers, cron scripts), export environment variables:

export LIPAFY_TOKEN="lip_live_your_api_key_here"
export LIPAFY_API_BASE="https://api.lipafy.xyz"

🛠️ CLI Command Reference

Account & Balance

Command	Description
`lipafy whoami`	Inspect active workspace identity, account handle (`@tag`), and verification status.
`lipafy balance`	Check available wallet balance, active escrow holds, and currency.
`lipafy logout`	Clear locally stored session credentials.

Payments & Money Movement

1. Instant @tag Transfer (Zero-Fee)

Send money instantly to any verified Lipafy user or organization:

npx lipafy transfer --to "@alice" --amount 1500 --note "Dinner split"

2. Pay a Utility PayBill

Settle utilities, fibre internet, or government bills:

npx lipafy pay --paybill 150501 --account "0722123456" --amount 3000 --purpose "Monthly Safaricom Home Fibre"

3. Pay a Buy Goods Till

Disburse payment to a merchant till:

npx lipafy pay --till 565444 --amount 850 --purpose "Restaurant lunch"

4. Disburse to M-Pesa Phone (B2C)

Pay contractors, riders, or employee reimbursements:

npx lipafy disburse --phone "254712345678" --amount 2500 --purpose "Courier delivery fee"

💳 Wallet Top-Up (M-Pesa STK Push)

Trigger an on-device M-Pesa PIN prompt to deposit funds into your workspace wallet:

npx lipafy topup --amount 5000 --phone "254712345678"

Your phone will immediately buzz with the Safaricom STK prompt:

“Do you want to pay KES 5,000 to Lipafy? Enter M-Pesa PIN:“

🛡️ Approvals & Intent Governance

Command	Description
`lipafy intents list`	List recent payment intents and status (`SUCCEEDED`, `PROCESSING`, `PENDING_APPROVAL`).
`lipafy approvals list`	List payment intents awaiting dual-custody human sign-off.
`lipafy approvals sign <id>`	Cryptographically sign and release an intent held in the approval queue.

🌐 Authenticated cURL Wrapper (`lipafy curl`)

The lipafy curl command acts as a drop-in proxy for curl. It automatically injects your workspace Bearer token when targeting Lipafy API endpoints without exposing tokens to untrusted hosts:

lipafy curl https://api.lipafy.xyz/v1/payment-intents \
  -H "Content-Type: application/json" \
  -d '{
    "payment_type": "PAYBILL_PAYMENT",
    "paybill": "150501",
    "account_reference": "0722123456",
    "amount_minor": "300000",
    "currency": "KES",
    "purpose": "Home Fibre"
  }'

Host Injection Safety Rules

https://api.lipafy.xyz/* ➔ Injects Bearer Token ✅
https://api.github.com/* ➔ Skips Token (Protected) ❌
https://untrusted-domain.com/* ➔ Skips Token (Protected) ❌