npm package: @mellow-finance/cli
Description: A CLI built with Ink and React
Latest version: 0.0.2

# Mellow CLI

A dual-mode command-line interface for interacting with Mellow Core Vault deposit and redeem queues. Supports an interactive terminal UI (TUI) for exploratory use and a non-interactive mode for scripting and automation.

## Quick Start

```bash
# Install dependencies
npm install

# Build
npm run build

# Set your private key
export MELLOW_CLI_USER_PK=0x<your-64-char-hex-private-key>

# Launch TUI (interactive mode)
mellow-cli --vault earnETH

# Run a single command (non-interactive)
mellow-cli overview --vault earnETH --non-interactive
```

## Installation

Requires **Node.js >= 20**.

```bash
# Clone the repository
git clone <repo-url>
cd mellow-cli

# Install dependencies
npm install

# Build the TypeScript source
npm run build

# The built binary is available at ./dist/cli.js
# You can also run it via the package name:
npx mellow --vault earnETH
```

For development with live reload:

```bash
npm run dev
```

## Environment Variables

| Variable | Required | Description |
|---|---|---|
| `MELLOW_CLI_USER_PK` | Yes | Your Ethereum private key in hex format |

The private key must be a `0x`-prefixed, 64-character hexadecimal string (32 bytes). The CLI derives your wallet address from this key automatically.

**Setting the variable:**

```bash
# Linux / macOS
export MELLOW_CLI_USER_PK=0xabc123...def456

# Windows (PowerShell)
$env:MELLOW_CLI_USER_PK = "0xabc123...def456"

# Windows (cmd)
set MELLOW_CLI_USER_PK=0xabc123...def456
```

> **Security note:** Avoid committing your private key to version control or shell history. Consider using a `.env` file (excluded from git) or a secrets manager.

## Commands

The CLI provides 7 commands covering the full LP lifecycle:

| Command | Description |
|---|---|
| `overview` | Display vault APY, TVL, and allocation breakdown |
| `my-position` | Display your vault position and pending requests |
| `deposit` | Deposit assets into a vault queue |
| `deposit cancel` | Cancel a pending deposit request |
| `deposit claim` | Claim processed deposit shares |
| `redeem` | Redeem vault shares into a withdrawal queue |
| `redeem claim` | Claim all claimable redemption requests |

## Arguments

| Flag | Short | Description |
|---|---|---|
| `--vault` | `-v` | Vault identifier (required for all commands) |
| `--queue` | `-q` | Queue identifier (required for deposit and redeem commands) |
| `--amount` | `-a` | Amount to deposit or redeem (human-readable, e.g. `"1.5"`) |
| `--non-interactive` | | Run in non-interactive mode with tagged stdout output |
| `--help` | | Show help message |

### --vault

Accepts any of the following:

- **Address** -- full Ethereum address (e.g. `0x1234...abcd`)
- **Slug / ID** -- vault identifier from the API (e.g. `earnETH`)
- **Symbol** -- share token symbol (e.g. `earnETH`)

The CLI fetches all available vaults and matches against address, slug, and symbol. If no match is found, the CLI lists all available vaults and exits.

### --queue

Accepts any of the following:

- **Address** -- full queue contract address (e.g. `0xABC...DEF`)
- **Asset symbol** -- the token symbol accepted by the queue (e.g. `WETH`, `weth`)

Queue matching is **case-insensitive** for asset symbols. If multiple queues match the same symbol, the CLI asks you to specify by address instead.

## TUI Mode (Interactive)

TUI mode is the default when the CLI detects an interactive terminal. Launch it by running any command without `--non-interactive`:

```bash
# Open the command palette (entry screen)
mellow-cli --vault earnETH

# Open directly on a specific screen
mellow-cli overview --vault earnETH
mellow-cli deposit --vault earnETH
mellow-cli redeem --vault earnETH
mellow-cli my-position --vault earnETH
```

### Command Palette

When launched without a specific command, the TUI opens an entry screen with a command palette. Type to filter commands by prefix (e.g. `/d` shows `/deposit`, `/deposit cancel`, `/deposit claim`). Navigate with arrow keys and press Enter to select.

### TUI Navigation

- **Arrow keys** -- navigate table rows and command suggestions
- **Enter** -- select an item or confirm an action
- **q / Escape** -- exit the application

### TUI Screens

| Screen | Shows |
|---|---|
| Entry | Vault metadata and command palette |
| Overview | APY, TVL, allocation breakdown table |
| My Position | Share balance, USD value, all pending/claimable requests |
| Deposit | Deposit queue table with inline deposit/cancel actions |
| Redeem | Redeem queue table with inline redeem actions |

## Non-Interactive Mode

Activate non-interactive mode by passing `--non-interactive` or by piping stdout (the CLI auto-detects non-TTY environments).

Each command below shows the full argument list:

```bash
# View vault overview
mellow-cli overview --vault earnETH --non-interactive

# View your position
mellow-cli my-position --vault earnETH --non-interactive

# Deposit 1.5 WETH into a queue
mellow-cli deposit --vault earnETH --queue WETH --amount 1.5 --non-interactive

# Cancel a pending deposit
mellow-cli deposit cancel --vault earnETH --queue WETH --non-interactive

# Claim processed deposit shares
mellow-cli deposit claim --vault earnETH --queue WETH --non-interactive

# Redeem 1.5 shares into a withdrawal queue
mellow-cli redeem --vault earnETH --queue WETH --amount 1.5 --non-interactive

# Claim processed redemption assets
mellow-cli redeem claim --vault earnETH --queue WETH --non-interactive
```

### Output Tag Schema

Non-interactive output is line-oriented and machine-parseable. Each line is prefixed with a tag indicating its category:

| Tag | Stream | Description | Example |
|---|---|---|---|
| `[INFO]` | stdout | Progress or status message | `[INFO] Resolving vault earnETH...` |
| `[TX]` | stdout | Transaction hash (one per submitted tx) | `[TX] 0xabc123...` |
| `[OK]` | stdout | Success confirmation | `[OK] Deposit completed` |
| `[ERROR]` | stderr | Error with actionable detail | `[ERROR] Insufficient balance: you have 0.5 WETH but 1.0 WETH is required` |
| `[DATA]` | stdout | Key-value pair | `[DATA] apy: 4.52%` |
| `[TABLE]` | stdout | Table header (pipe-separated columns) | `[TABLE] Asset \| Address \| Pending \| Claimable` |
| `[ROW]` | stdout | Table data row (pipe-separated values) | `[ROW] WETH \| 0x000...000 \| 1.500 \| 0.000` |

**Parsing example (bash):**

```bash
# Extract only transaction hashes
mellow-cli deposit --vault earnETH --queue WETH --amount 1.0 --non-interactive \
  | grep '^\[TX\]' \
  | cut -d' ' -f2
```

## Cross-Platform Compatibility

| Platform | Minimum Version |
|---|---|
| Windows | 10+ |
| macOS | 12+ (Monterey) |
| Linux | Any modern distribution with Node.js >= 20 |

The CLI runs anywhere Node.js >= 20 is available. TUI mode requires an interactive terminal with ANSI color support. Non-interactive mode works in any environment including CI/CD pipelines, Docker containers, and headless servers.

## License

MIT