@faktoora/cli

v0.1.3

Published

2 months ago

Command-line interface for the faktoora public API

0High
0Medium
0Low

faktoora-master

@faktoora/cli

The official command-line interface for the faktoora e-invoicing platform.

faktoora is a cloud platform for electronic invoicing and smart workflows — XRechnung, ZUGFeRD, EN 16931 and Peppol — built for German and European compliance requirements. This package gives you full access to the faktoora public REST API from your terminal, scripts and CI/CD pipelines: create and dispatch outgoing invoices, ingest and validate incoming e-invoices, manage customers, products, webhooks and more.

Website: faktoora.com
Documentation: docs.faktoora.com
API base URL: https://api.faktoora.com
npm: @faktoora/cli

Requirements

Node.js >= 24
A faktoora API key — sign up at faktoora.com and generate a key from your account settings.

Installation

npm install -g @faktoora/cli

Configuration

Set your API key before running any command:

faktoora config set api-key YOUR_API_KEY

View the current configuration:

faktoora config get

The API key may also be supplied via the FAKTOORA_API_KEY environment variable, which takes precedence over the stored configuration and is the recommended approach for CI/CD environments.

Output

By default every command prints a human-readable table (empty columns are hidden, nested objects are summarised, pagination metadata is shown below the table).

Pass --json to get raw JSON instead (2-space indent), suitable for piping to jq or other tools:

faktoora invoice list                          # human-readable table
faktoora invoice list --json                   # raw JSON
faktoora invoice list --json | jq '.data[0].faktooraId'
faktoora customer get cust-uuid --json | jq '.email'

Commands

`faktoora invoice`

| Command | Description | |---------|-------------| | invoice list | List invoices with pagination and filters | | invoice create -f <path> | Create an invoice from a JSON file | | invoice status <faktooraId> | Get processing status | | invoice download <faktooraId> --format <fmt> | Download an invoice as PDF or XML | | invoice delete <faktooraId> | Delete an invoice (requires invoiceDeleteMode feature flag) |

# List
faktoora invoice list
faktoora invoice list --page 2 --per-page 50
faktoora invoice list --keyword INV-001
faktoora invoice list --sort issueDate --order desc   # sort: faktooraId|invoiceNumber|issueDate|createdAt
faktoora invoice list --invoice-number INV-001
faktoora invoice list --start-issue-date 20260101 --end-issue-date 20260331
faktoora invoice list --start-date 20260101 --end-date 20260331

# Create  (-f is short for --file)
faktoora invoice create -f invoice.json

# Create and wait until generation is complete
faktoora invoice create -f invoice.json --wait
faktoora invoice create -f invoice.json --wait --wait-timeout 120000

# Status
faktoora invoice status fak-001

# Download
faktoora invoice download fak-001 --format pdf
faktoora invoice download fak-001 --format xml
faktoora invoice download fak-001 --format pdf --output /tmp/invoice.pdf

# Delete (requires invoiceDeleteMode feature to be enabled on your account)
faktoora invoice delete fak-001

Invoice creation is asynchronous. The API returns a faktooraId immediately. Use --wait to poll automatically, or run invoice status manually to check progress.

invoice list returns { data, page, perPage, totalItems }. Each item includes: faktooraId, invoiceNumber, issueDate, createdAt, amount, currency, status, invoiceTypeCode, usedProfile, detailsPage.

invoice.json example:

{
  "invoices": [
    {
      "format": "xrechnung",
      "schema": "CII",
      "invoiceTypeCode": "380",
      "invoiceNumber": "INV-2026-001",
      "issueDate": "20260301",
      "currency": "EUR",
      "buyer": {
        "name": "Acme GmbH",
        "street": "Hauptstraße 1",
        "postcode": "10115",
        "city": "Berlin",
        "country": "DE",
        "email": "[email protected]",
        "vatId": "DE123456789"
      },
      "buyerReference": {
        "buyerReferenceId": "YOUR-LEITWEG-ID"
      },
      "invoiceItems": [
        {
          "id": "1",
          "product": {
            "name": "Consulting",
            "quantity": "8",
            "unitCode": "HUR",
            "price": "150.00",
            "taxes": [{ "typeCode": "VAT", "categoryCode": "S", "rate": "19" }]
          }
        }
      ]
    }
  ]
}

Supported formats: simple, zugferd2_extended, xrechnung Common invoiceTypeCode values: "380" invoice · "381" credit note · "384" corrected invoice · "326" partial invoice

For the full schema and all supported fields, see the API documentation.

`faktoora import incoming`

Upload and manage incoming e-invoices (XRechnung / ZUGFeRD).

| Command | Description | |---------|-------------| | import incoming -f <path> | Upload an incoming invoice file (.xml or .pdf) | | import incoming list | List all incoming imports | | import incoming status <importId> | Get processing status (validation, visualization, overall) | | import incoming validation <importId> | Get XML validation result (accepted/rejected) | | import incoming summary <importId> | Get seller, amount, tax, dates and invoice number | | import incoming content <importId> | Get complete merged content (seller + buyer + items + taxes + payment) | | import incoming seller <importId> | Get seller information | | import incoming buyer <importId> | Get buyer information | | import incoming delivery <importId> | Get delivery address | | import incoming lineitems <importId> | Get line items | | import incoming taxes <importId> | Get VAT breakdown | | import incoming paymentterms <importId> | Get payment terms | | import incoming paymentmeans <importId> | Get payment means | | import incoming attachments <importId> | List integrated file attachments | | import incoming attachment <importId> <attachmentId> | Get attachment metadata | | import incoming source <importId> | Download the source invoice file | | import incoming content-pdf <importId> | Download the invoice content as PDF | | import incoming validation-pdf <importId> | Download the validation report as PDF | | import incoming attachment-file <importId> <attachmentId> | Download an attachment file |

# Upload
faktoora import incoming -f invoice.xml
faktoora import incoming -f invoice.pdf

# List
faktoora import incoming list
faktoora import incoming list --keyword INV --page 2
faktoora import incoming list --sort issueDate --order desc   # sort: importId|invoiceNumber|issueDate|createdAt
faktoora import incoming list --start-issue-date 20260101 --end-issue-date 20260331
faktoora import incoming list --start-date 20260101 --end-date 20260331

# Status & validation
faktoora import incoming status imp-001
faktoora import incoming validation imp-001

# Content
faktoora import incoming summary imp-001
faktoora import incoming content imp-001
faktoora import incoming seller imp-001
faktoora import incoming buyer imp-001
faktoora import incoming delivery imp-001
faktoora import incoming lineitems imp-001
faktoora import incoming taxes imp-001
faktoora import incoming paymentterms imp-001
faktoora import incoming paymentmeans imp-001

# Attachments
faktoora import incoming attachments imp-001
faktoora import incoming attachment imp-001 att-uuid

# Download files
faktoora import incoming source imp-001
faktoora import incoming source imp-001 --output /tmp/source.xml
faktoora import incoming content-pdf imp-001
faktoora import incoming validation-pdf imp-001
faktoora import incoming attachment-file imp-001 att-uuid

import incoming list returns { data, page, perPage, totalItems }. Each item includes: importId, invoiceNumber, issueDate, createdAt, amount, invoiceCurrencyCode, status, usedProfile, invoiceTypeCode, detailsPage.

`faktoora import outgoing`

Upload and manage outgoing e-invoices imported from file (XRechnung / ZUGFeRD).

| Command | Description | |---------|-------------| | import outgoing -f <path> | Upload an outgoing invoice file (.xml or .pdf) | | import outgoing list | List all outgoing imports | | import outgoing status <faktooraId> | Get processing status (validation, visualization, overall) | | import outgoing validation <faktooraId> | Get XML validation result (accepted/rejected) | | import outgoing summary <faktooraId> | Get seller, amount, tax, dates and invoice number | | import outgoing content <faktooraId> | Get complete merged content (seller + buyer + items + taxes + payment) | | import outgoing seller <faktooraId> | Get seller information | | import outgoing buyer <faktooraId> | Get buyer information | | import outgoing delivery <faktooraId> | Get delivery address | | import outgoing lineitems <faktooraId> | Get line items | | import outgoing taxes <faktooraId> | Get VAT breakdown | | import outgoing paymentterms <faktooraId> | Get payment terms | | import outgoing paymentmeans <faktooraId> | Get payment means | | import outgoing attachments <faktooraId> | List integrated file attachments | | import outgoing attachment <faktooraId> <attachmentId> | Get attachment metadata | | import outgoing source <faktooraId> | Download the source invoice file | | import outgoing content-pdf <faktooraId> | Download the invoice content as PDF | | import outgoing validation-pdf <faktooraId> | Download the validation report as PDF | | import outgoing attachment-file <faktooraId> <attachmentId> | Download an attachment file |

# Upload
faktoora import outgoing -f invoice.xml

# List
faktoora import outgoing list
faktoora import outgoing list --keyword INV
faktoora import outgoing list --start-issue-date 20260101 --end-issue-date 20260331
faktoora import outgoing list --start-date 20260101 --end-date 20260331

# Status & validation
faktoora import outgoing status fak-001
faktoora import outgoing validation fak-001

# Content
faktoora import outgoing summary fak-001
faktoora import outgoing content fak-001
faktoora import outgoing seller fak-001
faktoora import outgoing buyer fak-001
faktoora import outgoing delivery fak-001
faktoora import outgoing lineitems fak-001
faktoora import outgoing taxes fak-001
faktoora import outgoing paymentterms fak-001
faktoora import outgoing paymentmeans fak-001

# Attachments
faktoora import outgoing attachments fak-001
faktoora import outgoing attachment fak-001 att-uuid

# Download files
faktoora import outgoing source fak-001
faktoora import outgoing content-pdf fak-001
faktoora import outgoing validation-pdf fak-001
faktoora import outgoing attachment-file fak-001 att-uuid

import outgoing list returns { data, page, perPage, totalItems }. Each item includes: faktooraId, invoiceNumber, issueDate, createdAt, amount, currency, status, invoiceTypeCode, usedProfile, detailsPage.

`faktoora customer`

| Command | Description | |---------|-------------| | customer list | List customers with pagination and filters | | customer get <id> | Get a single customer by UUID | | customer create -f <path> | Create a customer from a JSON file | | customer update <id> -f <path> | Update customer fields from a JSON file | | customer delete <id> | Delete a customer | | customer generate-number | Generate the next sequential customer number | | customer verify-number <number> | Check if a customer number is available | | customer import --file-id <uuid> | Import customers from a previously uploaded CSV file |

faktoora customer list
faktoora customer list --category vip
faktoora customer list --keywords "Acme,GmbH"   # comma-separated, partial match

faktoora customer get cust-uuid

faktoora customer create -f customer.json
faktoora customer update cust-uuid -f updates.json
faktoora customer delete cust-uuid

faktoora customer generate-number
faktoora customer verify-number KD-042

faktoora customer import --file-id upload-uuid

customer.json example:

{
  "isCompany": true,
  "name": "Acme GmbH",
  "address": "Hauptstr. 1",
  "postcode": "10115",
  "city": "Berlin",
  "country": "DE",
  "email": "[email protected]"
}

`faktoora product`

| Command | Description | |---------|-------------| | product list | List products with pagination and filters | | product get <id> | Get a single product by UUID | | product create -f <path> | Create a product from a JSON file (required: name, unit, tax) | | product update <id> -f <path> | Update product fields from a JSON file | | product delete <id> | Delete a product | | product verify-code <code> | Check if a product code is available | | product generate | AI-generate product suggestions (requires PRODUCT_GENERATION_CHATGPT feature) |

faktoora product list
faktoora product list --keyword widget
faktoora product list --code WDG-001
faktoora product list --sort price --order asc   # sort: code|name|unit|tax|price|createdAt

faktoora product get prod-uuid

faktoora product create -f product.json
faktoora product update prod-uuid -f updates.json
faktoora product delete prod-uuid

faktoora product verify-code WDG-001

# AI-generate product suggestions
faktoora product generate --industry "Software" --customer-type "B2B" --count 5
faktoora product generate --industry "Retail" --customer-type "B2C" --count 10 --additional-info "focus on eco products"
faktoora product generate --industry "Retail" --customer-type "B2C" --count 5 --prev-products-file prev.json

product.json example:

{
  "name": "Widget",
  "unit": "piece",
  "tax": 19,
  "price": 9.99
}

`faktoora productbundle`

Manage product bundles (requires PRODUCT_BUNDLE feature).

| Command | Description | |---------|-------------| | productbundle list | List product bundles with pagination and filters | | productbundle get <id> | Get a single product bundle by UUID | | productbundle create -f <path> | Create a product bundle from a JSON file (required: name, unit, tax) | | productbundle update <id> -f <path> | Update product bundle fields from a JSON file | | productbundle delete <id> | Delete a product bundle |

faktoora productbundle list
faktoora productbundle list --keyword "bundle"
faktoora productbundle list --sort name --order asc

faktoora productbundle get bundle-uuid

faktoora productbundle create -f bundle.json
faktoora productbundle update bundle-uuid -f updates.json
faktoora productbundle delete bundle-uuid

bundle.json example:

{
  "name": "Starter Pack",
  "unit": "package",
  "tax": 19,
  "price": 49.99,
  "productsOnProductBundles": [
    { "product": "product-uuid-1", "amount": "2" },
    { "product": "product-uuid-2", "amount": "1" }
  ]
}

`faktoora webhook`

| Command | Description | |---------|-------------| | webhook list | List all webhook subscriptions | | webhook create --action <action> --target <url> | Subscribe to a webhook event | | webhook update <id> --action <action> --target <url> | Update a webhook subscription | | webhook delete <id> | Delete a webhook subscription |

faktoora webhook list
faktoora webhook list --page 1 --per-page 20
faktoora webhook list --sort createdAt --order desc   # sort: action|target|createdAt

faktoora webhook create --action invoiceCreate --target https://your.app/hook
faktoora webhook update wh-uuid --action invoiceSent --target https://your.app/hook
faktoora webhook delete wh-uuid

Available actions:

| Action | Triggers when | |--------|--------------| | invoiceCreate | An invoice is created | | invoiceSent | An invoice is sent | | invoiceOverdue | An invoice becomes overdue | | invoiceIncomingCreate | An incoming invoice is imported | | invoiceIncomingSent | An incoming invoice is sent | | offerCreate / offerSent | An offer is created / sent | | letterCreate / letterSent | A letter is created / sent | | reminderCreate / reminderSent | A reminder is created / sent | | orderConfirmationCreate / orderConfirmationSent | An order confirmation is created / sent | | customerCreate | A customer is created | | productCreate | A product is created |

`faktoora config`

| Command | Description | |---------|-------------| | config set api-key <key> | Save API key | | config set api-url <url> | Set a custom API base URL | | config get | Show current configuration (key is masked) |

faktoora config set api-key abc123
faktoora config set api-url https://api.faktoora.com
faktoora config get

Resources

Product overview — faktoora.com
API & developer documentation — docs.faktoora.com
npm package — @faktoora/cli

Support

For account-related questions, billing or general enquiries, please get in touch via faktoora.com. For technical questions about the API or this CLI, refer to docs.faktoora.com.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@faktoora/cli

Requirements

Installation

Configuration

Output

Commands

faktoora invoice

faktoora import incoming

faktoora import outgoing

faktoora customer

faktoora product

faktoora productbundle

faktoora webhook

faktoora config

Resources

Support

License

`faktoora invoice`

`faktoora import incoming`

`faktoora import outgoing`

`faktoora customer`

`faktoora product`

`faktoora productbundle`

`faktoora webhook`

`faktoora config`