@genz-its/sevdesk-cli
v0.1.8
Published
Unofficial command-line interface for the sevdesk API.
Maintainers
Readme
@genz-its/sevdesk-cli
Unofficial command-line interface for the sevdesk API.[^1]
Features
- 🧾 Vouchers: Create vouchers from receipt files (PDF, image, XML), list, book, reset and enshrine them, and download their attached documents.
- 💳 Transactions: List and filter bank transactions, for example the ones that are not booked yet.
- 🏦 Check accounts: List accounts, query balances, and create clearing or file import accounts.
- 🧭 Receipt guidance: Find bookable accounts and their allowed tax rules.
- 📄 Documents: List invoices, credit notes and orders, and download them as PDF.
- 📤 Exports: Export accounting data in the DATEV format, or contacts, invoices, transactions and vouchers as CSV.
- 🤖 Automation-friendly:
--jsonoutput on every command, non-interactive mode, and stable exit codes.
Requirements
- Node.js 22 or later.
- A sevdesk account on bookkeeping system version 2.0 (sevdesk-Update 2.0).
Installation
Install the CLI globally:
npm install -g @genz-its/sevdesk-cliAlternatively, run it without installation:
npx @genz-its/sevdesk-cli <command>Quickstart
# Log in with your sevdesk API token
sevdesk login
# Verify your setup
sevdesk doctor
# Find a booking account and its allowed tax rules
sevdesk guidance:accounts --expense
# Create an open voucher from a receipt file
sevdesk vouchers:create --file receipt.pdf --supplier-name "ACME GmbH" --amount 119 --tax-rule 9 --account-datev 26
# List unbooked bank transactions
sevdesk transactions:list --unbooked
# Book the voucher against a bank transaction
sevdesk vouchers:book --id 123 --amount 119 --check-account 1 --transaction 456Authentication
Run sevdesk login to validate and store your API token. You can find the token in your sevdesk account under Settings > User > API token.
The token is resolved in the following order:
- The
SEVDESK_TOKENenvironment variable. - The config file written by
sevdesk login(~/.config/sevdesk/config.json, respectingXDG_CONFIG_HOME).
In CI or other automated environments, prefer the SEVDESK_TOKEN environment variable over storing the token on disk.
Scripting
The CLI is designed to be scriptable:
--json: Every command supports the--jsonflag to output machine-readable JSON.- Non-interactive mode: When the CLI runs without a TTY or with the
CIenvironment variable set, it never prompts. Missing required values cause an error and exit code1instead. --yes: Commands that ask for confirmation accept--yesto skip the prompt.- Exit codes:
0on success,1on any failure.
# Example: print the IDs of all unbooked transactions
sevdesk transactions:list --unbooked --json | jq -r '.[].id'Commands
loginlogoutdoctoraccounts-datev:getaccounts-datev:listaccounts:balanceaccounts:create-clearingaccounts:create-file-importaccounts:getaccounts:listcontacts:add-addresscontacts:add-emailcontacts:add-phonecontacts:createcontacts:deletecontacts:delete-addresscontacts:getcontacts:listcontacts:updatecontacts:update-addresscredit-notes:getcredit-notes:listcredit-notes:pdfexport:contactsexport:datevexport:invoicesexport:transactionsexport:vouchersguidance:accountsinvoices:getinvoices:listinvoices:pdforders:getorders:listorders:pdfparts:getparts:listtags:createtags:deletetags:listtransactions:createtransactions:gettransactions:listvouchers:bookvouchers:createvouchers:documentvouchers:enshrinevouchers:getvouchers:listvouchers:openvouchers:positionsvouchers:reset-to-draftvouchers:reset-to-openvouchers:update
login
Log in with your sevdesk API token. The token is validated against the sevdesk API and stored in the config file. Accounts on bookkeeping system version 1.0 are rejected.
sevdesk login [options]Options:
--token: The sevdesk API token. If omitted, you will be prompted.
logout
Log out by removing the stored API token.
sevdesk logoutdoctor
Check the CLI setup and the connection to the sevdesk API.
sevdesk doctor [options]Options:
--json: Output in JSON format.
accounts-datev:get
Show a single booking account (AccountDatev), including hidden accounts that accounts-datev:list does not return. Backed by an undocumented sevdesk endpoint that may change without notice.
sevdesk accounts-datev:get [options]Options:
--id: The booking account ID. If omitted, you will be prompted.--json: Output in JSON format.
accounts-datev:list
List booking accounts (AccountDatev). Covers only accounts visible in the sevdesk account picker; hidden accounts (for example some tax accounts) are reachable via accounts-datev:get. Backed by an undocumented sevdesk endpoint that may change without notice.
sevdesk accounts-datev:list [options]Options:
--number: Only show accounts with this account number. Filtered client-side across all visible accounts.--name-like: Only show accounts whose name contains this text. Filtered client-side across all visible accounts.--limit: Maximum number of accounts to return. Defaults to all of them.--offset: Number of accounts to skip before filtering.--json: Output in JSON format.
accounts:balance
Show the balance of a check account at a given date. The balance is the sum of all transactions known to sevdesk, which is not necessarily the real bank balance.
sevdesk accounts:balance [options]Options:
--id: The check account ID. If omitted, you will be prompted.--date: The date to calculate the balance for (YYYY-MM-DD). Defaults to today.--json: Output in JSON format.
accounts:create-clearing
Create a clearing check account.
sevdesk accounts:create-clearing [options]Options:
--name: The name of the check account. If omitted, you will be prompted.--accounting-number: The booking account number of the check account.--json: Output in JSON format.
accounts:create-file-import
Create a check account that imports its transactions from files.
sevdesk accounts:create-file-import [options]Options:
--name: The name of the check account. If omitted, you will be prompted.--import-type: The file format used to import transactions. Supported values areCSVandMT940. Defaults toCSV.--accounting-number: The booking account number of the check account.--iban: The IBAN of the check account.--json: Output in JSON format.
accounts:get
Show a single check account.
sevdesk accounts:get [options]Options:
--id: The check account ID. If omitted, you will be prompted.--json: Output in JSON format.
accounts:list
List your check accounts.
sevdesk accounts:list [options]Options:
--limit: The maximum number of check accounts to return. Defaults to all of them.--offset: The number of check accounts to skip.--json: Output in JSON format.
contacts:add-address
Add an address to a contact.
sevdesk contacts:add-address [options]Options:
--contact: The contact ID. If omitted, you will be prompted.--street: Street and house number.--zip: Zip code.--city: City name.--country: ID of the country as a StaticCountry ID, for example1for Germany. There is no lookup endpoint in this CLI, but an existing address of a contact reveals the IDs of other countries. If omitted, you will be prompted.--category: ID of the address category. The sevdesk API does not document the IDs, they are listed by aGETto/Category?objectType=ContactAddressand an existing address of a contact reveals the ones in use. If omitted, you will be prompted.--json: Output in JSON format.
contacts:add-email
Add an e-mail address to a contact.
sevdesk contacts:add-email [options]Options:
--contact: The contact ID. If omitted, you will be prompted.--email: The e-mail address. If omitted, you will be prompted.--key: ID of the communication way key:1private,2work,7newsletter,8invoicing. Defaults to2.--main: Mark the e-mail address as the main one of the contact. Defaults tofalse.--json: Output in JSON format.
contacts:add-phone
Add a phone number to a contact.
sevdesk contacts:add-phone [options]Options:
--contact: The contact ID. If omitted, you will be prompted.--phone: The phone number. If omitted, you will be prompted.--key: ID of the communication way key:1private,2work,3fax,4mobile. Defaults to2.--main: Mark the phone number as the main one of the contact. Defaults tofalse.--json: Output in JSON format.
contacts:create
Create a contact. Use --name for organizations and --surename together with --familyname for persons.
sevdesk contacts:create [options]Options:
--name: Name of the organization. Not to be used for persons. If both--nameand--familynameare omitted, you will be prompted for the organization name.--surename: First name of the person. Not to be used for organizations.--familyname: Last name of the person. Not to be used for organizations.--category: ID of the contact category:2supplier,3customer,4partner. Defaults to3.--customer-number: Customer number of the contact.--description: Description of the contact.--vat-number: VAT number of the contact.--tax-number: Tax number of the contact.--json: Output in JSON format.
contacts:delete
Delete a contact.
sevdesk contacts:delete [options]Options:
--id: The contact ID. If omitted, you will be prompted.--yes: Skip the confirmation prompt. Defaults tofalse.--json: Output in JSON format.
contacts:delete-address
Delete an address of a contact.
sevdesk contacts:delete-address [options]Options:
--id: The contact address ID, as shown bycontacts:get. If omitted, you will be prompted.--yes: Skip the confirmation prompt. Defaults tofalse.--json: Output in JSON format.
contacts:get
Show a single contact with its addresses and communication ways.
sevdesk contacts:get [options]Options:
--id: The contact ID. If omitted, you will be prompted.--json: Output in JSON format. Prints an object with the keyscontact,addressesandcommunicationWays.
contacts:list
List contacts.
sevdesk contacts:list [options]Options:
--name: Filter by organization, first or last name.--customer-number: Filter by customer number.--depth: Contact depth:0returns only organizations,1organizations and persons. Defaults to0.--category: ID of the contact category to filter by:2supplier,3customer,4partner.--limit: Maximum number of contacts to return. Defaults to all of them.--offset: Number of contacts to skip.--json: Output in JSON format.
contacts:update
Update a contact. Only the given fields are changed.
sevdesk contacts:update [options]Options:
--id: The contact ID. If omitted, you will be prompted.--name: Name of the organization. Not to be used for persons.--surename: First name of the person. Not to be used for organizations.--familyname: Last name of the person. Not to be used for organizations.--category: ID of the contact category:2supplier,3customer,4partner.--customer-number: Customer number of the contact.--description: Description of the contact.--vat-number: VAT number of the contact.--tax-number: Tax number of the contact.--json: Output in JSON format.
contacts:update-address
Update an address of a contact. Only the given fields are changed.
sevdesk contacts:update-address [options]Options:
--id: The contact address ID, as shown bycontacts:get. If omitted, you will be prompted.--street: Street and house number.--zip: Zip code.--city: City name.--country: ID of the country as a StaticCountry ID, for example1for Germany.--category: ID of the address category.--json: Output in JSON format.
credit-notes:get
Show a single credit note.
sevdesk credit-notes:get [options]Options:
--id: ID of the credit note. If omitted, you will be prompted.--json: Output in JSON format.
credit-notes:list
List credit notes.
sevdesk credit-notes:list [options]Options:
--status: Filter by status:100draft,200open,750partially paid,1000paid.--credit-note-number: Filter by credit note number.--start-date: Only credit notes on or after this date asdd.mm.yyyyor Unix timestamp.--end-date: Only credit notes on or before this date asdd.mm.yyyyor Unix timestamp.--contact: ID of the contact whose credit notes to list.--limit: Maximum number of credit notes to return. Defaults to all of them.--offset: Number of credit notes to skip.--json: Output in JSON format.
credit-notes:pdf
Download the PDF of a credit note.
sevdesk credit-notes:pdf [options]Options:
--id: ID of the credit note. If omitted, you will be prompted.--output: Path to write the PDF to. Defaults to the file name reported by the API.--prevent-send-by: Do not mark the credit note as sent by download. Defaults tofalse.--json: Output in JSON format.
export:contacts
Export contacts as a CSV file.
sevdesk export:contacts [options]Options:
--output: Path to write the CSV file to. Defaults to the filename of the export.--limit: The maximum number of contacts to export.--json: Output in JSON format.
export:datev
Export accounting data in the DATEV format as a ZIP archive. The export runs as a background job that the CLI waits for.
sevdesk export:datev [options]Options:
--start-date: Start of the export period asdd.mm.yyyyor Unix timestamp. If omitted, you will be prompted.--end-date: End of the export period asdd.mm.yyyyor Unix timestamp. If omitted, you will be prompted.--format: The DATEV export format. Supported values arecsvandxml. Defaults tocsv.--scope: The models to include as a string of letters:E(earnings),X(expenditure),T(transactions),C(cash register) andD(assets). XML exports support onlyEandX. Defaults toEXTCD.--output: Path to write the ZIP archive to. Defaults to the filename of the export.--timeout: Maximum number of seconds to wait for the export job. Defaults to300.--json: Output in JSON format.
export:invoices
Export invoices as a CSV file.
sevdesk export:invoices [options]Options:
--output: Path to write the CSV file to. Defaults to the filename of the export.--limit: The maximum number of invoices to export.--start-date: Only export invoices on or after this date (ISO 8601).--end-date: Only export invoices on or before this date (ISO 8601).--json: Output in JSON format.
export:transactions
Export transactions as a CSV file.
sevdesk export:transactions [options]Options:
--output: Path to write the CSV file to. Defaults to the filename of the export.--limit: The maximum number of transactions to export.--start-date: Only export transactions on or after this date (ISO 8601).--end-date: Only export transactions on or before this date (ISO 8601).--json: Output in JSON format.
export:vouchers
Export vouchers as a CSV file.
sevdesk export:vouchers [options]Options:
--output: Path to write the CSV file to. Defaults to the filename of the export.--limit: The maximum number of vouchers to export.--start-date: Only export vouchers on or after this date (ISO 8601).--end-date: Only export vouchers on or before this date (ISO 8601).--json: Output in JSON format.
guidance:accounts
List bookable accounts and their allowed tax rules. Covers only the ReceiptGuidance subset of VAT-relevant accounts — use accounts-datev:list for all booking accounts. The first matching filter wins: --account-number, --tax-rule, --revenue, --expense. Without a filter, all accounts are listed.
sevdesk guidance:accounts [options]Options:
--account-number: Only show the account with this datev account number.--tax-rule: Tax rule name, for exampleUSTPFL_UMS_EINN.--revenue: Only show accounts that can be used for revenue. Defaults tofalse.--expense: Only show accounts that can be used for expenses. Defaults tofalse.--json: Output in JSON format.
invoices:get
Show a single invoice.
sevdesk invoices:get [options]Options:
--id: ID of the invoice. If omitted, you will be prompted.--json: Output in JSON format.
invoices:list
List invoices.
sevdesk invoices:list [options]Options:
--status: Filter by status:50deactivated recurring,100draft,200open,750partially paid,1000paid.--invoice-number: Filter by invoice number.--start-date: Only invoices on or after this date asdd.mm.yyyyor Unix timestamp.--end-date: Only invoices on or before this date asdd.mm.yyyyor Unix timestamp.--contact: ID of the contact whose invoices to list.--limit: Maximum number of invoices to return. Defaults to all of them.--offset: Number of invoices to skip.--json: Output in JSON format.
invoices:pdf
Download the PDF of an invoice.
sevdesk invoices:pdf [options]Options:
--id: ID of the invoice. If omitted, you will be prompted.--output: Path to write the PDF to. Defaults to the file name reported by the API.--prevent-send-by: Do not mark the invoice as sent by download. Defaults tofalse.--json: Output in JSON format.
orders:get
Show a single order.
sevdesk orders:get [options]Options:
--id: ID of the order. If omitted, you will be prompted.--json: Output in JSON format.
orders:list
List orders.
sevdesk orders:list [options]Options:
--status: Filter by status:100draft,200delivered,300rejected,500accepted,750partially calculated,1000calculated.--order-number: Filter by order number.--start-date: Only orders on or after this date asdd.mm.yyyyor Unix timestamp.--end-date: Only orders on or before this date asdd.mm.yyyyor Unix timestamp.--contact: ID of the contact whose orders to list.--limit: Maximum number of orders to return. Defaults to all of them.--offset: Number of orders to skip.--json: Output in JSON format.
orders:pdf
Download the PDF of an order.
sevdesk orders:pdf [options]Options:
--id: ID of the order. If omitted, you will be prompted.--output: Path to write the PDF to. Defaults to the file name reported by the API.--prevent-send-by: Do not mark the order as sent by download. Defaults tofalse.--json: Output in JSON format.
parts:get
Show a single part.
sevdesk parts:get [options]Options:
--id: The part ID. If omitted, you will be prompted.--json: Output in JSON format.
parts:list
List parts.
sevdesk parts:list [options]Options:
--name: Filter by part name.--part-number: Filter by part number.--limit: Maximum number of parts to return. Defaults to all of them.--offset: Number of parts to skip.--json: Output in JSON format.
tags:create
Create a tag and attach it to a document.
sevdesk tags:create [options]Options:
--name: Name of the tag. If omitted, you will be prompted.--object-type: Type of the document to tag:Invoice,Voucher,OrderorCreditNote. If omitted, you will be prompted.--object-id: ID of the document to tag. If omitted, you will be prompted.--json: Output in JSON format.
tags:delete
Delete a tag.
sevdesk tags:delete [options]Options:
--id: The tag ID. If omitted, you will be prompted.--yes: Skip the confirmation prompt. Defaults tofalse.--json: Output in JSON format.
tags:list
List tags.
sevdesk tags:list [options]Options:
--limit: Maximum number of tags to return. Defaults to all of them.--offset: Number of tags to skip.--json: Output in JSON format.
transactions:create
Create a transaction. Only use this on file import (online) check accounts.
sevdesk transactions:create [options]Options:
--check-account: The ID of the check account the transaction belongs to. If omitted, you will be prompted.--amount: The amount of the transaction. Negative for expenses. If omitted, you will be prompted.--payee: The name of the payee or payer. If omitted, you will be prompted.--value-date: The date the transaction was booked (ISO 8601). Defaults to now.--entry-date: The date the transaction was imported (ISO 8601).--purpose: The payment purpose of the transaction.--status: The status of the transaction:100created,200linked,300private,400booked. Defaults to100.--json: Output in JSON format.
transactions:get
Show a single transaction.
sevdesk transactions:get [options]Options:
--id: The transaction ID. If omitted, you will be prompted.--json: Output in JSON format.
transactions:list
List transactions of your check accounts.
sevdesk transactions:list [options]Options:
--check-account: Only show transactions of this check account ID.--unbooked: Only show transactions with status100(created). Filtered client-side because the sevdesk API ignores itsisBooked=falsefilter. Defaults tofalse.--start-date: Only show transactions on or after this date (ISO 8601).--end-date: Only show transactions on or before this date (ISO 8601).--payee: Only show transactions with this payee or payer name.--purpose: Only show transactions with this payment purpose.--limit: The maximum number of transactions to return. Defaults to all of them.--offset: The number of transactions to skip.--json: Output in JSON format.
vouchers:book
Book a payment on a voucher. For online check accounts (bank, PayPal, file import), pass the existing bank transaction via --transaction. For clearing accounts and cash registers, omit --transaction and sevdesk creates the transaction automatically.
sevdesk vouchers:book [options]Options:
--id: ID of the voucher. If omitted, you will be prompted.--amount: Amount to book. Can also be a partial amount. Pass it as a positive number — the sign is derived from the voucher, which the API requires to be negative for expense vouchers. If omitted, you will be prompted.--date: Booking date as ISO 8601. Defaults to now.--type: Type of the booking. Supported values areFULL_PAYMENT,N(partial),CB(cash discount),O(other),OF(reminder charges) andMTC(monetary traffic costs). Defaults toFULL_PAYMENT.--check-account: ID of the check account. If omitted, you will be prompted.--transaction: ID of the bank transaction to link. Required for online check accounts, omit for clearing accounts.--create-feed: Create a feed entry for the booking.--yes: Skip the confirmation prompt. Defaults tofalse.--json: Output in JSON format.
vouchers:create
Create a voucher from a receipt file. The file is uploaded and attached to the voucher, which is created with a single position.
sevdesk vouchers:create [options]Options:
--file: Path to the receipt file to attach, for example a PDF, an image or an XML invoice. If omitted, you will be prompted.--status: Status of the created voucher. Supported values aredraftandopen. Defaults toopen.--credit-debit:Cfor expense (credit),Dfor income (debit) vouchers. Defaults toC.--tax-rule: ID of the tax rule, for example9for deductible input tax expenses. If omitted, you will be prompted.--account-datev: ID of the booking account (AccountDatev). Find it withguidance:accounts. If omitted, you will be prompted.--amount: Amount of the voucher position. If omitted, you will be prompted.--net: Treat the amount as net instead of gross. Defaults tofalse.--tax-rate: Tax rate of the voucher position in percent. Defaults to19.--voucher-date: Date asdd.mm.yyyyor Unix timestamp.--pay-date: Date asdd.mm.yyyyor Unix timestamp.--delivery-date: Start of the service period (Leistungszeitraum), or the single service date, asdd.mm.yyyyor Unix timestamp.--delivery-date-until: End of the service period asdd.mm.yyyyor Unix timestamp. Requires--delivery-date.--supplier-id: ID of the supplier contact.--supplier-name: Name of the supplier, used when no supplier ID is given.--description: The voucher number.--comment: Comment for the voucher position.--json: Output in JSON format.
vouchers:document
Download the document attached to a voucher.
sevdesk vouchers:document [options]Options:
--id: ID of the voucher. If omitted, you will be prompted.--output: Path to write the document to. Defaults to the file name reported by the API. Existing files are never overwritten.--json: Output in JSON format.
vouchers:enshrine
Enshrine a voucher so that it can no longer be changed. This cannot be undone.
sevdesk vouchers:enshrine [options]Options:
--id: ID of the voucher. If omitted, you will be prompted.--yes: Skip the confirmation prompt. Defaults tofalse.--json: Output in JSON format.
vouchers:get
Show a single voucher.
sevdesk vouchers:get [options]Options:
--id: ID of the voucher. If omitted, you will be prompted.--json: Output in JSON format.
vouchers:list
List vouchers.
sevdesk vouchers:list [options]Options:
--status: Filter by status:50draft,100open,150transferred,750partially paid,1000paid.--credit-debit: Filter byCfor expense orDfor income vouchers.--description-like: Filter by voucher number, matching partially.--start-date: Only vouchers on or after this date asdd.mm.yyyyor Unix timestamp.--end-date: Only vouchers on or before this date asdd.mm.yyyyor Unix timestamp.--contact: ID of the contact whose vouchers to list.--limit: Maximum number of vouchers to return. Defaults to all of them.--offset: Number of vouchers to skip.--json: Output in JSON format.
vouchers:open
Move a draft voucher to the open status. Everything else, including the attached document and the positions, stays unchanged. Exits with an error and changes nothing unless the voucher is a draft that is not enshrined.
sevdesk vouchers:open [options]Options:
--id: ID of the voucher. If omitted, you will be prompted.--json: Output in JSON format.
vouchers:positions
List voucher positions.
sevdesk vouchers:positions [options]Options:
--voucher: ID of the voucher whose positions to list.--limit: Maximum number of positions to return. Defaults to all of them.--offset: Number of positions to skip.--json: Output in JSON format.
vouchers:reset-to-draft
Reset a voucher to the draft status. This unlinks existing payments.
sevdesk vouchers:reset-to-draft [options]Options:
--id: ID of the voucher. If omitted, you will be prompted.--yes: Skip the confirmation prompt. Defaults tofalse.--json: Output in JSON format.
vouchers:reset-to-open
Reset a voucher to the open status. This unlinks existing payments.
sevdesk vouchers:reset-to-open [options]Options:
--id: ID of the voucher. If omitted, you will be prompted.--yes: Skip the confirmation prompt. Defaults tofalse.--json: Output in JSON format.
vouchers:update
Update the service period (Leistungszeitraum) of a voucher. Options you leave out keep their stored value.
sevdesk vouchers:update [options]Options:
--id: ID of the voucher. If omitted, you will be prompted.--delivery-date: Start of the service period, or the single service date, asdd.mm.yyyyor Unix timestamp.--delivery-date-until: End of the service period asdd.mm.yyyyor Unix timestamp.--clear-delivery-date-until: Remove the end of the service period, leaving a single service date. Cannot be combined with--delivery-date-until. Defaults tofalse.--json: Output in JSON format.
License
See LICENSE.
[^1]: This project is not affiliated with, endorsed by, sponsored by, or approved by sevDesk GmbH or any of their affiliates or subsidiaries.
