---
name: "fakturownia-shared"
description: "Fakturownia CLI shared patterns: authentication prerequisites, global flags, output modes, `--fields` vs `--columns`, `--raw`, schema discovery, and binary maintenance. Use before any area-specific fakturownia task."
metadata:
  bundle: "fakturownia"
  category: "core"
  command_refs:
    - "self update"
  cli_help: "fakturownia --help"
  requires_bins:
    - "fakturownia"
  discovery_hint: "Start here for global behavior, then use `fakturownia schema list --json` to discover supported command groups."
---

> Auto-generated by `go run ./cmd/gen-skills`. Do not edit manually.

# Shared

## Use This Skill When

- The task is generally about the `fakturownia` CLI rather than one specific noun.
- You need auth setup, global flags, output behavior, or command discovery before calling API-area commands.
- You need to update the installed fakturownia binary from GitHub Releases.

## Covered Commands

- `fakturownia self update` — Replace the running binary with a GitHub Release build

## Notable Flags

- `--profile`: Select a named profile
- `--json` (default `false`): Alias for --output json
- `--output` (default `human`, enum `human`, `json`): Output format
- `--quiet` (default `false`): Emit bare values when exactly one field or column remains
- `--fields`: Project JSON envelope data fields using dot/bracket paths like number or positions[].name
- `--columns`: Select human table columns using dot/bracket paths like number or positions[].name
- `--raw` (default `false`): Emit the upstream JSON response body directly when supported
- `--dry-run` (default `false`): Accepted on read-only commands and reserved for future mutating request previews
- `--timeout-ms` (default `30000`): HTTP timeout in milliseconds
- `--max-retries` (default `2`): Maximum retry attempts for idempotent reads on network or 5xx failures
- `--non-interactive` (default `true`): Disable interactive behavior
- `--config`: Override the config file path
- `--json` aliases `--output json`; see this skill's output section for the shared behavior.

## Environment

- `FAKTUROWNIA_PROFILE`: Select a profile unless --profile is provided
- `FAKTUROWNIA_URL`: Override the base account URL from any profile
- `FAKTUROWNIA_API_TOKEN`: Override the API token from any profile

## Verify, Authenticate, And Smoke Test

- Confirm `fakturownia` is already available on `PATH` with `fakturownia --version` before attempting task-specific commands.
- Save credentials before API calls with `fakturownia auth login --prefix acme --api-token "$FAKTUROWNIA_API_TOKEN"`.
- If the environment already provides credentials, still run `fakturownia auth status --json` to confirm the resolved profile, prefix, and token source.
- Run `fakturownia account get --json` as the first authenticated smoke test before attempting task-specific writes or reads.

## Output and Discovery

- `--json` or `--output json` writes the structured envelope to stdout.
- `--fields` projects JSON envelope `data` fields.
- `--columns` only changes human table rendering.
- `--raw` emits the upstream JSON body when the command supports it.
- `--quiet` emits bare values when exactly one field or column remains.
- Use `fakturownia schema list --json` and `fakturownia schema <noun> <verb> --json` before constructing calls programmatically.

## Binary Maintenance

- Use `fakturownia self update` to replace the running binary with the latest GitHub Release build.
- Add `--version vX.Y.Z` to pin a specific release.
- Add `--dry-run --json` to preview the download URLs and target binary path without modifying the binary.

## Examples

```bash
fakturownia auth login --prefix acme --api-token $FAKTUROWNIA_API_TOKEN
fakturownia auth login --url https://acme.fakturownia.pl --api-token TOKEN --profile work --set-default
fakturownia auth exchange --login user@example.com --password secret --json
fakturownia auth exchange --login partner@example.com --password secret --integration-token PARTNER_TOKEN
fakturownia auth exchange --login user@example.com --password secret --save-as work --raw
fakturownia account get --json
fakturownia account get --integration-token PARTNER_TOKEN
fakturownia account get --raw
fakturownia department list --json
fakturownia department list --columns id,name,shortcut,tax_no
fakturownia department list --page 2 --per-page 25 --raw
fakturownia issuer list --json
fakturownia issuer list --columns id,name,tax_no
fakturownia issuer list --page 2 --per-page 25 --raw
fakturownia webhook list --json
fakturownia webhook list --columns id,kind,url,active
fakturownia webhook list --page 2 --per-page 25 --raw
fakturownia category list --json
fakturownia category list --columns id,name,description
fakturownia category list --page 2 --per-page 25 --raw
fakturownia schema list
fakturownia schema list --json
fakturownia self update
fakturownia self update --version v0.2.0
fakturownia self update --dry-run --json
fakturownia client list --json
fakturownia client list --name Acme --columns id,name,email,country
fakturownia client list --external-id ext-123 --json
fakturownia client list --page 2 --per-page 25 --raw
fakturownia payment list --json
fakturownia payment list --include invoices --json
fakturownia payment list --columns id,name,price,paid,kind
fakturownia payment list --page 2 --per-page 25 --raw
fakturownia bank-account list --json
fakturownia bank-account list --columns id,name,bank_account_number,bank_currency,default
fakturownia bank-account list --page 2 --per-page 25 --raw
fakturownia product list --json
fakturownia product list --date-from 2025-11-01 --json
fakturownia product list --warehouse-id 7 --columns id,name,code,stock_level
fakturownia product list --page 2 --per-page 25 --raw
fakturownia price-list list --json
fakturownia price-list list --columns id,name,currency,description
fakturownia price-list list --page 2 --per-page 25 --raw
fakturownia invoice list --json
fakturownia invoice list --period this_month --columns id,number,buyer_name,price_gross
fakturownia invoice list --include-positions --fields number,positions[].name --json
fakturownia invoice list --page 2 --per-page 25 --raw
fakturownia recurring list --json
fakturownia recurring list --columns id,name,every,next_invoice_date,send_email
fakturownia recurring list --raw
fakturownia warehouse list --json
fakturownia warehouse list --columns id,name,kind,description
fakturownia warehouse list --page 2 --per-page 25 --raw
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 --columns id,kind,product_id,quantity,warehouse_document_id
fakturownia warehouse-action list --page 2 --per-page 25 --raw
fakturownia warehouse-document list --json
fakturownia warehouse-document list --columns id,kind,number,client_name
fakturownia warehouse-document list --page 2 --per-page 25 --raw
```