snaplii-cli 0.6.1

Browse, purchase, and manage gift cards through Snaplii — safe payments for AI agents

Agent-to-Merchant Payments by Snaplii

Payments are broken for AI agents.

Snaplii unlocks real-world commerce with a safe, tokenized payment layer — powered by 500+ merchant gift cards — and is the only one that actually saves you money (up to 10% per transaction), on top of any existing deals or promotions. New users can unlock an exclusive welcome offer: $10 off your first $30 transaction.

---

The Problem

AI agents can already:

• decide what to buy
• compare options
• navigate merchant platforms

But they still can’t safely pay. Payments require trust, compliance, and risk control — things AI agents are not designed to handle.

Giving agents access to cards is not a solution. It’s a risk.

---

The Solution

Snaplii introduces a new model: User → Agent → Snaplii → Merchant

• Users fund Snaplii
• Agents operate within a controlled boundary
• Each transaction is pre-funded, isolated, and non-reusable

No shared credentials. No persistent risk.

In addition, Snaplii embeds value directly into the payment layer —
transactions can save up to 10% and stack seamlessly with existing merchant deals and promotions.

Table of Contents

• Requirements
• Quick Start
  • 1. Get Your API Key via Snaplii App
  • 2. Get the Code
  • 3. Install the CLI
  • 4. Authenticate
  • 5. Use the CLI
• Components
• CLI Commands
• Claude Desktop Setup MCP Server
• Claude Code Skill
• Troubleshooting
• Security
• License

---

Requirements

• Python 3.10+
  CLI works on Python 3.9+, but the MCP server requires Python 3.10+.
• Git
• Snaplii Mobile App
  Required to generate your API key.

Mac users: check your Python version

python3 --version

If your Python version is below 3.10, install Python via Homebrew:

brew install python@3.12

Then use python3.12 and pip3.12 instead of python3 / pip3 in the steps below.

---

Quick Start

1. Get Your API Key via Snaplii App

Before using the CLI or configuring your AI agent, generate a secure API key from the Snaplii mobile app:

1. Download the Snaplii app for iOS or Android.
2. Register an account and bind a payment method to load your Snaplii Cash balance.
3. In the app, go to More → Payment Methods → AI Payment Management.
4. Tap + New API Key.
5. Set a name, define the permission scope, and set a hard spending limit.
   • Example scopes: Read-only or Purchase
6. Copy the API key.
   • Format: snp_sk_live_...
   • Keep it safe — it will only be shown once.

2. Get the Code

git clone https://github.com/Snaplii-Inc/agent-to-merchant-payments.git
cd agent-to-merchant-payments

3. Install the CLI

pipx is the smoothest path. It installs the CLI in its own isolated environment and puts the snaplii executable on your PATH.

macOS

brew install pipx
pipx ensurepath

Linux

python3 -m pip install --user pipx
python3 -m pipx ensurepath

Windows

Option A — Scoop (recommended):

scoop install pipx
pipx ensurepath

Option B — pip:

py -m pip install --user pipx

If you see a warning that pipx.exe is not on PATH, run the following from the displayed path:

.\pipx.exe ensurepath

Restart your terminal after running ensurepath.

Note: If you installed Python from the Microsoft Store, use python3 instead of py.

All platforms

pipx install -e ./snaplii-cli

Open a new terminal window so the updated PATH takes effect, then verify the installation:

snaplii --help

If you see command not found, see Troubleshooting.

4. Authenticate

Link your local CLI to your Snaplii account using the API key generated in Step 1:

snaplii init

The CLI will prompt for your API key via hidden input (like a password prompt). The key is used only to obtain a session token and is never stored on disk. Agent ID is auto-derived from the key.

5. Use the CLI

snaplii browse tags --prov CA                        # Browse gift card categories (CA or US)
snaplii browse brand --id CB...                      # See denominations and cashback
snaplii giftcard list                                # View owned cards
snaplii purchase --item-id CB...-CT... --price 50 --prov ON   # Buy a card

--item-id is formatted as {cardBrandId}-{cardTemplateId}. Both IDs are available from snaplii browse brand.

Note on --prov: For browse tags, use country code (CA for Canada, US for United States). For purchase, use province/state code (ON, QC, BC, NY, CA, TX, etc.).

---

Components

agent-to-merchant-payments/
├── snaplii-cli/       # Python CLI — pip-installable
├── mcp-server/        # MCP server for Claude Desktop
├── skills/            # Claude Code skill definition
├── clawhub-publish/   # ClawHub skill artifact
└── clawhub-plugin/    # ClawHub MCP bundle plugin

---

CLI Commands

Command	Purpose
snaplii init	Authenticate with your Snaplii API key
snaplii config show	Show current config and auth status
snaplii browse tags	Browse card categories and brands
snaplii browse brand --id ID	View brand details, denominations, and cashback
snaplii giftcard list	List owned gift cards
snaplii giftcard detail --card-no NO	View card redemption code and PIN
snaplii quote --item-id ID --price P	Preview price with voucher/cashback before buying
snaplii purchase --item-id ID --price P --prov PROV	Purchase a gift card (prov = province/state)
snaplii smart cashback --brand-id ID --amount A	Calculate cashback savings
snaplii smart dashboard	View card inventory summary

---

Claude Desktop Setup MCP Server

Claude Desktop cannot run CLI commands directly. It requires an MCP server to bridge the gap. The Snaplii MCP server exposes tools that let Claude browse gift cards and make purchases through natural conversation.

Step 1: Install dependencies

The MCP server requires Python 3.10+ and the mcp package. Install both the CLI and server dependencies:

pip3 install -e ./snaplii-cli
pip3 install "mcp[cli]"

If you get an externally-managed-environment error, add --break-system-packages:

pip3 install -e ./snaplii-cli --break-system-packages
pip3 install "mcp[cli]" --break-system-packages

Step 2: Authenticate one time

The MCP server reads credentials from ~/.snaplii/config.json. If you have not authenticated yet, run:

snaplii init

Enter your API key when prompted.

Step 3: Configure Claude Desktop

Edit your Claude Desktop config file:

OS	Config file location
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Windows	%APPDATA%\Claude\claude_desktop_config.json
Linux	~/.config/Claude/claude_desktop_config.json

Add the mcpServers section. Create the file if it does not exist. Use absolute paths:

{
  "mcpServers": {
    "snaplii": {
      "command": "/absolute/path/to/python",
      "args": ["/absolute/path/to/agent-to-merchant-payments/mcp-server/server.py"]
    }
  }
}

[!IMPORTANT]

• command must point to the Python interpreter where mcp is installed. Find it with which python3 or echo ~/.venvs/snaplii/bin/python.
• args must be the exact path to server.py inside your cloned repo.

Step 4: Restart Claude Desktop

Fully quit Claude Desktop, for example with Cmd+Q on macOS, then reopen it. You should now see the Snaplii tools available.

Step 5: Verify

In a new Claude Desktop conversation, ask:

What gift cards are available on Snaplii?

Claude should automatically call snaplii_browse_tags and display the categories.

---

Claude Code Skill

Claude Code expects each skill in its own directory containing a SKILL.md file:

mkdir -p ~/.claude/skills/snaplii-cli
cp skills/snaplii-cli.md ~/.claude/skills/snaplii-cli/SKILL.md

Then open:

~/.claude/skills/snaplii-cli/SKILL.md

If the file contains a line like this:

Always prepend `export PATH="$PATH:/Users/.../bin" &&` before any snaplii command.

Replace the path with the directory that holds your snaplii binary. You can find it with:

which snaplii

On Windows, use:

where.exe snaplii

If snaplii is already on your default PATH, you can delete the export PATH=... prefix entirely.

---

Troubleshooting

snaplii: command not found after install

The console script was placed somewhere not on your PATH. Run:

python3 -m pip show -f snaplii-cli

Look for an entry ending in bin/snaplii or Scripts\snaplii.exe on Windows. Then either prepend that directory to PATH in your shell configuration, or reinstall using pipx.

externally-managed-environment from pip

Your system Python forbids global package installs. Use pipx, which is recommended, or a virtual environment. As a last resort, append --break-system-packages to the pip command.

Claude Desktop logs ModuleNotFoundError: No module named 'mcp' or 'snaplii'

The Python interpreter referenced by command in claude_desktop_config.json does not have the required dependencies. Confirm with:

/absolute/path/to/python -c "import mcp, snaplii; print('ok')"

If it fails, install the missing packages into that specific interpreter:

pip install -e ./snaplii-cli
pip install "mcp[cli]"

---

Security

• Limited authorization: agents can only spend from Snaplii Cash, your prepaid balance.
• Scoped API keys: keys can be restricted to PAY_READ view-only or PAY_WRITE view + purchase.
• Spending limits: strict per-key consumption caps are set via the mobile app.
• Data protection: card redemption codes and PINs are strictly masked and never exposed without explicit user consent.

---

License

This project is licensed under the Apache License 2.0.

See the Apache License 2.0 for details.