Using the CLI with AI agents

AI agents that run terminal commands, such as Claude Code, OpenAI Codex, Cursor’s agent, or Gemini CLI, can use qonto like any other command-line tool. There is nothing to configure in the agent: once you have signed in, the agent runs qonto commands with your session.

When an agent runs qonto, the output goes into the agent’s conversation and is sent to the agent’s provider, who controls it from then on under its own terms, which may include keeping it or using it to train models. The agent can also run commands that change your account (create a card, send an invoice) if you let it. Before you start:

Check how your agent’s provider handles your data, and use a professional account you trust.
Keep the agent asking for your approval before it runs a command that creates, changes, sends, or deletes something.
Double-check what the agent tells you. It can misread data or make mistakes.

CLI or MCP server?

Both give an AI assistant access to your Qonto account, as you, within your role.

	Qonto CLI	Qonto MCP server
Works with	Agents that run terminal commands on your machine	Chat assistants and IDEs that support MCP (Claude, ChatGPT, Cursor, Le Chat, and more)
Setup	Install `qonto` and sign in once	Add the server URL to the assistant
Surface	One command per Business API endpoint, raw API JSON	Tools designed for conversations, which may combine several endpoints
Good for	Scripts, exports, bulk work, combining Qonto data with local files	Asking questions and running actions from a chat

Tell your agent about the CLI

Agents discover the CLI with --help, but a few lines in your agent’s instructions file (AGENTS.md, CLAUDE.md, or your agent’s equivalent) make it faster and safer:

## Qonto
- Use the `qonto` CLI for Qonto data. `qonto --help` lists the
  resources; `qonto <resource> <action> --help` shows a command's flags.
- Add -o json to get the API's JSON. Use --jq or --fields to keep
  only what you need.
- List commands return one page. Add --all only with filters that
  keep the result small.
- Only run list and get commands on your own. Ask me before any
  command that creates, updates, sends, cancels, deletes, or marks
  something.
- Never run `qonto auth token` or print a token.
- Exit code 1 means the API refused the request: read the error on
  stderr before retrying.

Keep the agent’s access narrow

A few habits limit what an agent can do and how much data it sees:

Use your agent’s permission settings. Most agents can allow some commands and ask for others. Allow list and get commands, and keep approval on everything else.
Sign in with read-only scopes when the agent only needs to read. The session then cannot change anything, whatever the agent tries:
qonto auth login --scopes offline_access,organization.read,membership.read,attachment.read,supplier_invoice.read,client_invoices.read,client.read,product.read,team.read,card.read,cash_flow_category.read,einvoicing.read,payment_link.read,subscription.read
The CLI keeps one session per machine, so this also applies to the commands you run yourself. Sign in again without --scopes to get write access back.
Ask for less data. --jq and --fields run on your machine, so only the filtered result reaches the agent. Prefer --fields id,amount,label over sending every field of every transaction.
Keep tokens out of the conversation. qonto auth token prints a credential to your account; an agent has no reason to run it.

What agents can rely on

The API’s own JSON. With -o json, or whenever the output is not a terminal, every command prints the API’s response unchanged. The API reference describes every field.
Separate channels. Data goes to standard output; messages, warnings, and errors go to standard error.
Exit codes. 0 success, 1 API or authentication error, 2 usage error, 3 unsupported CLI version. See Exit codes.
Strong Customer Authentication. When an action needs it, the command waits until you approve in the Qonto app, then finishes. The agent cannot approve for you. See Strong Customer Authentication.

Scripts and scheduled jobs

For unattended use, such as a nightly export on a server:

On a machine without a credential store, sign in once with --store-cleartext and a narrow --scopes list, then pass the same flag on every command.
Alternatively, pass a short-lived access token in QONTO_CLI_ACCESS_TOKEN. The CLI uses it without storing it.

--store-cleartext writes your Qonto session to disk unencrypted, in ~/.config/qonto/credentials.json. Whoever can read that file can act on your Qonto account as you, within the scopes you granted, until you sign out or revoke the access: another administrator of the machine, a backup or a disk image, any program running under your user, including an AI agent with shell access.

Use it only on a machine you control, never on a shared or personal laptop that has a credential store.
Sign in with the fewest scopes the job needs, read-only if it only reads.
Never copy, commit, or upload the file, and keep it out of backups and container images.
When the job no longer needs access, run qonto auth logout --store-cleartext and revoke the CLI from the connected apps section of your Qonto account.

qonto transactions list --settled-at-from "$(date -u -d yesterday +%F)" --all \
  --fields id,settled_at,amount,side,label > transactions.json

​CLI or MCP server?

​Tell your agent about the CLI

​Keep the agent’s access narrow

​What agents can rely on

​Scripts and scheduled jobs

CLI or MCP server?

Tell your agent about the CLI

Keep the agent’s access narrow

What agents can rely on

Scripts and scheduled jobs