Privacy CLI

📘

You must be subscribed to a paid Privacy Plan in order to access the Privacy API and CLI. You can upgrade your account at app.privacy.com/subscriptions .

Global flags

These flags work with any command.

Install the CLI

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

Verify the installation:

privacy --version

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

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)

Using the CLI

Create Card

privacy cards create --type <type> [options]

Card types:

# Create a single-use card with a $10 limit
privacy cards create --type SINGLE_USE --memo "Trial signup" --spend-limit 10 --spend-limit-duration TRANSACTION

List Cards

Returns a paginated list of your virtual cards.

privacy cards list [options]

Default fields: token, last_four, type, state, memo, spend_limit

Use --wide to include spend_limit_duration, exp_month, exp_year, and created.

Examples

# List the first page of cards
privacy cards list

# Fetch page 3 with 50 results per page
privacy cards list --page 3 --page-size 50

# Output as JSON and filter with jq
privacy cards list --json | jq '[.[] | select(.state == "OPEN")]'

Get Card Details

Fetches details for a specific card by its token.

privacy cards get <token>

Update Card Details

Updates the card name, spend limit, or card state on an existing card. Only the fields you pass will be changed.

privacy cards update <token> [options]

Examples

# Update the memo and lower the spend limit
privacy cards update abc*******xyz --memo "Updated Card Name" --spend-limit 25

# Pause a card
privacy cards update abc*******xyz --state PAUSED

Pause or Unpause a Card

Pauses a card, preventing it from being charged. The card can be unpaused at any time.

privacy cards pause <token>

privacy cards unpause <token>

Close a Card

Permanently closes a card. This action cannot be undone. A closed card cannot be reopened or charged.

privacy cards close <token>

Get a Card's Full PAN

Retrieves the sensitive card details needed to make a purchase: the full card number (PAN), CVV, and expiry date.

privacy cards pan <token>

Security note: Treat PAN data carefully. Avoid logging or storing the output of this command.

Transactions

Review transaction history across your cards.

Transactions List

Returns a paginated list of transactions across all cards, with optional filters for date range, card, and result.

privacy transactions list [options]

Default fields: token, card_token, amount, result, merchant, created

Examples

# List recent transactions
privacy transactions list

# Filter by date range
privacy transactions list --begin 2025-01-01 --end 2025-03-31

# Show only declined transactions for a specific card
privacy transactions list --card-token abc*******xyz --result DECLINED

# Export a full month as JSON
privacy transactions list --begin 2025-03-01 --end 2025-03-31 --page-size 1000 --json > march.json

List transactions for a specific card

privacy transactions list --card-token <token>

Interactive Mode

Launches an interactive REPL (read-eval-print loop) for running multiple commands in a single session without re-authenticating or repeating the privacy prefix. Running privacy with no arguments also opens the REPL.

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

Inside the REPL, enter 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

Built-in REPL commands:

The REPL also provides fuzzy suggestions if you mistype a command name.

Note: Shell operators such as |, >, and && are not supported inside the REPL. For pipelines and redirects, use the CLI in non-interactive mode.

Output Modes