Run Daffy from the terminal with daffy-cli

daffy-cli is a small command-line client for the Daffy Public API. It lets an AI agent (or you) search charities, check a fund balance, make and cancel donations, list contributions and send gifts, and every command can print JSON for an agent to parse. Set an API key, point your agent at daffy-cli, and it's ready to go.

npx daffy-cli auth <your-key>
npx daffy-cli search "doctors without borders" --json
npx daffy-cli balance --json
npx daffy-cli donate --ein 133433452 --amount 50 --yes --json

Not sure this is the right route? Pick the CLI when your agent lives in a terminal, a CI job or a script (Claude Code, Codex, a shell) and needs output it can parse; pick the MCP server for chat assistants like Claude and ChatGPT. The AI Agents overview compares every option.

Install

The package is daffy-cli on npm (opens in a new tab). It needs Node.js 18 or newer and an API key, nothing else: no SDK, no server.

npx daffy-cli --help

Or install it globally and drop the npx prefix:

npm install -g daffy-cli
daffy-cli --help

The examples on this page use npx daffy-cli; installed globally, daffy-cli behaves the same.

Authenticate

Every command needs an API key. Create one at daffy.org/settings/developers (opens in a new tab); it's shown only once, so copy it straight away (see Authentication for the walkthrough). Then pick one of these:

# Option A: the auth command, which checks the key and saves it to ~/.daffy/credentials
npx daffy-cli auth <your-key>
 
# Or run it without an argument for a prompt
npx daffy-cli auth
 
# Option B: write the credentials file yourself
mkdir -p ~/.daffy && echo 'DAFFY_API_KEY=your-key' > ~/.daffy/credentials
 
# Option C: environment variable, which takes precedence over the file
export DAFFY_API_KEY="your-key"

Treat the key like a password. Getting an API key on the overview page covers how to hand it to an agent safely and when to revoke it.

What agents can do

Everything the CLI does is scoped to the member whose API key it's using: an agent sees and does only what you could in the Daffy app.

Commands

Three commands change your account: donate and gift create move real money, and cancel permanently deletes a donation, returning the amount to your fund. All three show what they're about to do and wait for a [y/N] answer before calling the API. Pass --yes to skip the prompt, and only once the member has explicitly confirmed.

donate looks up the EIN first, so the confirmation shows the charity's name and a mistyped EIN fails before any money moves. Amounts below the minimum are rejected before a request is sent.

Options

Set NO_COLOR to turn off the colours in formatted output.

JSON output and pagination

Agents should add --json to every command. Without it the CLI prints tables meant for people; with it you get the API's response, ready for jq or JSON.parse:

npx daffy-cli balance --json
npx daffy-cli search "khan academy" --json | jq '.items[].name'
npx daffy-cli donations --json | jq '.items[] | {id, amount, status}'

The objects are the same ones the REST API returns, so the field lists in the API Reference apply.

Paginated commands (search, donations, contributions, gifts) return items plus a meta object with count, page and last (see Pagination). Ask for another page with --page and keep going until page equals last:

last=$(npx daffy-cli donations --json | jq '.meta.last')
for p in $(seq 1 "$last"); do
  npx daffy-cli donations --json --page "$p" | jq -r '.items[] | "\(.id)\t\(.amount)\t\(.non_profit.name)"'
done

Example: donate by name

A typical agent flow: search, check funds, then donate.

# 1. Find the charity
npx daffy-cli search "khan academy" --json | jq '.items[0].ein'
 
# 2. Check what's available to donate
npx daffy-cli balance --json | jq '.available_balance'
 
# 3. Donate, once the member has confirmed the charity and amount
npx daffy-cli donate --ein 261544963 --amount 25 --note "Great work" --yes --json

If the search returns more than one plausible match, show the candidates (EIN, name, city, state) and ask which one before going on. If the member gave you an EIN, skip the search and run nonprofit <ein> --json to verify it. Then report the new donation's id, status and amount back to the member.

If a donate, cancel or gift create call times out or fails with a network error, it may or may not have gone through. Check with donations --json (or gifts --json) before retrying.

Skill file

If your agent framework supports skills, you don't have to teach it the commands above yourself. Install this file as a skill and the agent will know every command, the flags to use, the multi-step workflows, and when to stop and ask for confirmation.

It follows the Claude Code skill format (opens in a new tab). For Claude Code, save it as .claude/skills/daffy-api/SKILL.md in your project, or under ~/.claude/skills/ to have it everywhere. Other frameworks have their own locations; check their docs. Use it as-is or extend it with your own workflows.

Example repos

• Example agent code: daffyorg/examples/agents/daffy-http-donation (opens in a new tab)
• Skill files: daffyorg/examples/skills/daffy-donation (opens in a new tab)
• The CLI itself: daffy-cli on npm (opens in a new tab)

Troubleshooting