freshness-check

freshness check

Answer one question — is this data current enough to use? — and act on the answer. Every analysis skill that reads financy data should start here.

Minimum CLI version: 0.1.0

Guardrails

• Confirm before spending credits. financy refresh costs 20 credits every time it is called. Never run it without stating the cost and getting an explicit yes from the user in this conversation. "The data is stale, want me to refresh?" is not enough — say the number.
• Never echo the client secret or the contents of the config file. If you need to show what is configured, use financy config, which masks the secret.
• Exit code 4 means the plan, not the credentials. Point the user at the upgrade path at https://open-finance.ai and stop; do not retry and do not ask for new credentials.

Method

1. Read the status

financy status --json

The envelope:

{
  "data": [
    {
      "provider": "hapoalim",
      "status": "ACTIVE",
      "fresh": "2026-08-01",
      "expires": "2026-11-14",
      "accounts": 3
    }
  ],
  "staleThresholdDays": 2
}

Per row:

• provider — the bank or card issuer. null while a connection is still being established.
• status — ACTIVE means the connection itself is healthy. Anything else is a broken connection, not a staleness problem.
• fresh — the date the data runs through, as YYYY-MM-DD. null means the connection has never fetched anything.
• expires — when the user's bank consent lapses. Not a freshness signal, but worth surfacing when it is close.
• accounts — how many accounts, cards, savings, loans and securities this connection covers.

staleThresholdDays is the CLI's own threshold (2 days). Read it from the response rather than hard-coding it.

Handle the exit code before the body: 3 → the CLI is not configured or the credentials are rejected, so run the financy-setup skill instead; 4 → see the guardrail above; 7 → the API is unreachable, retry once then report.