Telemetry

The CLI collects a small amount of anonymous usage analytics to understand which commands are used and where they fail, so the tool can be improved. It is designed to be privacy-preserving by construction: it never sees your account data or your command arguments.

What is collected#

One event is recorded per real command, with these fields:

• The resolved command name, for example transactions list (never the raw arguments you typed).
• Whether the command succeeded.
• How long it took, in milliseconds.
• A mapped error code class on failure, for example conflict or rate_limited (never the raw error message).
• The CLI version.
• The authentication method: apiKey, oauth, or anonymous.

Events are tied to a random, locally generated identifier stored at ~/.config/banksync/cli-id. It is not linked to your identity, your key, or your workspace, and the CLI never calls identify or alias.

What is never collected#

Several commands emit no telemetry at all: --help, --version, commands, schema, config, and shell autocomplete. Diagnostics and logs are never sent to analytics.

The first-run notice#

The first time you run a command that emits telemetry, the CLI prints a one-time notice to stderr describing what is collected and how to opt out, then does not show it again. Because it is written to stderr, it never pollutes stdout, so the disclosure is shown on the first tracked run even when output is piped, in a machine format, or in CI.

How to opt out#

Any one of these disables telemetry completely. When disabled, no events are captured.

• Set the widely supported DO_NOT_TRACK variable:

export DO_NOT_TRACK=1

• Set the BankSync-specific variable to an off value (0, false, off, or no):

export BANKSYNC_TELEMETRY=0

• Turn it off persistently in your config (per profile):

banksync config set telemetry off

Any of these takes effect immediately on the next command. Environment variables are convenient for CI; the config setting persists across sessions on your machine.

Environments#

In local dev and staging builds the CLI uses a no-op analytics provider, so those runs never send anything regardless of settings. The opt-out is honored in every environment. Telemetry flushes with a short timeout, so it can never delay or hang your terminal.

Next steps#

• Authentication: profiles and where config and credentials live.
• Scripting and CI: disabling telemetry in automation.
• Installation: install and update the CLI.