lnget: like wget but for L402 on the web

Install and use lnget, a Lightning-native HTTP client with automatic L402 payment support. Use when downloading files behind Lightning paywalls, managing L402 tokens, checking Lightning backend status, or making HTTP requests that may require micropayments.

# lnget - Lightning-Native HTTP Client

lnget is a wget/curl-like CLI that natively handles L402 (Lightning HTTP 402)
authentication. When a server responds with HTTP 402 and an L402 challenge,
lnget automatically pays the Lightning invoice and retries with the paid token.

**Source:** `github.com/lightninglabs/lnget`

## Quick Start

```bash
# 1. Install lnget
skills/lnget/scripts/install.sh

# 2. Initialize config (auto-detects local lnd)
lnget config init

# 3. Fetch an L402-protected resource
lnget --max-cost 1000 https://api.example.com/paid-data
```

## Installation

```bash
skills/lnget/scripts/install.sh
```

This will:
- Verify Go is installed
- Run `go install github.com/lightninglabs/lnget/cmd/lnget@latest`
- Verify `lnget` is on `$PATH`

To install manually:

```bash
go install github.com/lightninglabs/lnget/cmd/lnget@latest
```

Or build from source:

```bash
git clone https://github.com/lightninglabs/lnget.git
cd lnget
make install
```

## Basic Usage

### Downloads

```bash
# Fetch URL (output to stdout)
lnget https://api.example.com/data.json

# Save to file
lnget -o data.json https://api.example.com/data.json

# Quiet mode for piping
lnget -q https://api.example.com/data.json | jq .

# Resume partial download
lnget -c -o largefile.zip https://api.example.com/largefile.zip

# Custom HTTP method with data
lnget -X POST -d '{"query":"test"}' https://api.example.com/search

# Custom headers
lnget -H "Accept: text/plain" https://api.example.com/data
```

### Payment Control

```bash
# Set maximum auto-pay amount (satoshis)
lnget --max-cost 5000 https://api.example.com/expensive.json

# Set maximum routing fee
lnget --max-fee 50 https://api.example.com/data.json

# Preview without paying (shows 402 challenge details)
lnget --no-pay https://api.example.com/data.json

# Custom payment timeout
lnget --payment-timeout 120s https://api.example.com/data.json
```

### Output Modes

```bash
# JSON output (default, best for programmatic use)
lnget --json https://api.example.com/data.json

# Human-readable output
lnget --human https://api.example.com/data.json

# Verbose mode (shows L402 flow details)
lnget -v https://api.example.com/data.json

# Disable progress bar
lnget --no-progress -o file.zip https://api.example.com/file.zip
```

## Subcommands

### Token Management (`lnget tokens`)

Tokens are cached per-domain at `~/.lnget/tokens/<domain>/token.json` and
reused automatically on subsequent requests.

```bash
# List all cached tokens
lnget tokens list

# Show token for a specific domain
lnget tokens show api.example.com

# Remove token for a domain (forces re-authentication)
lnget tokens remove api.example.com

# Clear all tokens
lnget tokens clear --force
```

### Configuration (`lnget config`)

```bash
# Initialize config file at ~/.lnget/config.yaml
lnget config init

# Show current configuration
lnget config show

# Show config file path
lnget config path
```

### Lightning Backend (`lnget ln`)

```bash
# Check backend connection status
lnget ln status

# Show detailed node info
lnget ln info
```

#### LNC (Lightning Node Connect)

```bash
# Pair with a node via LNC pairing phrase
lnget ln lnc pair "your-pairing-phrase"

# Ephemeral pairing (no session persistence)
lnget ln lnc pair "phrase" --ephemeral

# List saved LNC sessions
lnget ln lnc sessions

# Revoke a session
lnget ln lnc revoke <session-id>
```

#### Neutrino (Embedded Wallet)

```bash
# Initialize embedded neutrino wallet
lnget ln neutrino init

# Get address to fund wallet
lnget ln neutrino fund

# Check wallet balance
lnget ln neutrino balance

# Show sync status
lnget ln neutrino status
```

## Configuration File

Config lives at `~/.lnget/config.yaml`. Run `lnget config init` to create it.

**Note:** `lnget config init` may generate incorrect YAML key names (e.g.,
`tlscertpath` and `macaroonpath` instead of `tls_cert` and `macaroon`) due to
missing yaml struct tags in the lnget source. Use the example below as the
reference config format. If your config was generated by `lnget config init`,
verify the `ln.lnd` keys match the format shown here.

```yaml
l402:
  max_cost_sats: 1000       # Max invoice to auto-pay
  max_fee_sats: 10           # Max routing fee
  payment_timeout: 60s       # Payment timeout
  auto_pay: true             # Enable auto-payment

http:
  timeout: 30s
  max_redirects: 10
  user_agent: "lnget/0.1.0"
  allow_insecure: false

ln:
  mode: lnd                  # Options: lnd, lnc, neutrino
  lnd:
    host: localhost:10009
    tls_cert: ~/.lnd/tls.cert
    macaroon: ~/.lnd/data/chain/bitcoin/mainnet/admin.macaroon
    network: mainnet

output:
  format: json
  progress: true
  verbose: false

tokens:
  dir: ~/.lnget/tokens
```

Environment variables override config with `LNGET_` prefix:

```bash
export LNGET_L402_MAX_COST_SATS=5000
export LNGET_LN_MODE=lnc
export LNGET_LN_LND_HOST=localhost:10009
```

## Exit Codes

| Code | Meaning |
|------|---------|
| 0 | Success |
| 1 | General error |
| 2 | Payment exceeds max cost |
| 3 | Payment failed |
| 4 | Network/connection error |

## L402 Flow

When lnget encounters a 402 response:

1. Parses `WWW-Authenticate: L402 macaroon="...", invoice="..."` header
2. Decodes the macaroon and BOLT11 invoice
3. Checks invoice amount against `--max-cost`
4. Stores a pending token (crash recovery)
5. Pays the invoice via the configured Lightning backend
6. Stores the paid token with preimage at `~/.lnget/tokens/<domain>/`
7. Retries the request with `Authorization: L402 <macaroon>:<preimage>`

Subsequent requests to the same domain reuse the cached token without payment.

## Agent Integration Patterns

### Budget-Aware Fetching

```bash
# Check cost before committing
result=$(lnget --no-pay --json https://api.example.com/data.json)
cost=$(echo "$result" | jq -r '.invoice_amount_sat // 0')

if [ "$cost" -le "$BUDGET" ]; then
    lnget --max-cost "$BUDGET" -q https://api.example.com/data.json
fi
```

### Parsing JSON Output

```bash
# Extract just the response body
lnget --json -q https://api.example.com/data.json | jq '.body'

# Check if payment was required
lnget --json https://api.example.com/data.json | jq '.l402_paid'
```

### Testing with Insecure Connections

```bash
# For local development with aperture (no TLS)
lnget -k https://localhost:8081/api/data
```

## File Locations

| Path | Purpose |
|------|---------|
| `~/.lnget/config.yaml` | Configuration file |
| `~/.lnget/tokens/<domain>/` | Per-domain token storage |
| `~/.lnget/lnc/sessions/` | LNC session persistence |
| `~/.lnget/neutrino/` | Embedded wallet data |