Is the CLI open source?

Yes, MIT-licensed on GitHub. The service itself is not — the CLI is, and it is a single bash file you can read in full before running it.

Where does my token end up?

In .git/zuuna.conf with mode 600. The file lives inside .git/, so it cannot be committed, and the script itself contains no token.

Will the hook fail my commit if the server is unreachable?

No. The hook prints a warning to stderr and exits 0. The commit always goes through.

Does it work with GitLab or a self-hosted Gitea?

Yes. The CLI never talks to your git host, only to your Zuuna instance — it is a plain HTTP call. An instance unreachable from outside works too.

CLI: link commits to cards without an OAuth app

The Zuuna CLI is a single bash file with no dependencies beyond git and curl. It reports commits and branches to your board and cuts releases from git tags. It is open source under the MIT licence on GitHub — you can read all of it before running any of it.

Installed in 30 seconds

curl -o zuuna https://app.zuuna.de/zuuna.sh
chmod +x zuuna
./zuuna init https://app.zuuna.de zk_live_your_token

That writes .git/zuuna.conf with mode 600 and installs a post-commit hook. From then on every commit is reported automatically. The config lives inside .git/, so it cannot be committed by accident, and the script itself contains no token.

What counts as work — and what is only a reference

Mentioning a card key in a commit does not always mean you worked on that card. Sometimes you are just pointing at it. Treating both the same is how cards end up walking backwards across a board: a ticket cited in passing gets linked, moved, and reopened three days later by someone else's commit.

So position decides:

Where the key appears	Treated as	Effect
Commit subject line	Work	links and moves the card
Branch name	Work	links and moves the card
Body, behind `ref:` / `see:`	Reference only	links, does not move
Body, bare	Reference only	links, does not move

The commands

zuuna init <url> <token> [group-id] — write the config, install the hook. The group id is only needed for release and plan.
zuuna report — report the current commit and branch by hand. Useful after an --amend.
zuuna plan <name> [--tag v1.2.3] — create a planned release, optionally bound to the tag it will ship as.
zuuna release [--tag v1.2.3] — cut a release from a tag: collect the commits since the previous tag and send the manifest.

The hook never fails your commit

A broken token or an unreachable server must not stop you committing — the hook prints a warning to stderr and exits 0. It does print it, though: an earlier version swallowed everything with || true, which made a revoked token look exactly like success.

zuuna report does the opposite and exits non-zero on 401 or 403, because there a human is waiting for an answer.

Requirements

git and curl. For release and plan, also jq. The URL is a parameter and nothing is pinned to a particular host — the CLI never talks to your git host, only to your Zuuna instance. A Gitea reachable only inside your network works exactly the same.

The same thing step by step is in the tutorial Link commits to cards automatically. What lands on the card is git on the board; what it becomes over time is the Code Graph. The REST API covers everything the CLI does not.