Skip to main content
Most problems come from one of four places: the installation, the sign-in, the session store, or a request the API refuses. Run the failing command again with -v to see each request and its status; the output never contains tokens.

​
qonto: command not found

The program is installed but not on your PATH.
  • macOS and Linux: if the installer put it in ~/.local/bin (it says so at the end), add that directory to your PATH in ~/.zshrc or ~/.bashrc, then open a new terminal.
  • Windows: the installer adds %LOCALAPPDATA%\Programs\qonto to your user PATH, which only new terminals see. Close PowerShell and open it again.

​
The installer stops with a checksum error

The downloaded archive does not match the published checksums.txt, so nothing was installed. This is usually a proxy or a network interruption altering the download. Run the installer again, from another network if it keeps failing.

​
macOS says it cannot verify the developer

Releases before 0.2.1 were not signed. Update to the latest version: it is signed and notarized by Apple, and macOS runs it without asking.

​
The browser never comes back to the CLI

After you consent, the browser has to reach http://127.0.0.1:53683/callback on the same machine as the CLI.
  • Remote machine or container: the browser runs on another machine, so it cannot reach the CLI. Use qonto auth login --manual --no-browser, see Signing in from a remote machine.
  • Port already in use: another program is listening on port 53683. Stop it, or sign in with --manual.
  • Stale browser state: close the tab and run qonto auth login again.

​
The session cannot be saved

qonto auth login fails when your system has no credential store, which is common on servers, in containers, and on Linux without a desktop session.
  • On a Linux desktop, make sure GNOME Keyring or KWallet is running and unlocked.
  • On a server or in a container, use --store-cleartext after reading its warning.

​
”Not logged in” although you signed in

  • You signed in with --store-cleartext, but the command does not have it. Pass --store-cleartext on every command, or set QONTO_CLI_STORE_CLEARTEXT=1 in your environment.
  • You revoked the CLI in Qonto or ran qonto auth logout. Sign in again.
Run qonto auth status to see which session the CLI finds, and whether Qonto accepts it.

​
Every command fails with an authentication error

The stored session exists, but Qonto refuses it.
  • The access was revoked from the connected apps section of your Qonto account. Run qonto auth login again.
  • The refresh token expired after a long period without use. Sign in again.
  • QONTO_CLI_ACCESS_TOKEN is set in your environment and holds an expired token. It takes precedence over the stored session: unset it.

​
A command fails with “forbidden” or a missing scope

The request reached Qonto, but Qonto refused it.
  • Your role does not allow this action (for example, some card or membership operations are reserved to owners and admins).
  • Your plan does not include this feature. --help on the command mentions plan restrictions when the API documents them.
  • The session lacks the scope the command needs, because you signed in with a narrower --scopes list. --help shows the scope; sign in again with it.

​
A command fails with a validation error

The API rejected a value. The error names the field (for example /data/attributes/currency). Check the allowed values in --help and in the command’s page of the API reference. With --body, remember that flags on the command line override the matching keys of the document.

​
The SCA approval never arrives

A command is waiting for Strong Customer Authentication and your phone does not ring.
  • Make sure notifications are enabled for the Qonto app on your paired device, then open the app: pending approvals are listed there.
  • If no device is paired with your account, the command says so. Pair one in the Qonto app, then run the command again.
  • After 15 minutes the command gives up without executing the action. Run it again.

​
”qonto … is no longer supported”

Your version is past its support date and refuses to run (exit code 3). Update with the install command.

​
Rate limits and slow lists

Like the API, the CLI is rate limited. --all on a large collection makes one request per page: narrow it with a date range or a status filter.

​
Where to ask for help

  • Check the Business API troubleshooting guide for errors that are not specific to the CLI.
  • For account-level issues (your Qonto role, plan limits, SCA devices), reach out via the in-app support chat.
  • To report a bug or request a feature, open a request and include the output of qonto version and of the failing command with -v.