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

Supported Commands

The current implementation covers these command groups:

Auth

auth login
auth exchange
auth status
auth profile list
auth profile set-default
auth logout

Accounts

account create
account get
account delete
account unlink

Departments

department list
department get
department create
department update
department delete
department set-logo

Issuers

issuer list
issuer get
issuer create
issuer update
issuer delete

Users

user create

Clients

client list
client get
client create
client update
client delete

Payments

payment list
payment get
payment create
payment update
payment delete

Bank Accounts

bank-account list
bank-account get
bank-account create
bank-account update
bank-account delete

Products

product list
product get
product create
product update
product delete

Price Lists

price-list list
price-list get
price-list create
price-list update
price-list delete

Invoices

invoice list
invoice get
invoice create
invoice update
invoice delete
invoice send-email
invoice send-gov
invoice change-status
invoice cancel
invoice public-link
invoice add-attachment
invoice download-attachment
invoice download-attachments
invoice fiscal-print
invoice download

Recurrings

recurring list
recurring create
recurring update
recurring delete

Warehouses

warehouse list
warehouse get
warehouse create
warehouse update
warehouse delete

Warehouse Actions

warehouse-action list

Warehouse Documents

warehouse-document list
warehouse-document get
warehouse-document create
warehouse-document update
warehouse-document delete

Webhooks

webhook list
webhook get
webhook create
webhook update
webhook delete

Schema

schema list
schema <noun> <verb>

Maintenance

self update

Diagnostics

doctor run

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

Skills

The repo ships a generated, single-installable skill bundle at skills/fakturownia.

root install target: skills/fakturownia
generated bundle-local index: skills/fakturownia/references/skills-index.md
generated recipe index: skills/fakturownia/recipes/index.md
generated repo index for browsing: docs/skills.md
regenerate from code: just generate-skills

For GitHub-based skill installers, use repo sixers/fakturownia-cli with path skills/fakturownia.

Install

Install with the script

The public install path is:

curl -fsSL https://raw.githubusercontent.com/sixers/fakturownia-cli/master/install.sh | bash

The installer:

detects darwin or linux
detects amd64 or arm64
downloads the matching release archive
verifies it against checksums.txt
installs fakturownia into ~/.local/bin by default
prints a PATH hint if ~/.local/bin is not already on your PATH
uses GITHUB_TOKEN or GH_TOKEN when set
can fall back to gh release download when gh is installed and authenticated

Pin a specific version:

curl -fsSL https://raw.githubusercontent.com/sixers/fakturownia-cli/master/install.sh | VERSION=v0.1.1 bash

Install into a custom bin directory:

curl -fsSL https://raw.githubusercontent.com/sixers/fakturownia-cli/master/install.sh | BIN_DIR=/usr/local/bin bash

Run it from a local clone instead of piping from curl:

./install.sh
VERSION=v0.1.1 ./install.sh
BIN_DIR="$HOME/.local/bin" ./install.sh

The curl ... | bash path is the recommended install flow for public releases. Running ./install.sh from a local clone is still handy for development or if you want to inspect the installer before executing it.

Update an existing install

The recommended update path is the built-in self-update command:

fakturownia self update
fakturownia --version

Preview an update without modifying the binary:

fakturownia self update --dry-run --json

Pin a specific release:

fakturownia self update --version v0.2.0
fakturownia --version

If you are updating from an older release that does not include self update yet, rerun the installer script instead:

curl -fsSL https://raw.githubusercontent.com/sixers/fakturownia-cli/master/install.sh | bash

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 Example: v0.1.1
OS with darwin or linux
ARCH with amd64 or arm64

The manual install path is mostly useful for debugging or air-gapped installs. The script above is the recommended path for normal users.

Authentication

The CLI persists API tokens in the configured credential store and stores only profile metadata in the config file.

Save separate accounts under distinct profile names, list them, and choose the default without re-entering a token:

fakturownia auth login --prefix acme --api-token "$ACME_TOKEN" --profile acme
fakturownia auth login --prefix work --api-token "$WORK_TOKEN" --profile work
fakturownia auth profile list --json
fakturownia auth profile set-default --name work
fakturownia invoice list --profile acme --json

--profile selects a profile for one command; FAKTUROWNIA_PROFILE selects one for the current environment. auth profile set-default updates the stored fallback profile, and --dry-run --json previews that local change.

Supported config inputs:

FAKTUROWNIA_API_TOKEN
FAKTUROWNIA_URL
FAKTUROWNIA_PROFILE
FAKTUROWNIA_KEYRING_BACKEND
FAKTUROWNIA_KEYRING_PASSWORD

Example:

fakturownia auth login --prefix acme --api-token "$FAKTUROWNIA_API_TOKEN"
fakturownia auth exchange --login user@example.com --password secret --json
fakturownia auth status --json

For headless Linux, SSH, or container sessions without a working OS credential store, use the encrypted file backend:

export FAKTUROWNIA_KEYRING_BACKEND=file
export FAKTUROWNIA_KEYRING_PASSWORD='choose-a-strong-passphrase'
fakturownia auth login --prefix acme --api-token "$FAKTUROWNIA_API_TOKEN"

Use FAKTUROWNIA_KEYRING_BACKEND=auto to keep the default behavior, or FAKTUROWNIA_KEYRING_BACKEND=keychain as an alias for the native OS-backed store only.

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 and request catalogs for supported resources.

fakturownia schema auth exchange --json, fakturownia schema account get --json, fakturownia schema department list --json, fakturownia schema department get --json, fakturownia schema issuer list --json, fakturownia schema issuer get --json, fakturownia schema webhook list --json, fakturownia schema webhook get --json, fakturownia schema invoice list --json, fakturownia schema invoice get --json, fakturownia schema category list --json, fakturownia schema category get --json, fakturownia schema client list --json, fakturownia schema payment list --json, fakturownia schema payment get --json, fakturownia schema bank-account list --json, fakturownia schema bank-account get --json, fakturownia schema product list --json, fakturownia schema price-list list --json, fakturownia schema price-list get --json, fakturownia schema recurring list --json, fakturownia schema warehouse list --json, fakturownia schema warehouse get --json, fakturownia schema warehouse-action list --json, fakturownia schema warehouse-document list --json, and fakturownia schema warehouse-document get --json expose output.known_fields
fakturownia schema account create --json, fakturownia schema department create --json, fakturownia schema department update --json, fakturownia schema issuer create --json, fakturownia schema issuer update --json, fakturownia schema user create --json, fakturownia schema webhook create --json, fakturownia schema webhook update --json, fakturownia schema invoice create --json, fakturownia schema invoice update --json, fakturownia schema category create --json, fakturownia schema category update --json, fakturownia schema client create --json, fakturownia schema client update --json, fakturownia schema payment create --json, fakturownia schema payment update --json, fakturownia schema bank-account create --json, fakturownia schema bank-account update --json, fakturownia schema product create --json, fakturownia schema product update --json, fakturownia schema price-list create --json, fakturownia schema price-list update --json, fakturownia schema recurring create --json, fakturownia schema recurring update --json, fakturownia schema warehouse create --json, fakturownia schema warehouse update --json, and fakturownia schema warehouse-document create --json, and fakturownia schema warehouse-document update --json expose request_body_schema
known_fields and request body catalogs are curated from the upstream Fakturownia README; invoice schemas also cite KSeF.md for the KSeF-specific gov_* fields and payload notes, and invoice plus bank-account schemas cite API_RACHUNKI_BANKOWE.md for bank-account-specific payloads and invoice bank-account fields
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 schema auth exchange --json
fakturownia schema account create --json
fakturownia schema department create --json
fakturownia schema issuer create --json
fakturownia schema user create --json
fakturownia schema webhook create --json
fakturownia schema invoice create --json
fakturownia invoice get --id 123 --fields id,number,gov_status,gov_id --json
fakturownia schema recurring create --json
fakturownia schema category create --json
fakturownia schema client create --json
fakturownia schema payment create --json
fakturownia schema bank-account create --json
fakturownia schema product create --json
fakturownia schema price-list create --json
fakturownia schema warehouse create --json
fakturownia schema warehouse-action list --json
fakturownia schema warehouse-document create --json
fakturownia category list --fields name,description --json
fakturownia client list --fields name,email --json
fakturownia payment list --include invoices --fields name,price,paid --json
fakturownia bank-account get --id 100 --fields id,name,bank_account_number,bank_account_version_departments[].show_on_invoice --json
fakturownia product list --fields name,code,stock_level --json
fakturownia price-list get --id 8523 --fields id,name,price_list_positions[].price_gross --json
fakturownia warehouse list --fields name,description --json
fakturownia warehouse-action list --warehouse-document-id 15 --fields kind,product_id,quantity --json
fakturownia warehouse-document get --id 15 --fields id,kind,warehouse_actions[].quantity --json
fakturownia product create --input '{"name":"Widget","code":"W001","tax":"23"}' --json
fakturownia client create --input '{"name":"Acme","email":"billing@example.com"}' --json
fakturownia price-list create --input '{"name":"Dropshipper","currency":"PLN"}' --json
fakturownia warehouse create --input '{"name":"my_warehouse","kind":null,"description":null}' --json
fakturownia warehouse-document create --input '{"kind":"mm","warehouse_actions":[{"product_id":7,"quantity":2,"warehouse2_id":3}]}' --json
fakturownia account create --input '{"account":{"prefix":"acme"},"user":{"login":"owner","email":"owner@example.com","password":"secret"},"company":{"name":"Acme"}}' --json
fakturownia webhook create --input '{"kind":"invoice:create","url":"https://example.com/hook","active":true}' --json
fakturownia invoice list --include-positions --fields number,positions[].name --json
fakturownia invoice create --input '{"kind":"vat","client_id":1,"positions":[{"product_id":1,"quantity":2}]}' --dry-run --json
fakturownia invoice list --columns number,positions[].name

Examples

Auth

fakturownia auth login --prefix acme --api-token "$FAKTUROWNIA_API_TOKEN"
fakturownia auth exchange --login user@example.com --password secret --json
fakturownia auth status --json
fakturownia auth profile list --json
fakturownia auth profile set-default --name work
fakturownia auth logout --yes

Accounts

fakturownia account create --input '{"account":{"prefix":"acme"},"user":{"login":"owner","email":"owner@example.com","password":"secret"},"company":{"name":"Acme"}}' --json
fakturownia account get --json
fakturownia account unlink --prefix acme --prefix beta --json
fakturownia account delete --yes --dry-run --json

Departments

fakturownia department list --json
fakturownia department get --id 10 --json
fakturownia department create --input '{"name":"Sales","shortcut":"SALES","tax_no":"1234567890"}' --json
fakturownia department set-logo --id 10 --file ./logo.png --json

Issuers

fakturownia issuer list --json
fakturownia issuer get --id 3 --json
fakturownia issuer create --input '{"name":"HQ","tax_no":"1234567890"}' --json
fakturownia issuer delete --id 3 --yes --dry-run --json

Users

fakturownia user create --integration-token PARTNER_TOKEN --input '{"invite":true,"email":"user@example.com","role":"member"}' --json

Clients

fakturownia client list --json
fakturownia client get --external-id ext-123 --json
fakturownia client create --input '{"name":"Acme"}' --dry-run --json

Payments

fakturownia payment list --include invoices --json
fakturownia payment get --id 555 --json
fakturownia payment create --input '{"name":"Payment 001","price":100.05,"invoice_id":null,"paid":true,"kind":"api"}' --dry-run --json

Bank Accounts

fakturownia bank-account list --json
fakturownia bank-account get --id 100 --json
fakturownia bank-account create --input '{"name":"Rachunek główny PLN","bank_account_number":"PL61 1090 1014 0000 0712 1981 2874","bank_name":"Santander Bank Polska","bank_currency":"PLN","default":true}' --dry-run --json
fakturownia bank-account update --id 100 --input '{"bank_account_version_departments":[{"department_id":5,"show_on_invoice":true,"main_on_department":true}]}' --json

Products

fakturownia product list --json
fakturownia product get --id 100 --warehouse-id 7 --json
fakturownia product create --input '{"name":"Widget","code":"W001","price_net":"100","tax":"23"}' --dry-run --json
fakturownia product update --id 333 --input '{"price_gross":"102","tax":"23"}' --json

Price Lists

fakturownia price-list list --json
fakturownia price-list get --id 8523 --json
fakturownia price-list create --input '{"name":"Dropshipper","currency":"PLN","price_list_positions_attributes":{"0":{"priceable_id":97149307,"price_gross":"33.16","tax":"23"}}}' --dry-run --json
fakturownia price-list update --id 8523 --input '{"description":"updated"}' --json
fakturownia price-list delete --id 8523 --yes --json

Invoices

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 id,number,gov_status,gov_id,gov_error_messages[] --json
fakturownia invoice get --id 123 --fields id,number,bank_accounts[].bank_name,bank_accounts[].bank_account_number --json
fakturownia invoice get --id 123 --fields number,positions[].name --json
fakturownia invoice get --id 123 --include descriptions --fields descriptions[].content --json
fakturownia invoice get --id 123 --additional-field corrected_content_before --additional-field corrected_content_after --correction-positions full --json
fakturownia invoice create --input '{"kind":"vat","client_id":1,"positions":[{"product_id":1,"quantity":2}]}' --json
fakturownia invoice create --gov-save-and-send --input '{"kind":"vat","buyer_company":true,"seller_tax_no":"5252445767","seller_street":"ul. Przykładowa 10","seller_post_code":"00-001","seller_city":"Warszawa","buyer_name":"Klient ABC Sp. z o.o.","buyer_tax_no":"9876543210","positions":[{"name":"Usługa","quantity":1,"total_price_gross":1230,"tax":23}]}' --json
fakturownia invoice create --input '{"kind":"vat","buyer_name":"Klient ABC","bank_account_id":100,"buyer_mass_payment_code":"ABC-123","positions":[{"name":"Usługa","quantity":1,"total_price_gross":1230,"tax":23}]}' --json
fakturownia invoice update --id 123 --gov-save-and-send --input '{"buyer_name":"Nowa nazwa"}' --json
fakturownia invoice send-email --id 123 --email-to billing@example.com --email-pdf --json
fakturownia invoice send-gov --id 123 --json
fakturownia invoice public-link --id 123 --json
fakturownia invoice add-attachment --id 123 --file ./scan.pdf --json
fakturownia invoice download-attachment --id 123 --kind gov --dir ./attachments --json
fakturownia invoice download-attachment --id 123 --kind gov_upo --dir ./attachments --json
fakturownia invoice fiscal-print --invoice-id 123 --invoice-id 124 --json
fakturownia invoice download --id 123 --dir ./invoices --json

For KSeF flows, the API uses gov names:

invoice send-gov means “send the invoice to KSeF”
invoice download-attachment --kind gov downloads the KSeF XML
invoice download-attachment --kind gov_upo downloads the KSeF UPO XML
invoice schemas expose KSeF status through gov_* fields such as gov_status and gov_id

Recurrings

fakturownia recurring list --json
fakturownia recurring create --input '{"name":"Miesięczna","invoice_id":1,"every":"1m"}' --json
fakturownia recurring update --id 77 --input '{"next_invoice_date":"2026-05-01"}' --json

Warehouses

fakturownia warehouse list --json
fakturownia warehouse get --id 1 --json
fakturownia warehouse create --input '{"name":"my_warehouse","kind":null,"description":null}' --json
fakturownia warehouse update --id 1 --input '{"description":"new_description"}' --json
fakturownia warehouse delete --id 1 --yes --json

Warehouse Actions

fakturownia warehouse-action list --json
fakturownia warehouse-action list --warehouse-id 1 --kind mm --product-id 7 --json
fakturownia warehouse-action list --warehouse-document-id 15 --fields kind,product_id,quantity --json

Warehouse Documents

fakturownia warehouse-document list --json
fakturownia warehouse-document get --id 15 --json
fakturownia warehouse-document create --input '{"kind":"mm","warehouse_id":1,"warehouse_actions":[{"product_id":7,"quantity":2,"warehouse2_id":3}]}' --json
fakturownia warehouse-document update --id 15 --input '{"invoice_ids":[100,111]}' --json
fakturownia warehouse-document delete --id 15 --yes --json

Webhooks

fakturownia webhook list --json
fakturownia webhook get --id 7 --json
fakturownia webhook create --input '{"kind":"invoice:create","url":"https://example.com/hook","active":true}' --json
fakturownia webhook update --id 7 --input '{"active":false}' --json
fakturownia webhook delete --id 7 --yes --json

Schema

fakturownia schema list --json
fakturownia schema auth exchange --json
fakturownia schema account create --json
fakturownia schema department create --json
fakturownia schema issuer create --json
fakturownia schema user create --json
fakturownia schema webhook create --json
fakturownia schema invoice list --json
fakturownia schema invoice create --json
fakturownia schema recurring create --json
fakturownia schema client create --json
fakturownia schema price-list create --json
fakturownia schema warehouse create --json
fakturownia schema warehouse-action list --json
fakturownia schema warehouse-document create --json

Diagnostics

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
just secrets

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.

just secrets runs gitleaks with the repo's root gitleaks.toml. Install it first with go install github.com/zricethezav/gitleaks/v8@v8.30.1 if $(go env GOPATH)/bin/gitleaks is not already available.

Bun E2E

The repo also ships Bun-based real-account e2e coverage under e2e/.

Required environment:

FAKTUROWNIA_BIN defaults to /Users/mateusz/.local/bin/fakturownia
FAKTUROWNIA_PROFILE defaults to cli
MAILTEST_API_BASE_URL defaults to https://api.mailtestapi.com
MAILTEST_API_KEY must be set

Run the suite with Bun's native parallel file execution and global preload setup:

bun install
bun test

Or use the package script:

bun run test:e2e

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"

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
cmd		cmd
docs		docs
e2e		e2e
internal		internal
skills/fakturownia		skills/fakturownia
testdata/golden		testdata/golden
.gitignore		.gitignore
.goreleaser.yml		.goreleaser.yml
AGENTS.md		AGENTS.md
CONTRIBUTING.md		CONTRIBUTING.md
Justfile		Justfile
LICENSE		LICENSE
README.md		README.md
bun.lock		bun.lock
bunfig.toml		bunfig.toml
gitleaks.toml		gitleaks.toml
go.mod		go.mod
go.sum		go.sum
install.sh		install.sh
llms.txt		llms.txt
package.json		package.json
tsconfig.json		tsconfig.json

Latest commit

History

Folders and files

Repository files navigation

fakturownia

Supported Commands

Auth

Accounts

Departments

Issuers

Users

Categories

Clients

Payments

Bank Accounts

Products

Price Lists

Invoices

Recurrings

Warehouses

Warehouse Actions

Warehouse Documents

Webhooks

Schema

Maintenance

Diagnostics

Skills

Install

Install with the script

Update an existing install

Build from source

Install from a release

Authentication

Output Contract

Output Introspection

Examples

Auth

Accounts

Departments

Issuers

Users

Clients

Categories

Payments

Bank Accounts

Products

Price Lists

Invoices

Recurrings

Warehouses

Warehouse Actions

Warehouse Documents

Webhooks

Schema

Diagnostics

Exit Codes

Development

Bun E2E

Release

About

Topics

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages