fakturownia-cli

README

fakturownia

fakturownia is an agent-first Go CLI for the Fakturownia API.

It is designed for two audiences at once:

• agents need deterministic behavior, structured output, and stable recovery paths
• humans still need clear help text, sensible defaults, and a clean local workflow

Status

The current implementation focuses on the first high-value read flows:

• auth login
• auth status
• auth logout
• invoice list
• invoice get
• invoice download
• schema list
• schema <noun> <verb>
• doctor run

The architecture is intentionally structured so more API resources can be added without changing the CLI contract.

Install

Build from source

This is the simplest copy-paste path during early development:

brew install go just
git clone https://github.com/sixers/fakturownia-cli.git
cd fakturownia-cli
mkdir -p "$HOME/.local/bin"
go build -o "$HOME/.local/bin/fakturownia" ./cmd/fakturownia
case "$(basename "$SHELL")" in
  zsh) rc_file="$HOME/.zshrc" ;;
  bash) rc_file="$HOME/.bashrc" ;;
  *) rc_file="$HOME/.profile" ;;
esac
grep -qxF 'export PATH="$HOME/.local/bin:$PATH"' "$rc_file" || echo 'export PATH="$HOME/.local/bin:$PATH"' >> "$rc_file"
export PATH="$HOME/.local/bin:$PATH"
fakturownia version

Install from a release

mkdir -p "$HOME/.local/bin"
tmpdir="$(mktemp -d)"
cd "$tmpdir"
curl -fsSLO "https://github.com/sixers/fakturownia-cli/releases/download/VERSION/fakturownia_VERSION_OS_ARCH.tar.gz"
tar -xzf "fakturownia_VERSION_OS_ARCH.tar.gz"
install -m 0755 fakturownia "$HOME/.local/bin/fakturownia"
rm -rf "$tmpdir"
case "$(basename "$SHELL")" in
  zsh) rc_file="$HOME/.zshrc" ;;
  bash) rc_file="$HOME/.bashrc" ;;
  *) rc_file="$HOME/.profile" ;;
esac
grep -qxF 'export PATH="$HOME/.local/bin:$PATH"' "$rc_file" || echo 'export PATH="$HOME/.local/bin:$PATH"' >> "$rc_file"
export PATH="$HOME/.local/bin:$PATH"
fakturownia version

Replace:

• VERSION with a release tag such as v0.1.0
• OS with darwin or linux
• ARCH with amd64 or arm64

Authentication

The CLI persists API tokens in the OS keychain and stores only profile metadata in the config file.

Supported config inputs:

• FAKTUROWNIA_API_TOKEN
• FAKTUROWNIA_URL
• FAKTUROWNIA_PROFILE

Example:

fakturownia auth login --prefix acme --api-token "$FAKTUROWNIA_API_TOKEN"
fakturownia auth status --json

Output Contract

Every command supports --json or --output json.

• JSON is written to stdout
• diagnostics and warnings are written to stderr
• --raw emits the upstream JSON response body directly when supported
• --quiet emits bare values when exactly one field or column remains

Envelope shape:

{
  "schema_version": "fakturownia-cli/v1alpha1",
  "status": "success",
  "data": {},
  "errors": [],
  "warnings": [],
  "meta": {
    "command": "invoice list",
    "profile": "default",
    "duration_ms": 12
  }
}

Output Introspection

schema describes both the command contract and the README-backed output catalog for invoice resources.

• fakturownia schema invoice list --json exposes output.known_fields
• known_fields is curated from the upstream Fakturownia README
• nested paths use dot_bracket syntax such as positions[].name
• the catalog is intentionally not exhaustive; syntactically valid paths outside the catalog are still allowed and produce warnings instead of hard failures

Examples:

fakturownia schema invoice list --json
fakturownia invoice list --include-positions --fields number,positions[].name --json
fakturownia invoice list --columns number,positions[].name

Examples

fakturownia invoice list --json
fakturownia invoice list --period this_month --columns id,number,price_gross
fakturownia invoice get --id 123 --fields id,number,status --json
fakturownia invoice get --id 123 --fields number,positions[].name --json
fakturownia invoice download --id 123 --dir ./invoices --json
fakturownia schema invoice list --json
fakturownia doctor run --json

Exit Codes

• 0 success
• 2 usage or validation error
• 3 not found
• 4 authentication or permission failure
• 5 conflict
• 6 network or timeout failure
• 7 reserved for rate limiting or retry budget exhaustion
• 8 remote API rejected request
• 9 internal CLI failure

Development

just test
just lint
just build

Golden tests cover help and schema output for the public CLI contract. Run just schema-help when you want to refresh just that contract-focused test target.

Release

Releases are created by pushing a semver tag. The GitHub Actions release workflow then runs GoReleaser and publishes the archives, checksums, and SBOMs automatically.

Prerequisites:

• push the release commit to master
• have gh authenticated for the sixers/fakturownia-cli repo
• use a clean worktree before tagging

Dry run locally:

brew install goreleaser
goreleaser release --snapshot --clean

Create a real release:

cd /Users/mateusz/Projects/Personal/fakturownia-cli

just test
just lint
just build

git status --short
git push origin master

version="v0.1.0"
git tag "$version"
git push origin "$version"

Watch the release workflow:

gh run list --repo sixers/fakturownia-cli --workflow release --limit 5
run_id="$(gh run list --repo sixers/fakturownia-cli --workflow release --limit 1 --json databaseId --jq '.[0].databaseId')"
gh run watch "$run_id" --repo sixers/fakturownia-cli
gh release view "$version" --repo sixers/fakturownia-cli

If you need to replace a failed tag before publishing a corrected release:

version="v0.1.0"
git tag -d "$version"
git push origin ":refs/tags/$version"
git tag "$version"
git push origin "$version"