Metadata-Version: 2.4
Name: pocketsmith-cli
Version: 1.1.0
Summary: CLI tool for accessing PocketSmith financial data via the API
Project-URL: Homepage, https://github.com/lextoumbourou/pocketsmith-skill
Project-URL: Repository, https://github.com/lextoumbourou/pocketsmith-skill
Project-URL: Issues, https://github.com/lextoumbourou/pocketsmith-skill/issues
Author-email: Lex Toumbourou <lextoumbourou@gmail.com>
License-Expression: MIT
Keywords: budgeting,cli,finance,pocketsmith,transactions
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Office/Business :: Financial :: Accounting
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27.0
Provides-Extra: dev
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest-httpx>=0.30.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# PocketSmith Skill

<p align="center">
  <img src="pocketsmith.svg" alt="PocketSmith Logo" width="200">
</p>

[![PyPI version](https://badge.fury.io/py/pocketsmith-cli.svg)](https://pypi.org/project/pocketsmith-cli/)
[![Tests](https://github.com/lextoumbourou/pocketsmith-skill/actions/workflows/test.yml/badge.svg)](https://github.com/lextoumbourou/pocketsmith-skill/actions/workflows/test.yml)
[![codecov](https://codecov.io/gh/lextoumbourou/pocketsmith-skill/branch/main/graph/badge.svg)](https://codecov.io/gh/lextoumbourou/pocketsmith-skill)

> Manage [PocketSmith](https://www.pocketsmith.com) 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](https://pipx.pypa.io/) (recommended) or [uv](https://docs.astral.sh/uv/):

```bash
# 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:

```bash
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):

```bash
# 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):

```bash
# 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):

```bash
# 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):

```bash
# 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

```bash
# 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](https://my.pocketsmith.com/)
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`):

```json
{
  "env": {
    "POCKETSMITH_DEVELOPER_KEY": "your_developer_key"
  }
}
```

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

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

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

```bash
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`):

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

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

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

**For shell**:

```bash
export POCKETSMITH_ALLOW_WRITES=true
```

### 4. Verify Authentication

```bash
pocketsmith auth status
```

## Usage

### CLI Commands

```bash
# 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](./IMPLEMENTATION_NOTES.md) for implementation details and endpoint coverage.

## Output

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

## Development

```bash
# 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
