sevdesk-cli

TypeScript CLI for selected sevdesk API endpoints.

Scope v0.1

Currently implemented:

• GET /CheckAccount
• GET /CheckAccount/{checkAccountId}/getBalanceAtDate
• GET /Invoice
• GET /CheckAccountTransaction
• GET /CheckAccountTransaction/{checkAccountTransactionId}
• GET /Report/invoicelist

Installation

Global via npm

npm i -g @calumba/sevdesk-cli

After that, the sevdesk command is available globally.

Without a global install

npm exec --package @calumba/sevdesk-cli sevdesk -- --help

Local development

cd /Users/pascal/projects/sevdesk-cli
npm install
npm run build
npm link

Quickstart

1. Set an API token

export SEVDESK_API_TOKEN="<your-token>"

Or use the user config at ~/.config/sevdesk-cli/config.json.

Important: the default config always lives at ~/.config/sevdesk-cli/config.json. You can point to another file with --config <path>. If that file is inside the current project, the CLI prints an explicit warning.

2. List accounts

sevdesk check-accounts list
sevdesk check-accounts list --json

3. List invoices

sevdesk invoices list --status 200 --start-date 2026-01-01 --end-date 2026-03-31
sevdesk --profile kkr invoices list --count-all --limit 1 --created-after 2026-03-01 --created-before 2026-03-31

Important:

• --start-date / --end-date filter by invoiceDate
• --created-after / --created-before filter by the technical create timestamp
• date values accept YYYY-MM-DD, ISO datetimes, or Unix seconds

4. List transactions

sevdesk transactions list --check-account-id 12 --only-credit
sevdesk transactions get 4711 --json

5. Save the invoice list report as PDF

sevdesk reports invoice-list --output ./invoice-list.pdf --invoice-type RE

Notes:

• PDF files are only written with --output <path> or --stdout
• existing files are only overwritten with --force

Output modes

• Default: human-readable
• --json: structured JSON output
• --plain: stable plain-text output for pipes and scripts

Configuration

Precedence:

1. Flags (--profile, --base-url, --config)
2. Environment (SEVDESK_API_TOKEN, SEVDESK_PROFILE, SEVDESK_BASE_URL, SEVDESK_API_TOKEN_FILE)
3. Config file (default: ~/.config/sevdesk-cli/config.json, optional via --config <path>)

Details: docs/configuration.md

Repository documentation

• docs/README.md
• docs/cli-spec.md
• docs/configuration.md
• docs/reference/authentication.md
• docs/reference/check-accounts.md
• docs/reference/invoices.md
• docs/reference/transactions.md
• docs/reference/report-invoice-list.md
• docs/api/README.md
• .agents/skills/create-cli/SKILL.md

Development

npm run test
npm run build
npm run dev -- invoices list --json

Maintainer release flow

Prerequisites:

• gh auth login
• npm login
• a clean local main that matches origin/main

Checks:

npm run release:doctor

Dry run without Git / GitHub / npm mutations:

npm run release -- --dry-run patch

Prepare a release (validate/finalize changelog, bump version, run checks, create release commit and git tag):

npm run release:prepare -- patch
# or: minor | major | prepatch | preminor | premajor | prerelease | 0.2.0

Publish a release (push + GitHub Release + npm publish):

npm run release:publish

Everything in one step:

npm run release -- patch

What the script does:

1. validates Git, GitHub CLI, and npm auth prerequisites
2. checks that CHANGELOG.md contains entries under ## Unreleased
3. moves those entries into a new ## X.Y.Z section
4. bumps package.json and package-lock.json
5. runs typecheck, tests, build, and smoke checks
6. creates chore(release): vX.Y.Z and tags vX.Y.Z
7. pushes main and the tag
8. creates a GitHub Release from the matching CHANGELOG.md section and verifies that the release actually exists
9. publishes the package to npm

Note: the manual workflow publishes without GitHub Actions provenance.

For future releases, the repository also includes .github/workflows/release.yml, which is designed to publish tagged releases with npm provenance via GitHub Actions once the repository is public.

After a successful release, install the package like this:

npm i -g @calumba/sevdesk-cli
sevdesk --help

--dry-run shows the same flow but skips all mutating steps such as version bumps, commits, tags, pushes, GitHub release creation, and npm publish.

Skills

• global runtime skill: ~/.agents/skills/sevdesk-cli/SKILL.md
• project-local runtime skill: /Users/pascal/projects/sevdesk-cli/.agents/skills/sevdesk-cli/SKILL.md
• project-local CLI design skill: /Users/pascal/projects/sevdesk-cli/.agents/skills/create-cli/SKILL.md
• project-local commit skill: /Users/pascal/projects/sevdesk-cli/.agents/skills/commit/SKILL.md
• project-local extension workflow skill: /Users/pascal/projects/sevdesk-cli/.agents/skills/extend-sevdesk-cli/SKILL.md
• compatibility mirrors:
  • /Users/pascal/projects/sevdesk-cli/.claude/skills/create-cli/SKILL.md
  • /Users/pascal/projects/sevdesk-cli/.codex/skills/create-cli/SKILL.md
  • /Users/pascal/projects/sevdesk-cli/.claude/skills/commit/SKILL.md
  • /Users/pascal/projects/sevdesk-cli/.codex/skills/commit/SKILL.md
  • /Users/pascal/projects/sevdesk-cli/.claude/skills/extend-sevdesk-cli/SKILL.md
  • /Users/pascal/projects/sevdesk-cli/.codex/skills/extend-sevdesk-cli/SKILL.md

When extending the CLI, agents should load the local extend-sevdesk-cli skill first. It points to create-cli, the repo docs, and the commit rules. Before committing, load the local commit skill; commits should remain atomic.