Organizze API (CLI scripts)#

Use the organizze-skill repository to read and write Organizze personal finance data through the official REST API. JSON is printed to stdout; errors go to stderr and the process exits non-zero on failure.

Before running anything#

Check whether the required credentials are available:

bash

[[ -n "${ORGANIZZE_TOKEN:-}" && -n "${ORGANIZZE_EMAIL:-}" && -n "${ORGANIZZE_USER_AGENT:-}" ]] && echo "READY" || echo "MISSING"

• If the output is MISSING: stop and guide the user through setup below. Do NOT proceed until all variables are set.
• If the output is READY: proceed.

Setup guidance (show this when MISSING)#

Tell the user they have two options:

Option 1 (recommended) — OpenClaw UI: Open the OpenClaw UI, go to Skills → organizze, enter the API token in the API key field, and click Save key. Then set ORGANIZZE_EMAIL and ORGANIZZE_USER_AGENT as environment variables in the skill's env section.

Option 2 — Edit ~/.openclaw/openclaw.json directly (for CLI users):

json

{
  "skills": {
    "entries": {
      "organizze": {
        "enabled": true,
        "apiKey": "<your-organizze-token>",
        "env": {
          "ORGANIZZE_EMAIL": "your@email.com",
          "ORGANIZZE_USER_AGENT": "my-organizze-skill"
        }
      }
    }
  }
}

The gateway picks up the change automatically — no restart needed.

The user can get their API token from the Organizze web app under Configurações → Integrações → Token de API.

Working directory#

Before every node command, set the shell working directory to the repository root — the directory that contains package.json.

Prerequisites#

• Node.js 18 or newer

• From the repository root: npm install

• A .env file (copy from .env.example) with:

  • ORGANIZZE_EMAIL
  • ORGANIZZE_TOKEN
  • ORGANIZZE_USER_AGENT (required by the API; any short string identifying your integration)

Do not print or log credential values. Mask PII when summarizing API output for the user.

How to run#

bash

node src/routes/<resource>.js <action> [args]

<resource> is one of: accounts, categories, transactions, credit-cards, transfers.

Run a script with no arguments to see its full usage on stderr.

Output: pretty-printed JSON on stdout. Errors: message on stderr, exit 1.

---

Conventions#

• amount_cents: integer cents. R$ 50.00 = 5000. Expenses are negative.
• Dates: YYYY-MM-DD.
• JSON arguments: pass as a single quoted shell argument.
• transactions list --group-by-tag: local grouping after the API response (not a native API feature). Returns [{ tag, total_cents, transactions }]. Transactions with multiple tags appear in each group; untagged ones go into "untagged".
• transfers list: returns two entries per transfer (debit and credit sides), not one merged object.

For field names and payloads not listed here, see: https://github.com/organizze/api-doc

---

accounts#

ActionArgumentslist(none)get``<id>``create``<json>``update``<id> <json>``delete``<id>bash

node src/routes/accounts.js list
node src/routes/accounts.js get 12345

---

categories#

ActionArgumentslist(none)get``<id>``create``<json>``update``<id> <json>``delete``<id> [json]

delete accepts optional JSON with replacement_id to migrate existing references before removal.

bash

node src/routes/categories.js list
node src/routes/categories.js delete 42 '{"replacement_id":18}'

---

transactions#

ActionArgumentslistOptional flags: --start-date=YYYY-MM-DD, --end-date=YYYY-MM-DD, --account-id=<id>, --group-by-tag``get``<id>``create``<json>``update``<id> <json>``delete``<id> [json]

delete accepts optional JSON for recurring/installment behavior: '{"update_future":true}' or '{"update_all":true}'.

bash

node src/routes/transactions.js list --start-date=2025-04-01 --end-date=2025-04-30
node src/routes/transactions.js list --account-id=1 --group-by-tag
node src/routes/transactions.js delete 888 '{"update_future":true}'

---

credit-cards#

ActionArgumentslist(none)get``<id>``create``<json>``update``<id> <json>``delete``<id>``list-invoices``<credit_card_id> optional --start-date=... --end-date=...``get-invoice``<credit_card_id> <invoice_id>``get-payments``<credit_card_id> <invoice_id>bash

node src/routes/credit-cards.js list
node src/routes/credit-cards.js list-invoices 3 --start-date=2025-01-01 --end-date=2025-12-31
node src/routes/credit-cards.js get-payments 3 1001

---

transfers#

ActionArgumentslistOptional --start-date=YYYY-MM-DD --end-date=YYYY-MM-DD``get``<id>``create``<json>``update``<id> <json>``delete``<id>

Typical create fields: credit_account_id, debit_account_id, amount_cents, date, paid. Confirm exact shape via the API doc or by inspecting existing transfers.

bash

node src/routes/transfers.js list --start-date=2025-04-01 --end-date=2025-04-30
node src/routes/transfers.js get 55

---

End-to-end workflows#

Balances#

bash

node src/routes/accounts.js list

Transactions for a period, filtered by account#

bash

# 1. get account id
node src/routes/accounts.js list

# 2. list transactions
node src/routes/transactions.js list --start-date=2025-04-01 --end-date=2025-04-30 --account-id=1

Create an expense#

bash

node src/routes/transactions.js create \
  '{"description":"Coffee","amount_cents":-1500,"date":"2025-04-03","category_id":10,"account_id":1}'

Use negative amount_cents. Get category_id and account_id from prior list calls. Adjust fields to match the API.

Spending by tag#

bash

node src/routes/transactions.js list --start-date=2025-04-01 --end-date=2025-04-30 --group-by-tag

Each group in the result has tag and total_cents.