snaplii-cli 0.5.1

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

AI Passport by Snaplii

Safe, limited-authorization payments for AI agents.

AI Passport lets AI agents browse, purchase, and manage gift cards through Snaplii with spending limits and scoped permissions. Agents pay with Snaplii Cash prepaid balance, so exposure is capped and controllable.

---

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/SnapPayInc/ai-passport.git
cd ai-passport

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 PowerShell

py -m pip install --user pipx
py -m pipx ensurepath

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:

agent-id is any name you choose to identify this agent session (e.g. "my-laptop", "claude-desktop"). It is not provided by Snaplii — you make it up.

snaplii init --api-key "snp_sk_live_..."

5. Use the CLI

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

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

---

Components

ai-passport/
├── snaplii-cli/     # Python CLI — pip-installable
├── mcp-server/      # MCP server for Claude Desktop
└── skills/          # Claude Code skill definition

---

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 purchase --item-id ID --price P	Purchase a gift card
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 --api-key "snp_sk_live_..."

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/ai-passport/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.