agentleFS
teottiteotti/banana-cli/skills/banana/SKILL.md

banana

Skill19 starsChanged 20 days agoMITView on GitHub

Use the BananaSplit CLI (`banana`) to set up the CLI, record and edit shared expenses, record payments, check balances, and browse groups, friends and activity. Applies when the user names BananaSplit or banana, or is working with a BananaSplit account.

  • Pipes a download into a shell

4 other projects use a version of this.

Adopted by

Most recently taken up by

  • Other versions4 projects use a version of this.

    Word for word · 0

    None found.

    Edited · 0

    None found.

    Wrote their own version · 4

    1. AgriciDaniel/banana-claude★ 1.1ksame name
    2. chriswestt/claude-skills★ 0same name
    3. redrmehta/Tmp★ 0same name
    4. ShaoXiangChien/banana-codex★ 0same name

    How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.

  • In this repository2 other files it gives its agents.

The file

We split this skill into the rules it gives an agent

8 rules. 0 are common, 1 is distinctive, and 7 are very specific to this project.

  • 0

    Common

    Most of the 4 edited versions we read keep these.

  • 1

    Distinctive

    This author's own choices. Worth a look.

  • 7

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Check whether banana is available with banana --help.

    line 14
  2. Very specific:

    Use the package install only as a fallback, when the installer above fails (no curl, no release for the platform, a blocked download) and …

    line 30
  3. Very specific:

    Verify the installation with banana --help.

    line 43
  4. Distinctive:

    Before reading or changing account data, check authentication:

    line 54
  5. Very specific:

    A request to be notified means --notify-me: When the user asks, in any language or wording, to be notified, pinged, alerted or sent a …

    line 143
  6. Very specific:

    Only the fields you pass to edit change.

    line 172
  7. Very specific:

    Prefer flags to positional JSON bodies: names are resolved through flags, while JSON bodies use API fields and ids.

    line 175
  8. Very specific:

    Leave it off when a person or an agent creates the row at the time it is asked for, including when you add one in a conversation.

    line 237

“Common” is measured: kept by at least 6 in 10 of the 4 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

BananaSplit from the command line

banana wraps the BananaSplit HTTP API. Person, group and currency flags accept names or codes, and --json gives a curated shape to parse. Expense and payment detail commands still require their row ids.

Set up the CLI when needed

Check whether banana is available with banana --help. If it is missing, install it with the standalone installer for the current platform. It needs no Bun or Node runtime, and is always the first thing to try.

macOS or Linux:

curl -fsSL https://github.com/teotti/banana-cli/releases/latest/download/install.sh | sh

Windows PowerShell:

irm https://github.com/teotti/banana-cli/releases/latest/download/install.ps1 | iex

Use the package install only as a fallback, when the installer above fails (no curl, no release for the platform, a blocked download) and Bun is already there:

bun install -g @bananasplitapp/cli

It installs the CLI as a TypeScript entry point that Bun runs, so Bun reads the current directory's tsconfig.json on every command and may print warnings about it around Banana's output. The standalone binary carries its own compiled code and stays quiet.

Verify the installation with banana --help. If the shell cannot find the standalone binary yet, use its full path: ~/.local/bin/banana on macOS/Linux, or $env:LOCALAPPDATA\BananaSplit\bin\banana.exe on Windows (unless BANANA_INSTALL_DIR was set). Follow the installer's PATH guidance for future shells. Do not reinstall repeatedly to fix PATH.

The skill is already loaded; there is no need to install it again through the CLI. The installed CLI's help is authoritative if this skill describes a newer feature.

Access

Before reading or changing account data, check authentication:

banana me --json
  • Succeeds → you are signed in; that output has the user's id and name.
  • Reports missing or expired login, or missing API permissions → ask the user to run banana login. It uses browser device approval that the user completes; there is no token environment variable to set. For other config errors, read the message: an invalid URL or credential-store failure needs a different fix.

Four rules

1. Parse --json, never the tables. The default output is aligned human text with colors and em-dashes for nulls. --json is the curated flat shape; --raw is the untouched API response. Ask for --json on every command whose output you intend to read.

2. Pass names directly for people, groups and currencies. --currency EUR, --group "Lisbon trip", --group Lisbon (a prefix works), --paid-by me, --split Ana=20. Names match exact → prefix → substring, usernames and emails work too, and an ambiguous name is reported rather than guessed. Ids still work if you happen to have one. Avoid lookup sweeps just to obtain ids. If a name is ambiguous, use the reported candidates to clarify it. Omitting --paid-by defaults to you.

3. Writes affect a real, shared account. An expense is visible to the group. Act on the user's requested changes; ask only for missing or ambiguous details. A payment records money already paid; it does not transfer money. Payments cannot be deleted from the CLI, so establish the amount, currency, date, direction and group (if any) before recording one. Something deleted elsewhere comes back with banana expenses restore or banana payments restore, which take the id and no flags; running one twice is safe, and there is no listing of deleted rows, so the id has to come from an activity feed or from the user. A clear request with those details supplies authorization; a balance inquiry alone does not.

Deleting an expense is permanent and has no undo. It leaves the balances of everyone it was split with, and they see it go. Delete only what the user asked you to delete, by an id you confirmed with banana expenses get — never one inferred from a description alone. If the user named an expense rather than an id, show them the row you matched and let them confirm before deleting it.

4. Report names and currency codes to the user. Cleaned shapes have both (paidById + paidBy, groupId + group, userId + user), and the id keys are exactly the fields the write endpoints take. When you show results to the user, show the names.

The commands

banana balanceaggregate: what you owe and are owed
banana balancesthe same, per person (alias for balance users)
banana expenses list--limit N --cursor C --sort date|amount --direction asc|desc --recurring|--no-recurring
banana expenses add--title --amount --currency --date required; --paid-by --group --description --split-type --split --notify-me --automated (--notify-me opts in to your own expense-created push notification)
banana expenses get <expense-id>one expense with payer and splits
banana expenses edit <expense-id>any subset of the add field flags except --notify-me and --automated, plus --no-group
banana expenses delete <expense-id>changes everyone's balance — confirm with the user first; undo with restore
banana expenses restore <expense-id>brings a deleted expense back with its shares
banana recurring list (or banana expenses recurring list)--status all|active|inactive --limit N --cursor C — pages of rules, not the expenses they make
banana recurring add--title --amount --currency --frequency --start --split required; --interval --end --paid-by --group --description --split-type
banana recurring get <rule-id>one rule, its splits, and the expenses it created
banana recurring edit <rule-id>any subset of the add flags, plus --no-group --no-end --active --inactive
banana recurring delete <rule-id>removes the rule itself
banana payments add--amount --currency --from --to --date required; --group --description --automated
banana payments get <payment-id>
banana payments restore <payment-id>brings a deleted payment back
banana groups [list]--search TEXT --limit --cursor --archived --sort balance|lastActivity
banana groups create--name --currency required; --description --member --type vacation|roommates|couple|travel|party|other
banana groups get|members|activities <group>activities takes --search --limit --cursor --type all|expenses|payments|recurring_expenses --sort date|amount --direction asc|desc
banana friends [list]--search TEXT --limit --cursor --sort balance|lastActivity --filter all|guests
banana currencies [list]--code EUR --search krona — browsing only, writes take the code directly
banana me / login / logout / version / upgradebanana -v aliases version; update aliases upgrade
banana doctor--json — version, PATH, API, login and skill freshness
banana uninstallremoves the CLI itself — ask the user first, and never run it unprompted

banana <command> --help is authoritative and cheap. Read it before guessing a flag.

Writing an expense correctly

  • Dates are YYYY-MM-DD or DD-MM-YYYY, required when adding expenses or payments. An edit preserves the existing date unless supplied. Resolve relative dates from the user's context; the dates below are examples.
  • A time goes on --date after a T: --date 2026-09-16T21:20:00, with optional seconds, milliseconds and an offset (Z or +02:00). With no time the row lands at midnight UTC, and with no offset the time is read as UTC. Pass one whenever the user gave a time — several expenses on one day otherwise all read as midnight.
  • Splits must add up to --amount. Repeat the flag: --split me=10 --split Ana=10.
  • A request to be notified means --notify-me. When the user asks, in any language or wording, to be notified, pinged, alerted or sent a notification about an expense being added ("notify me", "send me a notification", "let me know", "ping me", "avisa-me", "notifica-me", "manda-me uma notificação", "avísame", "notifícame"), pass --notify-me to banana expenses add. This sends BananaSplit's own expense-created push, which is what they want — do not reach for a generic agent notification tool instead. Also pass it when an automation runs banana expenses add, so the user hears about the row. edit has no --notify-me; say so if asked to be notified about an edit.
  • --automated is only for automations, never for a row a person or an agent creates as it is asked for. See Jobs and scripts.
  • --split-type is equal, custom, percentage or shares. It labels how the split was arrived at; --split values are amounts in every case, and still have to sum to --amount.
  • Without --group, at least one --split is required. With a group, omitting splits lets the API split it across the group. When adding an expense, an explicit --split-type requires splits.
  • A group states its own default split. banana groups get has defaultSplitType (equal or percentage) and banana groups members each member's defaultSplitPercentage. Read those before reconstructing a split from past expenses, and label a split that came from the group's percentages percentage, not custom.
  • A group listing names at most three members. banana groups --json gives each group a memberCount and a membersPreview of up to three names. Use banana groups members <group> for the whole roster, and banana groups get for the group's type.
  • Changing an amount: an existing equal split is recomputed across its current participants if no splits are supplied. For other split types, supply matching --split values that sum to the new total.
  • Only the fields you pass to edit change; everything else keeps its value.
  • --json amounts are numbers (or null when unavailable). --raw may contain 18-decimal strings such as "8.100000000000000000"; compare those numerically.
  • Prefer flags to positional JSON bodies: names are resolved through flags, while JSON bodies use API fields and ids. A cleaned expense has splits, but it is not a write payload to send back wholesale.
# paid for dinner for the trip group
banana expenses add --title Dinner --amount 42 --currency EUR \
  --date 2026-09-09 --group "Lisbon trip" --json

# a taxi split with one friend, no group
banana expenses add --title Taxi --amount 20 --currency EUR \
  --date 2026-09-09 --split me=10 --split Ana=10 --json

# settle up: direction is always named explicitly
banana payments add --amount 20 --currency EUR \
  --from me --to Ana --date 2026-09-09 --json

Successful expense, single-payment and group creates, and expense edits, normally read their detail back for --json. No extra get is needed. --raw skips that read; a payment response containing multiple rows retains a thin array shape.

Recurring expenses

A recurring expense is two things: a rule that says what to create and how often, and the expenses it has created so far. banana expenses add writes a one-off expense and can never make it recurring; the rule is its own row under banana recurring, which banana expenses recurring also reaches.

  • --frequency is daily, weekly, monthly or yearly, and --interval N makes it every N of those (--frequency weekly --interval 2 is fortnightly).
  • --start and --end take the same dates --date does, YYYY-MM-DD or DD-MM-YYYY with an optional time. --start is required; without --end the rule runs indefinitely.
  • --split is required, even with --group. The splits are the template every occurrence is created from, and they must add up to --amount.
  • Pausing is not deleting. --inactive stops a rule creating expenses and leaves the ones it already created; banana recurring delete removes the rule.
  • A cleaned rule carries nextOccurrence, lastGenerated and active. banana expenses list --recurring --json lists the expenses a rule created; each one has isRecurring.
# rent, split with a flatmate, every month from October
banana recurring add --title Rent --amount 900 --currency EUR \
  --frequency monthly --start 2026-10-01 \
  --split me=450 --split Ana=450 --json

# stop it without losing the history
banana recurring edit <rule-id> --inactive --json

The create endpoint answers with no row, so the CLI finds the rule it just wrote in the listing and reads it back. That is the one write whose --json shape can be wrong if two rules with the same title and amount are created at once.

Jobs and scripts

--automated on expenses add and payments add marks a row as created by a job or script. When you write a job or script that adds expenses or payments, put --automated on every create call in it.

Leave it off when a person or an agent creates the row at the time it is asked for, including when you add one in a conversation. expenses edit has no --automated.

In a job or script, check the login first with banana me --json, use --json, and stop on a non-zero exit. For a fixed amount on a fixed schedule, use banana recurring add instead.

#!/bin/sh
set -eu
banana me --json > /dev/null
banana expenses add --title "Airbnb" --amount 64.20 --currency EUR \
  --date 2026-10-01 --group "Lisbon trip" --automated --json

Paging

Expenses, recurring rules, groups and friends listings default to 5 rows. For a paged --json response {items, hasMore, nextCursor}, pass a non-null nextCursor back as --cursor with the same filters and sorting. Raise --limit when useful, but check hasMore before treating a page as complete. Per-person balances, group members and currencies return arrays instead. Do not assume every collection supports cursors.

--search on groups and friends filters on the server. It matches names. A username or an email is resolved through GET /users/search, and only when that person is already a friend. The friends list does not include either field.

Failures

Usage errors in human mode include the command's help. In --json, failures return an error object with type and message, plus optional status and body. The type is usage | config | network | api | cancelled.

exitmeaning
2usage error — inspect the message and request the command's help
1config, network or API error
130cancelled

A failed write may already have succeeded: the mutation can complete before a network failure or a failed detail read. Do not blindly repeat it. Inspect the relevant expense list or group activity, or use a known row id, to establish what was saved. If the outcome remains unclear, report the uncertainty before retrying.

Recipes

  • "What do I owe?" → banana balances --json, then report per person by name.
  • "How much does Ana owe me?" → banana friends --search ana --json, which carries her balance and its currency. banana balances --json has the same balance without a currency field.
  • "What's been spent on the trip?" → banana groups activities "Lisbon trip" --type expenses --sort amount --direction desc --json.
  • "Log the dinner I paid for" → establish amount, currency, date and participants, then one expenses add. If they named no group and no one else, ask who to split with.
  • "Settle up with Bruno" → read banana balances --json, then establish the amount, currency, direction, date and group scope, and whether money was paid. Balance output has no currency field; inspect the matching friend's currency or clarify it with the user before recording a payment. Record one payment once the details are authorized.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.