npm package: @privacy-com/privacy-cli
Description: CLI for the Privacy.com API - manage virtual cards and transactions from the terminal
Latest version: 0.2.3

# @privacy-com/privacy-cli

[![npm](https://img.shields.io/npm/v/@privacy-com/privacy-cli)](https://www.npmjs.com/package/@privacy-com/privacy-cli)

Terminal CLI for the Privacy.com API. Manage virtual cards and transactions from the command line, with an interactive REPL mode.

## Prerequisites

- [Privacy.com Account](https://www.privacy.com)
- [Privacy.com API key](https://app.privacy.com/account#api-key)

## Getting Started

```bash
npm install -g @privacy-com/privacy-cli
privacy
```

On first run, the CLI will prompt for your API key and save it to `~/.privacy/config` for future use.

## Commands

### Cards

```bash
privacy cards list [--page <n>] [--page-size <n>]       # List all cards
privacy cards create --type <type> [options]             # Create a card
privacy cards get <token>                                # Get card details
privacy cards update <token> [options]                   # Update card settings
privacy cards pause <token>                              # Pause a card
privacy cards unpause <token>                            # Unpause a card
privacy cards close <token>                              # Close a card (permanent)
privacy cards pan <token>                                # Get full PAN, CVV, expiry
```

**Card types:** `SINGLE_USE` (closes after first use), `MERCHANT_LOCKED` (locks to first merchant)

**Note:** CATEGORY_LOCKED cards appear in list/get output but cannot be created via CLI. To create a Category Locked card, use the Privacy Dashboard at app.privacy.com.

**Create options:** `--memo <text>`, `--spend-limit <dollars>`, `--spend-limit-duration <TRANSACTION|MONTHLY|ANNUALLY|FOREVER>`

**Update options:** `--memo <text>`, `--spend-limit <dollars>`, `--spend-limit-duration <duration>`, `--state <OPEN|PAUSED>`, `--pin <pin>`

### Transactions

```bash
privacy transactions list [options]    # List transactions
```

**Options:** `--begin <YYYY-MM-DD>`, `--end <YYYY-MM-DD>`, `--card-token <token>`, `--result <APPROVED|DECLINED>`, `--page <n>`, `--page-size <n>`

### Interactive REPL

```bash
privacy                    # start REPL (default when no command given)
privacy interactive        # explicit REPL mode
```

In the REPL, type commands without the `privacy` prefix:

```
privacy> cards list
privacy> cards create --type SINGLE_USE --memo "Coffee" --spend-limit 10
privacy> transactions list --begin 2025-01-01
privacy> help
privacy> exit
```

The REPL includes fuzzy command matching — if you mistype a command, it suggests the closest match.

## Output Modes

| Mode | When | Description |
|------|------|-------------|
| **Table** | TTY terminal (default) | Aligned columns, right-aligned monetary values, pagination footer |
| **JSON** | Non-TTY / `--json` flag | Compact JSON, monetary values formatted as `$X.XX` |
| **Wide** | `--wide` flag | Table mode with all fields shown |

## Authentication

The CLI resolves your API key in this order:

1. `PRIVACY_API_KEY` environment variable
2. `~/.privacy/config` file (JSON with `api_key` field)
3. Interactive prompt (saves to `~/.privacy/config` with `0600` permissions)

## Global Options

| Option | Description |
|--------|-------------|
| `--json` | Force JSON output |
| `--wide` | Show all fields in table mode |
| `--version` | Show CLI version |
| `--help` | Show help text |