@endaoment/ndao-cli
v0.7.0
Published
Anonymous Endaoment organization and public fund reads
Readme
Endaoment CLI
ndao searches nonprofits, browses and searches public funds, and retrieves their details. Those commands run anonymously. login signs a person in through the browser, whoami shows who is signed in, fund mine and activity mine show that person's funds and giving, grant create asks Endaoment to send a grant from one of those funds, and donate wire records a wire gift into one. With a partner API key, partner whoami identifies the API client, and the other partner commands read the funds and receipts that partner owns. Only grant create and donate wire ask a question, and only on a terminal. Production is the default environment.
Run ndao, ndao org, or ndao fund to see that group's help and available commands. ndao config shows configuration; commands such as ndao fund get still require their documented arguments.
Install
Use Node 22.12.0 or later, on macOS or Linux. Windows is untested. The package declares >=22.12.0; npm normally warns about incompatible engines rather than refusing installation. An installer can enable npm's engine-strict setting to require that minimum.
The package is public on npm. No account, token, or registry setup:
npm install --global @endaoment/ndao-cli
ndao --versionThe executable bundles its API client and libraries; the package has no additional runtime dependencies. It needs no backend checkout, compiler, database, or code generation.
Versions before 0.3.0 were published to GitHub Packages. If you installed one, remove the old scope mapping before upgrading, or npm keeps looking there:
npm config delete @endaoment:registry
npm install --global @endaoment/ndao-cliRead organizations and funds
ndao config
ndao org search "food bank" --count 3
ndao org get 11-1111111
ndao org get <existing-org-id>
ndao org subprojects 11-1111111
ndao subproject search garden --count 5
ndao org distributions <existing-org-id>
ndao org counts K,L
ndao fund featured
ndao fund community --count 5 --offset 10
ndao fund search "education" --types Community,ImpactPool --count 5
ndao fund get <public-fund-id>
ndao fund get <fund-vanity>
ndao fund universal
ndao fund get <public-fund-id> --json | jq '.usdcBalance'
ndao stats
ndao token list --chain 10
ndao activity featured
ndao activity org <existing-org-id> --count 5Replace the angle-bracket placeholders with actual ids; 11-1111111 is an illustrative EIN. Search returns one page. Use --offset for another page, or --help to see the available filters. Org lookup passes UUIDs or EINs to the selected API. Fund lookup accepts a UUID or vanity name and can only read publicly visible funds. UUID-shaped values use the ID route; other nonempty values use the vanity route, without a fallback request. ndao fund universal is a shortcut for ndao fund get universal: it returns the single UIP in the selected environment, like the frontend.
| Org and subproject command | Options and result |
| -------------------------- | ----------------------------------------------------------------------------------------------- |
| subprojects <ein> | The projects a nonprofit sponsors, by EIN with or without the hyphen. |
| distributions <id> | The distributions a nonprofit is eligible for. Takes a UUID only. |
| counts <codes> | How many nonprofits each NTEE major code has. Codes are comma-separated letters, such as K,L. |
| subproject search [term] | --count 1–25 and --offset 0 or more, sent only when given. |
| Fund command | Options and result |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| featured | Up to 10 funds; no pagination options. |
| community | --count 1–50 (default 10); --offset 0 or more (default 0). |
| search <term> | --types comma-separated values; public types are Community, Transparent, ImpactPool. --count 1–25 (default 10); --offset 0 or more (default 0). The API validates types and visibility. |
| get <identifier> | One fund by UUID or vanity name. |
| universal | One Universal Impact Pool, by vanity universal. |
| Platform command | Options and result |
| ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| stats | Lifetime donations and grants. Two requests, one JSON object. |
| token list | --type and --chain, sent only when given. |
| activity featured | No options. |
| activity org <id>, activity fund <id> | --count 1–100 and --offset, sent only when given. Without them the JSON is the API's bare list; with them it is the API's page envelope. A hidden fund answers an empty list. |
Each command accepts --env, --json, and --help. Lists preserve API order and fetch one page; successive requests do not guarantee a stable snapshot. Use the id or vanity column with fund get to inspect a result.
A terminal receives tables. Pipes and redirection receive JSON automatically; --json forces JSON. JSON preserves the API's response fields and money strings. API changes can affect installed CLI versions. Errors use stderr and leave stdout empty.
| Exit | Meaning |
| ---- | ---------------------------------------------------------------------------- |
| 0 | Success, including an empty search |
| 1 | Request or configuration failure |
| 2 | Local usage failure |
| 3 | Not signed in, missing API key, rejected authentication, or forbidden access |
Sign in
ndao login signs you in to the selected environment as yourself, through the Endaoment sign-in page. It prints an address and a code on standard error and tries to open the address in your browser. Approve there and the command finishes. Standard output carries only the result: the environment and your user id.
ndao login --env dev
ndao whoami --env dev
ndao fund mine --env dev
ndao activity mine --env dev --count 5
ndao logout --env dev| Command | Result |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| login | Signs in and stores the session. A second login replaces it. |
| whoami | The signed-in person's user id, and wallet when the API returns one. Exits 3 when not signed in. |
| fund mine | The funds you manage: id, name, type, and the available, invested and processing balances. Available is what you can grant, and counts invested holdings; processing is grants and transfers under way. |
| activity mine | Your giving: donations you made and grants from the funds you manage, with a grant not yet sent as pending_grant. --count 1–100 and --offset, sent only when given; with them the JSON is the API's page envelope. |
| logout | Revokes the session at the auth server and deletes it. Prints not signed in when there is none. If the auth server cannot be told, the session is still deleted, with a notice. |
Each environment has its own session, kept in session.<env>.json in the config file's directory: ~/.config/ndao/ by default, or beside the file NDAO_CONFIG names. The file has mode 0600, and a session file other users can read is refused. The session renews itself shortly before its access token lapses. If the auth server rejects the renewal, the session is deleted and the command asks you to sign in again. whoami, fund mine and activity mine exit 3 with that hint when there is no session, whatever keys are exported. Public commands stay anonymous with a session present, and partner commands use only the API key.
BROWSER names the program that opens the address, as with other command-line tools. Without it, ndao uses open on macOS, xdg-open on Linux, and start on Windows. When nothing opens, use the printed address. BROWSER=true never opens one.
For one release, whoami with an API key and no session still answers as the API client, and prints notice: whoami with an API key is now partner whoami on standard error. Use partner whoami for the API client. From the next release, whoami with an API key and no session exits 3 with the ndao login hint and makes no request.
Give
Signed in, you can ask Endaoment to send a grant from one of the funds you manage to a nonprofit, and withdraw the request until it is sent. With FUND_ID holding an id from fund mine and GRANT_ID the id grant create printed:
ndao grant preview --from "$FUND_ID" --to 12-3456789 --amount 100 --env dev
ndao grant create --from "$FUND_ID" --to 12-3456789 --amount 100 --env dev
ndao grant cancel "$GRANT_ID" --env dev| Command | Result |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| grant preview | Reads the fund and the nonprofit and shows what a grant request would send: the amount, the fund's name and available balance, the nonprofit's name and EIN, the purpose, and the idempotency key. Sends nothing. With --json the preview is on standard output, with a fresh key. |
| grant create | Shows the same preview on standard error and asks Send this grant request? [y/N]. On a yes it sends one grant request and prints the grant id and its status, waiting to be sent; the JSON is the API's grant object. |
| grant cancel <id> | Withdraws a grant that is still waiting to be sent. A grant already sent, or one from a fund you do not manage, is the API's refusal, with its status. |
--from is a fund UUID from fund mine; any other fund is refused before the nonprofit is read. --to is a nonprofit UUID or EIN, with or without the hyphen. --amount is dollars, more than 0 with at most two decimals. The purpose is General Purpose, or Restricted Grant with --instructions, unless --purpose names one. Your email goes to the nonprofit only with --share-email. Whether you may grant, whether the balance covers it, and whether the nonprofit may receive it are the API's answers, shown with their status.
--yes answers the question. With --json, or when standard output is not a terminal, grant create needs --yes and makes no request without it. Each grant request carries an idempotency key: a fresh one per run, or the one --idempotency-key gives. When the outcome is unknown (a timeout, a dropped connection, a 5xx), the error names the key; rerun with --idempotency-key <key> and the API returns the same grant rather than a second one. Money moves once Endaoment sends the grant; until then, grant cancel withdraws it.
Wire a gift into a fund
You can also tell Endaoment that a wire is coming for one of the funds you manage. The pledge records the amount and gives you the bank details to wire it to:
ndao donate preview --to "$FUND_ID" --amount 250 --env dev
ndao donate wire --to "$FUND_ID" --amount 250 --env dev| Command | Result |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| donate preview | Reads the fund and the wire instructions and shows the amount, the fund's name, every bank detail the API returns, and the idempotency key. Sends nothing. With --json the preview is on standard output, with a fresh key. |
| donate wire | Shows the same preview on standard error and asks Record this wire pledge? [y/N]. On a yes it records one pledge and prints the pledge id, the bank details again, and what happens next. The JSON is { "id", "instructions" }, the instructions as the API sent them. |
--to is a fund UUID from fund mine; any other fund is refused before anything is recorded. --amount is dollars, more than 0 with at most two decimals. --international shows the international bank details (SWIFT code and IBAN) instead of the domestic ones; the pledge is the same. The donor is you, as the fund's manager. Whether you may pledge to the fund is the API's answer, shown with its status.
--yes and --idempotency-key work as they do for grant create. Two runs without a key make two pledges. The API answers a key it already holds with the pledge it recorded, whatever the amount, so when you pass --idempotency-key, donate wire checks that pledge in activity mine. A pledge recorded with another amount or fund, or one it cannot find on the newest page, is refused and named; nothing is printed as success. Nothing moves until your wire arrives and Endaoment confirms it; until then the pledge shows in activity mine as a cash_donation_pledge awaiting assets.
API-key access
A partner supplies its existing API key through the variable for the environment it wants to use. Nothing is read from a file and nothing is stored.
| Environment | Key variable |
| ----------- | ---------------------- |
| local | NDAO_API_KEY_LOCAL |
| dev | NDAO_API_KEY_DEV |
| staging | NDAO_API_KEY_STAGING |
| prod | NDAO_API_KEY_PROD |
With the key exported by your shell or secret tooling, and FUND_ID, DONATION_ID, and PLEDGE_ID holding ids the partner owns:
ndao partner whoami --env prod
ndao partner fund get "$FUND_ID" --env prod
ndao partner fund get "$FUND_ID" --env prod --json
ndao partner fund activity "$FUND_ID" --env prod --count 5
ndao partner fund grants "$FUND_ID" --env prod
ndao partner receipt donation "$DONATION_ID" --env prod
ndao partner receipt pledge "$PLEDGE_ID" --env prod| Partner command | Options and result |
| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| partner whoami | The API client the key represents: name, roles, and partner identity when present. |
| partner fund get <id> | One owned fund, in the existing fund detail format. |
| partner fund activity <id> | Recent activity for an owned fund. --count 1–100 and --offset, sent only when given; with them the JSON is the API's page envelope. |
| partner fund grants <id> | Grants sent from an owned fund. |
| partner receipt donation <id> | The receipt for a donation the partner reported. |
| partner receipt pledge <id> | The receipt for a donation pledge the partner reported. |
partner whoami does not identify a person or prove access to a fund. Each other partner command takes a UUID and calls the partner ownership endpoint. A missing id and one owned by another partner produce the same 404. Every command accepts --env, --json, and --help; ndao partner, ndao partner fund, and ndao partner receipt show their available commands.
Keys are environment-bound: selecting staging reads only NDAO_API_KEY_STAGING. There is no fallback to another variable, another environment, a config-file secret, or a session from ndao login. Keys must contain visible ASCII without whitespace and are sent unchanged. A missing key fails before any request; a rejected key or denied access exits with code 3. Existing org and fund commands stay anonymous even when keys are exported.
Authenticated requests require HTTPS, except HTTP loopback for local, and refuse redirects. A key that an error message reflects is replaced by [REDACTED] in the CLI's output. The partner commands are reads; the same key may have more permissions through another API client.
Use from an AI agent
ndao mcp serves the same commands as tools over the Model Context Protocol (MCP) on standard input and output. Add it to any MCP client with no credentials:
{ "mcpServers": { "endaoment": { "command": "ndao", "args": ["mcp"] } } }Claude Desktop reads that from its claude_desktop_config.json; Cursor from .cursor/mcp.json; Codex from ~/.codex/config.toml with the equivalent [mcp_servers.endaoment] table. Then ask for three food banks and their EINs.
| Tool | Command | Listed |
| -------------------------- | -------------------------- | ---------------- |
| org_search | org search | Always |
| org_get | org get | Always |
| org_subprojects | org subprojects | Always |
| subproject_search | subproject search | Always |
| org_distributions | org distributions | Always |
| org_counts | org counts | Always |
| fund_featured | fund featured | Always |
| fund_community | fund community | Always |
| fund_search | fund search | Always |
| fund_get | fund get | Always |
| fund_universal | fund universal | Always |
| stats | stats | Always |
| token_list | token list | Always |
| activity_featured | activity featured | Always |
| activity_org | activity org | Always |
| activity_fund | activity fund | Always |
| whoami | whoami | With a session |
| fund_mine | fund mine | With a session |
| activity_mine | activity mine | With a session |
| grant_preview | grant preview | With a session |
| grant_create | grant create --yes | With a session |
| grant_cancel | grant cancel | With a session |
| donate_wire_preview | donate preview | With a session |
| donate_wire | donate wire --yes | With a session |
| partner_whoami | partner whoami | With the API key |
| partner_fund_get | partner fund get | With the API key |
| partner_fund_activity | partner fund activity | With the API key |
| partner_fund_grants | partner fund grants | With the API key |
| partner_receipt_donation | partner receipt donation | With the API key |
| partner_receipt_pledge | partner receipt pledge | With the API key |
The eight signed-in tools, from whoami to donate_wire, appear only when the launch environment has a session from ndao login, and their descriptions name the signed-in person. grant_preview and donate_wire_preview are declared read-only to the host, and grant_create, grant_cancel and donate_wire are declared writes, so the host asks the person before it runs them. grant_create requires the idempotencyKey that grant_preview returned and confirm: true, and donate_wire the one donate_wire_preview returned; their descriptions tell the agent to show the person the preview and get their yes first. donate_wire always checks the recorded pledge, as donate wire --idempotency-key does. Each call uses the session as it stands then, so a sign-out in a terminal after launch makes the next call fail with exit 3. The partner_ tools appear only when the launch environment's key variable is set; their descriptions say so. A tool takes the command's arguments and options under the same names, camel-cased (nteeMajorCodes, count), with a flag as a boolean (shareEmail). A tool result is the command's JSON, unchanged. A failed command is a tool error carrying the same JSON error the command prints, and the server keeps serving. The environment is chosen once at launch, ndao mcp --env staging, with the same precedence as every command, and each tool description names it. Standard output carries only protocol messages; the server writes one notice to standard error at launch.
Configuration
Environment selection is --env, then NDAO_ENV, then the config file's defaultEnv, then prod. Available environments are local, dev, staging, and prod. Production is intended for normal use; the other environments are for development and may require team network access. ndao config shows the selected source, all URLs, offline credential availability, and the session. credential: api-key with a credentialSource means the key variable is present, not that the API accepted it; the value is never shown. session names the signed-in user id and the session file, without a request. ndao config show is an alias.
The optional file is ~/.config/ndao/config.json, overridden by NDAO_CONFIG. Every field is optional; commands read it without creating or modifying it. Use mode 0600 when creating one yourself. Only local accepts URL overrides, for the API and for the auth server login uses:
{
"defaultEnv": "local",
"envs": { "local": { "baseUrl": "http://localhost:4444", "authUrl": "http://localhost:3000" } }
}Requests have a ten-second deadline, including the response body, and do not retry automatically. NDAO_TIMEOUT overrides the deadline in seconds.
