ksef2 CLI

Scriptable terminal workflows for the ksef2 Python SDK.

Use local profiles, environment-backed authentication, JSON output, and resumable workflow files to automate KSeF invoicing from shells, CI jobs, and operational scripts.

What is ksef2 CLI?

ksef2-cli exposes the ksef2 Python SDK as a command-line tool. It is designed for developers and operators who want to authenticate with KSeF, query invoice metadata, send invoices, download invoice XML, export packages, inspect sessions, and manage administrative resources without writing Python code.

The CLI avoids hidden state by default. Commands can read credentials from global options or environment variables, while local profiles store reusable non-secret defaults such as environment, NIP, auth method, certificate paths, and secret environment variable names.

This project is not published, endorsed, or supported by Poland's Ministry of Finance. Official KSeF documentation remains the source of truth for API behavior.

Install

uv tool install ksef2-cli

or:

pipx install ksef2-cli

The package exposes two equivalent executables:

ksef2 --help
ksef2-cli --help

Requires Python 3.12 or newer.

Authenticate

For repeated local work, create a profile once and let commands inherit its environment, NIP, and authentication settings:

ksef2 profile create test-company \
  --env test \
  --nip 5261040828 \
  --test-cert

ksef2 --profile test-company --json auth login

For CI and one-off scripts, pass global options before the command group:

ksef2 --nip "$KSEF2_NIP" --token "$KSEF2_TOKEN" --json \
  invoices metadata \
  --role seller \
  --date-from 2026-01-01T00:00:00Z \
  --all

Supported direct authentication methods:

• --token or KSEF2_TOKEN
• --test-cert for the TEST environment
• --cert and --key for PEM XAdES credentials
• --p12 for PKCS#12/PFX XAdES credentials

Send and download invoices

Send one XML invoice, wait for processing, save a UPO, and keep a receipt for later status checks:

ksef2 --profile test-company \
  invoices send invoice.xml \
  --wait \
  --upo-dir upos \
  --receipt invoice-receipt.json

Download the UPO later from the saved receipt:

ksef2 --profile test-company \
  invoices upo \
  --receipt invoice-receipt.json \
  --out invoice-upo.xml

Submit many XML files as one batch:

ksef2 --nip "$KSEF2_NIP" --token "$KSEF2_TOKEN" \
  invoices send invoice-1.xml invoice-2.xml \
  --mode batch \
  --wait \
  --upo-dir upos

Use --json before the command group when output is consumed by scripts.

Documentation

• Online docs: https://docs.stacking.me/ksef2/cli/intro/
• Installation: https://docs.stacking.me/ksef2/cli/getting-started/installation/
• Quickstart: https://docs.stacking.me/ksef2/cli/getting-started/quickstart/
• Command reference: https://docs.stacking.me/ksef2/cli/reference/commands/
• Source docs: docs
• SDK repository: stacking-hq/ksef2

Development

uv sync --all-groups
uv run ksef2 --help
uv run python -m coverage run -m pytest -q
uv run python scripts/validate_docs_frontmatter.py docs/

The CLI command domains live under src/ksef2_cli/commands/. Source documentation lives under docs/.

Contributing

Issues and pull requests are welcome. Before opening a PR, run the focused test or docs check that covers your change, and update source docs when command behavior changes.