> ## Documentation Index > Fetch the complete documentation index at: https://docs.visorfinance.app/llms.txt > Use this file to discover all available pages before exploring further. # Command-line interface > Use the personal API from your terminal with the visor CLI. The `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](https://github.com/Visor-Finance/visor-cli). ## Install ```bash Homebrew theme={null} brew install visor-finance/tap/visor ``` ```bash macOS and Linux theme={null} curl --proto '=https' --tlsv1.2 -LsSf https://github.com/Visor-Finance/visor-cli/releases/latest/download/visor-installer.sh | sh ``` ```powershell Windows theme={null} powershell -ExecutionPolicy Bypass -c "irm https://github.com/Visor-Finance/visor-cli/releases/latest/download/visor-installer.ps1 | iex" ``` Check the install with `visor --version`. Shell completions are available with `visor completions zsh`, as well as `bash`, `fish`, and `powershell`. ### Update ```bash theme={null} visor update # update the way the CLI was installed visor update --check # only compare versions; exit code 1 when a new one is out ``` `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. ````bash theme={null} visor settings autoupdate # show the setting visor settings autoupdate disable # keep only the new-version notice ``` `visor update` arrived in 0.6.0: to get there from an older version, run `brew upgrade visor-finance/tap/visor` or the install command again. ## Log in ```bash visor auth login ```` The CLI opens Visor in your browser. Log in, choose **Read only** or **Read and record transactions** (needed to record, edit, or delete transactions), and approve. The CLI then shows your account and stores the login in the system keychain: Keychain on macOS, Credential Manager on Windows, Secret Service on Linux. The login renews itself; see [Visor CLI login](https://docs.visorfinance.app/authentication.md#visor-cli-login). ```bash theme={null} visor auth login --no-browser # print the login page URL instead of opening a browser visor whoami # who is logged in, how, and the space commands act on visor doctor # check the CLI version, the login, the API, and the space visor auth logout # remove the stored login ``` The login appears as **Visor CLI** in [Settings > Connected apps](https://dashboard.visorfinance.app/settings/connected_apps). Revoke it there to end it on every machine. ### Without a browser On a server or in CI, create a personal API token in [Settings > Connected apps](https://dashboard.visorfinance.app/settings/connected_apps) and give it to the CLI: ```bash theme={null} visor auth login --with-token < token.txt # or paste it at the hidden prompt export VISOR_TOKEN="visor_pat_..." # or set it for one shell or job ``` `VISOR_TOKEN` takes precedence over the stored login. See [Authentication](https://docs.visorfinance.app/authentication.md). ## Everyday commands ```bash theme={null} visor spaces list visor spaces use Pessoal # the space the other commands act on visor overview # balances, this period, and the projection visor accounts list visor categories list visor tx list --from 2026-10-01 --category Groceries visor tx add --amount 42.90 --description Padaria --category Groceries --account Nubank visor tx edit TRANSACTION_ID --category Restaurants --tag travel visor tx delete TRANSACTION_ID # asks first; --yes skips the question visor cards list visor subscriptions list visor goals list ``` * Accounts, categories, tags, and spaces accept a name or an ID. A system category also accepts its key without the `category.` prefix, such as `food_and_drinks`. * `--space` picks a space for one command. Without it, the CLI uses the space from `visor spaces use`, then your default personal space. * Amounts are positive decimals, such as `42.90` or `42,90`. `--type debit`, the default, records money out; `--type credit` records money in. * `visor tx add` sends an `Idempotency-Key` and prints it. Run the command again with `--idempotency-key` and that key to retry without recording twice. See [Idempotency](https://docs.visorfinance.app/idempotency.md). Run `visor --help`, or `--help` after any command, for every option. ## Send a Pix ```bash theme={null} visor pix maria@example.com 20,00 -d Lunch # asks where to confirm, then waits visor pix 11987654321 50 --key-type phone --bank Nubank visor pix 123.456.789-09 20 --qr # confirm on your phone: shows a QR code visor pix maria@example.com 20 --open # confirm on this computer: opens the browser visor pix maria@example.com 20 --no-wait --json # print the Pix and its link, then exit visor pix status PIX_PAYMENT_ID # read a Pix you started ``` `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 pix` opens the browser so you can allow Pix, then replaces the stored login with the new one. A personal API token or `VISOR_TOKEN` cannot 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 cpf` or `--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](https://docs.visorfinance.app/api-reference/spaces/list-accessible-spaces.md). Data goes to standard output; notes and errors go to standard error. ```bash theme={null} # Export one year of transactions to a JSON Lines file visor tx list --from 2026-01-01 --to 2026-12-31 --all --json | jq --compact-output '.data[]' > transactions.jsonl ``` A list returns up to `--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](https://docs.visorfinance.app/rate-limits.md). ### Exit codes | Code | Meaning | | - | - | | `0` | Success | | `1` | Other failure, a failed `visor doctor` check, or a new version found by `visor update --check` | | `2` | Invalid usage, such as an unknown flag or category name | | `3` | Not logged in, or the API answered `401` or `403` | | `4` | The API answered `404` | | `5` | The API rejected the request (`400`, `409`, or `422`), or a Pix failed, was canceled, or expired | | `6` | Rate limited, network error, or Visor unavailable | ### Environment variables | Variable | Effect | | - | - | | `VISOR_TOKEN` | Token to use instead of the stored one | | `VISOR_SPACE` | Space name or ID, like `--space` | | `VISOR_CREDENTIAL_STORE` | `file` stores the token in the config directory, readable only by you, on machines without a keychain | | `VISOR_CONFIG_DIR` | Config directory. The default is `~/.config/visor`, or `%APPDATA%\visor` on Windows | | `BROWSER` | Command that opens a URL, instead of the system default | | `NO_COLOR` | Turns off color | | `VISOR_NO_UPDATE_NOTIFIER` | `1` turns off the new-version check: the notice and automatic updates (both are already off in CI and in pipes) | This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.