LucasApp CLI

Manage LucasApp finances from the terminal. The CLI is built for humans, scripts, and AI agents: command output is structured JSON unless a command is explicitly interactive.

Install

npm install -g lucasapp-cli

Authenticate

lucas auth login
lucas auth status
lucas auth logout

login opens LucasApp in your browser and asks you to approve a short visible code. Credentials are stored locally in ~/.config/lucas/credentials.json with owner-only permissions. logout clears the local credentials and attempts to revoke the CLI device token server-side.

Common Commands

lucas accounts list --include-archived
lucas accounts create --name "Savings" --type SAVINGS --bank BCP --currency PEN
lucas accounts debt-detail <account-id> --mode current_cycle

lucas transactions list --from 2026-05-01 --to 2026-05-31 --search rappi --limit 10
lucas transactions create --account-id <id> --amount 35 --type EXPENSE --description "Lunch"

lucas transfers list --limit 10 --offset 0
lucas transfers create --from-account-id <id> --to-account-id <id> --amount 500

lucas subscriptions list --type SERVICE --limit 20
lucas subscriptions mark-paid <id>

lucas loans list
lucas loans pay <id> --amount 750 --verified
lucas loans mark-paid <id> --verified

lucas stats summary
lucas stats by-category --year 2026 --month 5
lucas exchange-rate convert --from USD --to PEN --amount 25

lucas ai usage
lucas ai parse-expenses "lunch at Pardos S/ 35" --date 2026-05-08 --account-id <id>
lucas ai parse-expenses-image receipt.jpg --date 2026-05-08 --account-id <id>
lucas ai insights "How am I doing this month?" --period month --currency PEN

Command groups: auth, accounts, transactions, transfers, subscriptions, loans, stats, categories, exchange-rate, and ai. The ai group is intentionally limited to usage, text/image expense parsing, and read-only insights.

List commands are intentionally agent-friendly:

• transactions list supports --account-id, --account-ids, --category-id, --category-ids, --type, --search, --min-amount, --max-amount, --from, --to, --limit, and --offset.
• transfers list supports --limit and --offset over transfer pairs. Each transfer pair still returns its two transaction rows.
• subscriptions list supports --limit, --offset, --frequency, --type, and --group-id.
• accounts list --include-archived includes archived accounts in the account array and adds archivedAccounts metadata. Balance/debt totals remain the active-account totals returned by LucasApp.
• exchange-rate convert --amount <n> includes a client-side convertedAmount derived from the backend rate.

JSON Output

Success:

{ "ok": true, "data": { "example": true } }

Error:

{
  "ok": false,
  "error": {
    "message": "Not authenticated. Run: lucas auth login",
    "statusCode": 401
  }
}

Security Notes

• Do not pass arbitrary local files to agent-driven commands.
• parse-expenses-image accepts only real JPG, PNG, WebP, or HEIC files and rejects symlinks, suspicious credential paths, unsupported extensions, and oversized images.
• Resource IDs are validated before building API paths.
• Backend error details are summarized by default. Set LUCAS_DEBUG=1 only while debugging locally; sensitive fields are redacted.
• Network failures return structured JSON instead of raw Node stack traces.
• LUCAS_API_URL is intended for local development and advanced testing. Normal users should keep the default production URL.
• Never commit .env, .npmrc, credentials, keys, certificates, service account files, database dumps, or private fixtures.

Development

bun install --frozen-lockfile
bun run format:check
bun run typecheck
bun run lint
bun run test
bun run build
npm pack --dry-run --json --ignore-scripts

The npm package publishes only the built CLI and package metadata. Releases use npm Trusted Publishing with provenance; do not add long-lived npm tokens to the repository or workflow.

License

MIT