pp-zoho-expense

What this skill does

<!-- GENERATED FILE — DO NOT EDIT.
     This file is a verbatim mirror of library/productivity/zoho-expense/SKILL.md,
     regenerated post-merge by tools/generate-skills/. Hand-edits here are
     silently overwritten on the next regen. Edit the library/ source instead.
     See the repository agent guide, section "Generated artifacts: registry.json, cli-skills/". -->

# Zoho Expense — Printing Press CLI

## Prerequisites: Install the CLI

This skill drives the `zoho-expense-pp-cli` binary. **You must verify the CLI is installed before invoking any command from this skill.** If it is missing, install it first:

1. Install via the Printing Press installer. It defaults binaries to `$HOME/.local/bin` on macOS/Linux and `%LOCALAPPDATA%\Programs\PrintingPress\bin` on Windows:
   ```bash
   npx -y @mvanhorn/printing-press-library install zoho-expense --cli-only
   ```
2. Verify: `zoho-expense-pp-cli --version`
3. Ensure the reported install directory is on `$PATH` for the agent/runtime that will invoke this skill.

If the `npx` install fails (no Node, offline, etc.), fall back to a direct Go install (requires Go 1.26.3 or newer):

```bash
go install github.com/mvanhorn/printing-press-library/library/productivity/zoho-expense/cmd/zoho-expense-pp-cli@latest
```

If `--version` reports "command not found" after install, the runtime cannot see the binary directory on `$PATH`. Do not proceed with skill commands until verification succeeds.

## When to Use This CLI

Reach for this CLI when an AI agent needs to ingest invoices from email (or any source) and post them to Zoho Expense on a recurring cadence. It's also the right tool for monthly close automation — bundling expenses into a report and submitting in one command — and for India-specific GST splitting that the Zoho web UI doesn't expose. Not the right tool for occasional one-off expense editing through the UI (Zoho's web app is fine for that).

## Unique Capabilities

These capabilities aren't available in any other tool for this API.

### Hermes-first ingestion
- **`invoice ingest`** — Batch upload a folder of invoices to Zoho Expense, SHA256-dedup against the local store, poll autoscan in parallel, and auto-tag from learned merchant memory — the headline workflow for AI agents that ingest invoices from email.

  _Agents that ingest invoices on a cadence need one command that handles dedup, autoscan, and tagging — not three._

  ```bash
  zoho-expense-pp-cli invoice ingest ~/Downloads/october-invoices --auto-tag --agent
  ```
- **`receipt upload`** — SHA256-hash incoming receipts at upload, refuse duplicates (use --force to override).

  _Idempotent receipt upload — safe to re-run on a folder agents have already processed._

  ```bash
  zoho-expense-pp-cli receipt upload ~/Downloads/uber-receipt.pdf --auto-tag
  ```
- **`expense-untagged`** — List expenses missing category_id or project_id; `--auto-fix` applies the merchant→tag memory map and PUTs back to Zoho.

  _One command turns 30 untagged scanned receipts into 30 tagged ones, using the user's own historical mapping._

  ```bash
  zoho-expense-pp-cli expense-untagged --auto-fix --agent
  ```

### Local intelligence
- **`merchant list`** — Build a local merchant→category/project/tag mapping from sync history; pre-fill tags on first sight of a new merchant.

  _Solves Zoho's 'first-time merchant is always uncategorized' limitation with zero API calls._

  ```bash
  zoho-expense-pp-cli merchant list --agent --select merchant_name,category_name,seen_count
  ```
- **`merchant map`** — Train the local merchant→category mapping for future auto-tag (one merchant at a time, or bulk from a CSV).

  _Lets the user (or agent) explicitly seed the auto-tag map without waiting for sync history to learn it._

  ```bash
  zoho-expense-pp-cli merchant map 'AWS' --category Software --project Engineering
  ```

### Monthly automation
- **`close`** — Bundle a month's unreported expenses into an expense report in one shot — flags still-processing autoscans, flags untagged items, creates the report, attaches, optionally submits.

  _The natural end of every monthly agent workflow — turn raw expenses into a submitted report without leaving the terminal._

  ```bash
  zoho-expense-pp-cli close --month 2026-10 --auto-submit --agent
  ```

### India tax workflow
- **`gst-split`** — India-specific: parse an expense's tax_id and line items, compute CGST/SGST (intra-state) or IGST (inter-state) shares, emit the breakdown or update the expense.

  _Turns a monthly export into something a CA can directly file, without the user re-doing the math by hand._

  ```bash
  zoho-expense-pp-cli gst-split exp_1234567890 --emit-csv
  ```

## Command Reference

**currencies** — Currencies and exchange rates

- `zoho-expense-pp-cli currencies create` — Add a currency to the org
- `zoho-expense-pp-cli currencies delete` — Delete a currency
- `zoho-expense-pp-cli currencies get` — Get a currency
- `zoho-expense-pp-cli currencies list` — List currencies configured in the org
- `zoho-expense-pp-cli currencies update` — Update a currency

**customers** — Customers (contacts) expenses can be billed to

- `zoho-expense-pp-cli customers create` — Create a customer
- `zoho-expense-pp-cli customers delete` — Delete a customer
- `zoho-expense-pp-cli customers get` — Get a customer
- `zoho-expense-pp-cli customers list` — List customers
- `zoho-expense-pp-cli customers update` — Update a customer

**expense_categories** — Expense categories used to classify expenses

- `zoho-expense-pp-cli expense_categories create` — Create an expense category
- `zoho-expense-pp-cli expense_categories delete` — Delete an expense category
- `zoho-expense-pp-cli expense_categories disable` — Disable a category
- `zoho-expense-pp-cli expense_categories enable` — Enable a category
- `zoho-expense-pp-cli expense_categories get` — Get an expense category
- `zoho-expense-pp-cli expense_categories list` — List expense categories
- `zoho-expense-pp-cli expense_categories update` — Update an expense category

**expense_reports** — Expense reports — bundles of expenses submitted for approval and reimbursement

- `zoho-expense-pp-cli expense_reports approval-history` — View the approval history of a report
- `zoho-expense-pp-cli expense_reports approve` — Approve an expense report
- `zoho-expense-pp-cli expense_reports create` — Create an expense report
- `zoho-expense-pp-cli expense_reports get` — Get an expense report (includes attached expenses)
- `zoho-expense-pp-cli expense_reports list` — List expense reports
- `zoho-expense-pp-cli expense_reports reimburse` — Mark an expense report as reimbursed
- `zoho-expense-pp-cli expense_reports reject` — Reject an expense report
- `zoho-expense-pp-cli expense_reports update` — Update an expense report — used to attach more expenses

**expenses** — Expenses — the primary entity for an expense management CLI

- `zoho-expense-pp-cli expenses create` — Create an expense (JSON body — for receipt upload use 'receipt upload')
- `zoho-expense-pp-cli expenses get` — Get a single expense
- `zoho-expense-pp-cli expenses list` — List expenses with rich filters (date range, status, user, category, project)
- `zoho-expense-pp-cli expenses merge` — Merge multiple expenses (used to dedupe a scanned-receipt expense with a manual one)
- `zoho-expense-pp-cli expenses update` — Update an expense — used to add category/project/tags after autoscan

**organizations** — Zoho Expense organizations you have access to

- `zoho-expense-pp-cli organizations get` — Get organization details
- `zoho-expense-pp-cli organizations list` — List organizations accessible to the authenticated user

**projects** — Projects expenses can be associated with

- `zoho-expense-pp-cli projects activate` — Mark a project active
- `zoho-expense-pp-cli projects create` — Create a project
- `zoho-expense-pp-cli projects deactivate` — Mark a project inactive
- `zoho-expense-pp-cli projects delete` — Delete a project
- `zoho-expense-