visor CLI calls the personal API for you. It authenticates with your personal API token, turns names into IDs, follows pages, and retries rate limits. Every operation in this documentation has a command. The source is on GitHub.
Install
visor --version. Shell completions are available with visor completions zsh, as well as bash, fish, and powershell.
Update
visor update runs brew upgrade visor-finance/tap/visor for a Homebrew install, or the new release’s installer into the same directory for the shell and PowerShell installers. If Homebrew or the installer fails, its own error stays on screen and the CLI is left as it was.
Since 0.7.0 the CLI also updates itself. On a terminal, after a command, it installs a newer patch version in the background (its output goes to update.log in the config directory). A new minor or major version, or one more than five patches ahead, is installed before the command, which then runs in the new version. A failed update never stops the command, and the CLI waits an hour before trying again. Only Homebrew and installer installs update themselves; CI, pipes, and --json output never show an update.
Without a browser
On a server or in CI, create a personal API token in Settings > Connected apps and give it to the CLI:VISOR_TOKEN takes precedence over the stored login. See Authentication.
Everyday commands
- Accounts, categories, tags, and spaces accept a name or an ID. A system category also accepts its key without the
category.prefix, such asfood_and_drinks. --spacepicks a space for one command. Without it, the CLI uses the space fromvisor spaces use, then your default personal space.- Amounts are positive decimals, such as
42.90or42,90.--type debit, the default, records money out;--type creditrecords money in. visor tx addsends anIdempotency-Keyand prints it. Run the command again with--idempotency-keyand that key to retry without recording twice. See Idempotency.
visor --help, or --help after any command, for every option.
Send a Pix
visor pix starts a Pix and shows the page where you confirm it with biometrics at your bank; nothing is paid before that. On a terminal it asks where you confirm: on this computer (it opens the page) or on your phone (it shows the page as a QR code). The first Pix from a bank links the bank first. Then the CLI waits until the Pix is paid and prints its end-to-end ID, or fails with exit code 5 when the Pix fails, is canceled, or expires. Ctrl+C stops waiting, not the Pix.
- Pix needs the Pro plan (10 Pix a month) or Premium (30), and the browser login. The first time,
visor pixopens the browser so you can allow Pix, then replaces the stored login with the new one. A personal API token orVISOR_TOKENcannot start a Pix. - Without
--bank, Visor uses the one bank you already linked. Otherwise the CLI asks which bank on a terminal; in a script, the error lists the banks you can pass to--bank. A key that can be a CPF or a phone works the same way, with--key-type cpfor--key-type phone. - A bank link lives on the device that made it. To confirm on another device (the bank page says “Dispositivo não reconhecido”), pass
--link-device: that device links the bank first, then confirms.
Scripting
--json prints the API response body unchanged, so the fields are the ones in the API reference. Data goes to standard output; notes and errors go to standard error.
--limit results (50 by default) and fetches the pages it needs. --all follows every next_cursor, and --after continues from a cursor. The CLI waits for retry-after on 429 and retries 5xx responses, within the rate limits.