CLI

@faktoora/cli is a command-line interface for the faktoora public REST API. It lets developers manage invoices, customers, products, webhooks and e-invoice imports directly from the terminal or CI/CD pipelines — without needing an AI client.

Use the CLI when you need a scriptable, human-readable interface. For AI-driven workflows, see the MCP Server.

Requirements

Node.js >= 24
A faktoora API key

Installation

Install globally via npm:

npm install -g @faktoora/cli

Verify the installation:

faktoora --help

Configuration

Set your API key before running any command:

# Save to ~/.faktoora/config (persists across sessions)
faktoora config set api-key YOUR_API_KEY

# Or use an environment variable
export FAKTOORA_API_KEY=YOUR_API_KEY

By default the CLI calls https://app.faktoora.com. To target a different environment:

faktoora config set api-url https://YOUR_ENV.faktoora.com

# Or via environment variable
export FAKTOORA_API_URL=https://YOUR_ENV.faktoora.com

View the current configuration (API key is masked):

faktoora config get

Output

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

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

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

Invoice

Manage outgoing invoices.

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 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
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
faktoora invoice create -f invoice.json

# Create and poll 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
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 status returns the full status object including jobStatus, invoiceStatus, authority[], and delivery[].

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": "billing@acme.de",
        "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

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 (`validationStatus`, `visualizationStatus`, `overallStatus`)
`import incoming validation <importId>`	Get XML validation result (`accepted`/`rejected`)
`import incoming validation-pdf <importId>`	Download validation report as PDF
`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 content-pdf <importId>`	Download content as PDF
`import incoming source <importId>`	Download source invoice file (XML preferred)
`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 attachment-file <importId> <attachmentId>`	Download 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
faktoora import incoming validation-pdf imp-001
faktoora import incoming validation-pdf imp-001 --output /tmp/validation.pdf

# Content
faktoora import incoming summary imp-001
faktoora import incoming content imp-001
faktoora import incoming content-pdf imp-001 --output /tmp/invoice.pdf
faktoora import incoming source imp-001 --output /tmp/invoice.xml
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
faktoora import incoming attachment-file imp-001 att-uuid --output /tmp/attachment.pdf

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

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 (`validationStatus`, `visualizationStatus`, `overallStatus`)
`import outgoing validation <faktooraId>`	Get XML validation result (`accepted`/`rejected`)
`import outgoing validation-pdf <faktooraId>`	Download validation report as PDF
`import outgoing summary <faktooraId>`	Get seller, amount, outstanding balance, dates and invoice number
`import outgoing content <faktooraId>`	Get complete merged content (seller + buyer + items + taxes + payment)
`import outgoing content-pdf <faktooraId>`	Download content as PDF
`import outgoing source <faktooraId>`	Download source invoice file (XML preferred)
`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 attachment-file <faktooraId> <attachmentId>`	Download 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
faktoora import outgoing validation-pdf fak-001 --output /tmp/validation.pdf

# Content
faktoora import outgoing summary fak-001
faktoora import outgoing content fak-001
faktoora import outgoing content-pdf fak-001 --output /tmp/invoice.pdf
faktoora import outgoing source fak-001 --output /tmp/invoice.xml
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
faktoora import outgoing attachment-file fak-001 att-uuid --output /tmp/attachment.pdf

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

Customer

Manage customers.

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": "billing@acme.de"
}

Product

Manage products and services.

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
}

Product bundle

Manage product bundles (requires PRODUCT_BUNDLE feature).

Command	Description
`productbundle list`	List product bundles
`productbundle get <id>`	Get a single product bundle by UUID
`productbundle create -f <path>`	Create a product bundle from a JSON file
`productbundle update <id> -f <path>`	Update a product bundle from a JSON file
`productbundle delete <id>`	Delete a product bundle

faktoora productbundle list
faktoora productbundle list --keyword starter

faktoora productbundle get bundle-uuid

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

Webhook

Manage webhook subscriptions.

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

Config

Manage CLI configuration stored in ~/.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://staging.faktoora.com
faktoora config get

Requirements​

Installation​

Configuration​

Output​

Commands​

Invoice​

Import incoming​

Import outgoing​

Customer​

Product​

Product bundle​

Webhook​

Config​