@sahidha/cli — the ff command-line client

ff is the command-line client for Sahidha, a private multi-tenant household-finance platform for Indian families (INR, Apr–Mar financial year). Operate accounts, transactions, insurance, investments, reports, and bank- statement imports straight from your terminal — built for humans and AI agents alike.

You need a Sahidha account (your family admin adds you) and a personal access token. The CLI only ever sees your own family's data — tenant isolation is enforced in the database, not just the client.

Install

npm install -g @sahidha/cli
# or run without installing:
npx -y @sahidha/cli --help

Quick start

# 1. Sign in — mints + stores a token in ~/.sahidha/config.json (0600).
ff auth login --api https://api.sahidha.com/api/v1

# 2. Smoke-test.
ff auth whoami --json
ff accounts list --json
ff txns list --from 2026-04-01 --to 2026-05-31 --json

# 3. A report.
ff reports income-expenditure --fy 2025-26 --json

For scripts and agents, always pass --json — the table view is lossy.

Configuration

The CLI reads ~/.sahidha/config.json, overridable by environment:

| Env var | Meaning | |----------------------|-----------------------------------------------------------| | SAHIDHA_API_URL | Base URL (e.g. https://api.sahidha.com/api/v1) | | SAHIDHA_TOKEN | Bearer token (sa_…), replaces the config-file value | | SAHIDHA_CONFIG_DIR | Override the ~/.sahidha location | | FF_OUTPUT=json | Force JSON output, equivalent to --json |

Tokens & scopes

Mint tokens in the web app (Settings → API tokens) or with ff tokens create --name "my-agent" --scope read. Scopes:

• read — GET only (reports, exports, audits). Best for agents that just read.
• write — GET + mutations you can perform.
• admin — admin-only routes (requires family_admin).

Tokens are hashed server-side and shown once at creation. Revoke any time with ff tokens revoke <id> or from the web UI.

Help

ff --help
ff <command> --help

Full agent + API guide: https://mlguptag.github.io/Sahidha/ · Web app: https://app.sahidha.com