pocketsmith-cli 1.1.0

CLI tool for accessing PocketSmith financial data via the API

PocketSmith Skill

Manage PocketSmith transactions, categories, and financial data via the API.

Repository: https://github.com/lextoumbourou/pocketsmith-skill

Features

• Transactions - List, view, create, update, and delete transactions
• Categories - Full CRUD for spending categories
• Budgets - View budget lists, summaries, and trend analysis
• Labels - Create and manage transaction labels
• Attachments - Manage receipts and documents attached to transactions
• User Info - View authenticated user details
• Write Protection - Safe by default, write operations require explicit opt-in

Installation

CLI (Recommended)

Install as a standalone command-line tool using pipx (recommended) or uv:

# Using pipx (recommended - isolated environment)
pipx install pocketsmith-cli

# Or using uv
uv tool install pocketsmith-cli

# Or using pip
pip install pocketsmith-cli

After installation, the pocketsmith command is available globally:

pocketsmith --help
pocketsmith me
pocketsmith transactions list-by-user 123456

Claude Code

Claude Code can automatically discover and use this skill. Install it as a personal skill (available across all projects) or a project skill (specific to one project).

Personal skill (recommended):

# Clone into your personal skills directory
mkdir -p ~/.claude/skills
cd ~/.claude/skills
git clone https://github.com/lextoumbourou/pocketsmith-skill.git pocketsmith

# Install dependencies
cd pocketsmith
uv sync

Project skill (for a specific project):

# Clone into your project's skills directory
mkdir -p .claude/skills
cd .claude/skills
git clone https://github.com/lextoumbourou/pocketsmith-skill.git pocketsmith

# Install dependencies
cd pocketsmith
uv sync

Once installed, Claude Code will automatically load the skill when relevant, or you can invoke it directly with /pocketsmith.

OpenClaw

Install as a managed skill (available to all agents) or workspace skill (specific to one workspace).

Managed skill (recommended):

# Clone into your managed skills directory
mkdir -p ~/.openclaw/skills
cd ~/.openclaw/skills
git clone https://github.com/lextoumbourou/pocketsmith-skill.git pocketsmith

# Install dependencies
cd pocketsmith
uv sync

Workspace skill (for a specific workspace):

# Clone into your workspace's skills directory
mkdir -p ./skills
cd ./skills
git clone https://github.com/lextoumbourou/pocketsmith-skill.git pocketsmith

# Install dependencies
cd pocketsmith
uv sync

Verify Installation

# If installed via pipx/pip
pocketsmith --help

# If installed as a skill (Claude Code/OpenClaw)
cd ~/.claude/skills/pocketsmith  # or respective directory for your setup
uv run pocketsmith --help

Setup

1. Get PocketSmith Developer Key

1. Log in to PocketSmith
2. Go to Settings > Security > Manage Developer Keys
3. Create a new developer key and copy it

2. Set Environment Variables

For Claude Code (~/.claude/settings.json):

{
  "env": {
    "POCKETSMITH_DEVELOPER_KEY": "your_developer_key"
  }
}

For OpenClaw (~/.openclaw/openclaw.json):

{
  "skills": {
    "entries": {
      "pocketsmith": {
        "enabled": true,
        "env": {
          "POCKETSMITH_DEVELOPER_KEY": "your_developer_key"
        }
      }
    }
  }
}

For shell usage (~/.bashrc or ~/.zshrc):

export POCKETSMITH_DEVELOPER_KEY="your_developer_key"

3. Enable Write Operations (Optional)

Write operations (create, update, delete) are disabled by default for safety. To enable:

For Claude Code (~/.claude/settings.json):

{
  "env": {
    "POCKETSMITH_DEVELOPER_KEY": "your_developer_key",
    "POCKETSMITH_ALLOW_WRITES": "true"
  }
}

For OpenClaw (~/.openclaw/openclaw.json):

{
  "skills": {
    "entries": {
      "pocketsmith": {
        "enabled": true,
        "env": {
          "POCKETSMITH_DEVELOPER_KEY": "your_developer_key",
          "POCKETSMITH_ALLOW_WRITES": "true"
        }
      }
    }
  }
}

For shell:

export POCKETSMITH_ALLOW_WRITES=true

4. Verify Authentication

pocketsmith auth status

Usage

CLI Commands

# Get current user
pocketsmith me

# List transactions for a user
pocketsmith transactions list-by-user 123456

# Search transactions
pocketsmith transactions list-by-user 123456 --search "coffee" --start-date 2024-01-01

# Get a specific transaction
pocketsmith transactions get 987654

# Update a transaction (requires POCKETSMITH_ALLOW_WRITES=true)
pocketsmith transactions update 987654 --category-id 28637787

# Create a transaction
pocketsmith transactions create 456789 --payee "Coffee Shop" --amount -5.50 --date 2024-01-15

# List categories
pocketsmith categories list 123456

# Create a category
pocketsmith categories create 123456 --title "Subscriptions" --parent-id 28601039

# List budget for a user
pocketsmith budget list 123456

# Get budget summary for a period
pocketsmith budget summary 123456 --period months --interval 1 --start-date 2024-01-01 --end-date 2024-12-31

# Get trend analysis for specific categories
pocketsmith budget trend 123456 --period months --interval 1 --start-date 2024-01-01 --end-date 2024-06-30 --categories 28600217,28637787 --scenarios 1,2

# List attachments for a transaction
pocketsmith attachments list-by-transaction 987654

# Get a specific attachment
pocketsmith attachments get 123456

# Get help
pocketsmith --help
pocketsmith transactions --help
pocketsmith categories --help
pocketsmith budget --help
pocketsmith attachments --help

In Claude Code / OpenClaw

Once the skill is installed, Claude will automatically use it when relevant. Just ask naturally:

• "Show me my PocketSmith transactions from last month"
• "Find all transactions containing 'Netflix'"
• "Categorize transaction 123456 as Subscriptions"
• "Create a new category called 'Side Projects' under Entertainment"
• "List all my spending categories"

You can also invoke the skill directly with /pocketsmith to see available commands.

API Reference

See IMPLEMENTATION_NOTES.md for implementation details and endpoint coverage.

Output

All commands output JSON to stdout. Errors are written to stderr.

Development

# Install dev dependencies
uv sync --extra dev

# Run tests
uv run pytest tests/ -v

# Run directly
uv run pocketsmith me

Troubleshooting

Error	Solution
POCKETSMITH_DEVELOPER_KEY environment variable is required	Set POCKETSMITH_DEVELOPER_KEY
Write operations are disabled	Set POCKETSMITH_ALLOW_WRITES=true
401 Unauthorized	Check your developer key is valid
404 Not Found	Check the resource ID exists

License

MIT