Quickstart

This page walks you from a freshly cloned source tree to a successful read-only call against a real bank. It mirrors the Quick Start section of the galanthus README and adapts it for evaluators who are seeing the product for the first time.

gln is the JSON-speaking CLI front end for the galanthus banking library. Every command emits machine-readable JSON, every operational command runs against a resolved profile, and every TAN-gated command can be paused and resumed across process restarts.

What you need before you start

• A C++23 compiler.
• CMake >= 3.21.
• libcurl. On Windows the build fetches and builds curl locally with Schannel, so no separate libcurl install is required.

The build has been verified on Linux, macOS, Windows, and FreeBSD. The snippets on this page use PowerShell because the CLI's primary scripted target is Windows; the same cmake and gln invocations work on the other platforms with the path separators and quoting adjusted.

Build the CLI

From the root of the galanthus source tree:

cmake -S . -B build
cmake --build build --config Release --target gln

The default build also produces galanthus_lib, galanthus-live-suite, and galanthus_tests. If you want to run the test suite as part of the evaluation:

ctest --test-dir build -C Release --output-on-failure

The gln binary lands at build\Release\gln.exe on Windows and at build/gln on Linux, macOS, and FreeBSD. The remaining snippets on this page assume the Windows path.

Create a profile (FinTS)

A profile holds the endpoint, bank code, user identifier, and product identifier for one bank login. You create it once and reference it on later commands with --profile.

.\build\Release\gln.exe `
  profile init demo `
  --endpoint https://bank.example/fints `
  --blz 12345678 `
  --user myuser `
  --product-id myproduct1234567890ABCDE `
  --set-default

--set-default makes this profile the default, so subsequent commands can omit --profile demo if you prefer. See profile init for the full option list.

Bootstrap and run a read-only command

Profiles need a one-time bootstrap before they can run operational commands. Bootstrap performs the initial dialog with the bank, learns which TAN modes and accounts are available, and persists the resulting state under an AES-256-GCM encrypted store.

By default gln prompts for the PIN interactively. For scripted callers, pipe the PIN on stdin with --pin-stdin instead.

.\build\Release\gln.exe --profile demo profile bootstrap
.\build\Release\gln.exe --profile demo accounts list

accounts list is a read-only call and a good first command: it confirms that the profile, PIN, and connectivity are all working before you try anything that moves money. The full per-command reference for accounts list, balances list, transactions list, and the rest lives at /docs/galanthus/reference/.

EBICS variant

For an EBICS profile, pass --backend ebics and the EBICS-specific identifiers. You can also pin the endpoint TLS public key with --ebics-tls-pinned-public-key; the value is either sha256//<base64> with a decodable 32-byte digest, or a path to a file containing the expected key.

.\build\Release\gln.exe `
  profile init corp `
  --backend ebics `
  --endpoint https://bank.example/ebicsweb `
  --host-id BANKHOST `
  --partner-id PARTNER `
  --user alice `
  --product-id myproduct1234567890ABCDE `
  --ebics-tls-pinned-public-key sha256//BASE64PIN

EBICS profiles require explicit bank-key verification before any operational use. When you run profile bootstrap for an EBICS profile, the command may exit with code 11: the profile staged the bank keys correctly, but you still need to compare them against the bank's out-of-band channel and confirm the match. The JSON result and the printed next_steps guidance describe what to do.

The supporting commands for that flow are:

• profile brief ini and profile brief hia to render the INI and HIA letters.
• profile bank-keys verify to record the verified --auth-digest and --enc-digest and unlock operational commands.

A typical EBICS bootstrap looks like this:

.\build\Release\gln.exe --profile corp profile bootstrap
.\build\Release\gln.exe --profile corp profile brief ini --raw > ini-brief.txt
.\build\Release\gln.exe --profile corp profile brief hia --raw > hia-brief.txt
.\build\Release\gln.exe --profile corp profile bank-keys show
.\build\Release\gln.exe --profile corp profile bank-keys verify `
  --auth-digest BASE64... `
  --enc-digest BASE64...

Once profile bank-keys verify succeeds, the EBICS profile behaves like the FinTS one for the commands EBICS supports. EBICS TLS pin and handshake failures surface as structured tls_error JSON, not as generic CLI errors.

TAN-gated commands

Write commands such as transfers sepa and standing-orders add are TAN-gated. They exit with code 10 and write a resume file. Continue the flow with tan resume, supplying the resume file the original command produced. tan resume works across process restarts and supports decoupled approval flows with --decoupled.

Exit codes

Every gln command uses the same exit-code contract:

• 0 - command completed successfully.
• 1 - command failed.
• 10 - TAN or continuation input is required.
• 11 - the command succeeded, but explicit follow-up is still required before the workflow is ready.
• 130 - interrupted.

Scripted callers should branch on exit code first and parse the JSON envelope second.

Where next

• CLI reference - per-command pages for every gln leaf command, with synopsis, options, requirements, exit codes, result keys, and examples.
• Library reference - C ABI for embedding galanthus into a host process, with per-topic guides covering clients, accounts and balances, transfers, direct debits, interruptions, payloads, and a per-function index.
• Getting started with the library - end-to-end starting point for callers using the C ABI from C, C++, Python, Rust, Go, C#, and other FFI hosts.