> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.lipafy.xyz/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.lipafy.xyz/_mcp/server.

# Lipafy CLI (`npx lipafy`)

> Manage wallets, trigger M-Pesa payments, disburse funds, and proxy authenticated API calls from your terminal.

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:

**`npm`**

```bash npm
npx lipafy whoami
```

**`pnpm`**

```bash pnpm
pnpm dlx lipafy whoami
```

**`yarn`**

```bash yarn
yarn dlx lipafy whoami
```

### Global Installation (Optional)

```bash
npm install -g lipafy
```

---

## 🔑 Authentication

### 1. Interactive Login

```bash
npx lipafy login
```

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

### 2. Login via Flag

```bash
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:

```bash
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:

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

#### 2. Pay a Utility PayBill

Settle utilities, fibre internet, or government bills:

```bash
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:

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

#### 4. Disburse to M-Pesa Phone (B2C)

Pay contractors, riders, or employee reimbursements:

```bash
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:

```bash
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:

```bash
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)** ❌