Configuration · KSeF2 CLI dokumentacja

KSeF2 CLI can run without any local config file. This is the preferred mode for CI and shared machines. On a developer workstation, create named profiles so daily commands do not repeat --env, --nip, and authentication paths. The SDK can read the same profile file through client.authentication.with_profile().

Show the active config path

uv run ksef2 config path

bash

By default, the CLI uses:

~/.config/ksef2-cli/config.toml

text

Override the path with --config or KSEF2_CONFIG:

uv run ksef2 --config ./local.ksef2.toml config path

bash

Create a profile

uv run ksef2 profile create demo-client \
  --env test \
  --nip 5261040828 \
  --test-cert

bash

profile create selects the new profile by default. Use --no-activate when you only want to save it.

Token profiles store the environment variable name, not the token value:

uv run ksef2 profile create prod-client \
  --env production \
  --nip 5261040828 \
  --token-env KSEF2_PROD_TOKEN

bash

Certificate profiles store file paths and optional password environment variable names:

uv run ksef2 profile create demo-pem \
  --env demo \
  --nip 5261040828 \
  --cert company.pem \
  --key company.key \
  --key-password-env KSEF2_KEY_PASSWORD

uv run ksef2 profile create prod-p12 \
  --env production \
  --nip 5261040828 \
  --p12 signing-credentials.p12 \
  --p12-password-env KSEF2_P12_PASSWORD

bash

Select a profile

uv run ksef2 profile use demo-client
uv run ksef2 profile current
uv run ksef2 profile list

bash

Use a different profile for one command:

uv run ksef2 --profile prod-client --json \
  invoices metadata \
  --date-from 2026-01-01T00:00:00Z

bash

Or select one for the current shell:

export KSEF2_PROFILE=demo-client

bash

Selection order is:

--profile NAME on the current command.
KSEF2_PROFILE in the environment.
active_profile saved in the config file.

KSEF2_PROFILE affects runtime settings only. Use profile use NAME when you want to change the saved active profile.

Inspect local config

uv run ksef2 config show
uv run ksef2 profile show demo-client

bash

The config file stores profile names, environments, NIPs, credential file paths, polling settings, and secret environment variable names. It should not contain token or password values.

Example config:

active_profile = "demo-client"

[profiles.demo-client]
environment = "test"
nip = "5261040828"

[profiles.demo-client.auth]
type = "test_certificate"

[profiles.prod-client]
environment = "production"
nip = "5261040828"
poll_interval = 2.0
auth_timeout = 180.0

[profiles.prod-client.auth]
type = "token"
token_env = "KSEF2_PROD_TOKEN"
context_type = "nip"

[profiles.demo-pem]
environment = "demo"
nip = "5261040828"

[profiles.demo-pem.auth]
type = "xades_pem"
cert = "company.pem"
key = "company.key"
key_password_env = "KSEF2_KEY_PASSWORD"

[profiles.prod-p12]
environment = "production"
nip = "5261040828"

[profiles.prod-p12.auth]
type = "xades_p12"
p12 = "signing-credentials.p12"
p12_password_env = "KSEF2_P12_PASSWORD"

toml

Profile names, environment values, auth type strings, and field names match the SDK profile models.

Ignore local config once

uv run ksef2 --no-config --nip "$KSEF2_NIP" --token "$KSEF2_TOKEN" \
  invoices metadata --role seller --date-from 2026-01-01T00:00:00Z

bash

Output modes

The default output mode is plain text for humans:

uv run ksef2 invoices metadata --date-from 2026-01-01T00:00:00Z

bash

Use --json or --output json for scripts:

uv run ksef2 --json invoices metadata --date-from 2026-01-01T00:00:00Z

bash

Common environment variables

Variable	Purpose
`KSEF2_CONFIG`	Local config file path
`KSEF2_PROFILE`	Profile name for this shell/session
`KSEF2_NIP`	Taxpayer or context NIP override
`KSEF2_TOKEN`	KSeF token authentication secret override
`KSEF2_CONTEXT_TYPE`	Token-auth context type override
`KSEF2_TEST_CERT`	Enable SDK-generated TEST certificate authentication
`KSEF2_CERT`	PEM certificate path override
`KSEF2_KEY`	PEM private key path override
`KSEF2_KEY_PASSWORD`	PEM private key password override
`KSEF2_P12`	PKCS#12/PFX archive path override
`KSEF2_P12_PASSWORD`	PKCS#12/PFX password override