Can I use Invoice Ninja as a CLI?

Yes. KosmoKrator exposes a Invoice Ninja CLI through kosmo integrations:call and the provider shortcut command. Commands can return JSON for scripts, CI, and coding agents.

Can I expose Invoice Ninja through MCP?

Yes. The KosmoKrator MCP gateway can expose selected Invoice Ninja tools to clients such as Claude Code, Cursor, Codex, and other MCP-compatible tools.

Where are Invoice Ninja credentials stored?

Invoice Ninja credentials are configured in KosmoKrator's local integration settings and reused by CLI, Lua, and MCP gateway surfaces.

Can I deny write access for Invoice Ninja MCP tools?

Yes. Start the gateway with --write=deny for read-only clients, or use ask/allow only for trusted workspaces.

accounting

Invoice Ninja CLI for AI Agents

Use the Invoice Ninja CLI from KosmoKrator to call Invoice Ninja tools headlessly, return JSON, inspect schemas, and automate workflows from coding agents, scripts, and CI.

8 functions 6 read 2 write API token auth

Submit Invoice Ninja feedback View package source

Invoice Ninja CLI Setup

Invoice Ninja can be configured headlessly with `kosmokrator integrations:configure invoiceninja`.

# Install KosmoKrator first if it is not available on PATH.
curl -fsSL https://raw.githubusercontent.com/OpenCompanyApp/kosmokrator/main/install.sh | bash

# Configure and verify this integration.
kosmokrator integrations:configure invoiceninja --set api_token="$INVOICENINJA_API_TOKEN" --enable --read allow --write ask --json
kosmokrator integrations:doctor invoiceninja --json
kosmokrator integrations:status --json

Credentials

Authentication type: API token api_token. Configure credentials once, then use the same stored profile from scripts, coding CLIs, Lua code mode, and the MCP gateway.

Key	Env var	Type	Required	Label
`api_token`	`INVOICENINJA_API_TOKEN`	Secret `secret`	yes	API Token
`url`	`INVOICENINJA_URL`	URL `url`	no	Instance URL

Call Invoice Ninja Headlessly

Use the generic call form when another coding CLI or script needs a stable universal interface.

kosmo integrations:call invoiceninja.invoiceninja_list_invoices '{
  "per_page": 1,
  "page": 1,
  "client_id": "example_client_id",
  "status": "example_status",
  "number": "example_number",
  "sort": "example_sort"
}' --json

Use the provider shortcut form for shorter human-facing commands.

kosmo integrations:invoiceninja invoiceninja_list_invoices '{
  "per_page": 1,
  "page": 1,
  "client_id": "example_client_id",
  "status": "example_status",
  "number": "example_number",
  "sort": "example_sort"
}' --json

Agent Discovery Commands

These commands return structured output for coding agents that need to inspect capabilities before choosing a function.

kosmo integrations:docs invoiceninja --json
kosmo integrations:docs invoiceninja.invoiceninja_list_invoices --json
kosmo integrations:schema invoiceninja.invoiceninja_list_invoices --json
kosmo integrations:search "Invoice Ninja" --json
kosmo integrations:list --json

All CLI Functions

Every function below can be called headlessly. The generic form is stable across all integrations; the provider shortcut is shorter but specific to Invoice Ninja.

`invoiceninja.invoiceninja_list_invoices`

Read read

List invoices from Invoice Ninja. Supports filtering by client, status, and date range with pagination.

Parameters: per_page, page, client_id, status, number, sort

Generic CLI call

kosmo integrations:call invoiceninja.invoiceninja_list_invoices '{"per_page":1,"page":1,"client_id":"example_client_id","status":"example_status","number":"example_number","sort":"example_sort"}' --json

Provider shortcut

kosmo integrations:invoiceninja invoiceninja_list_invoices '{"per_page":1,"page":1,"client_id":"example_client_id","status":"example_status","number":"example_number","sort":"example_sort"}' --json

`invoiceninja.invoiceninja_get_invoice`

Read read

Get a single invoice from Invoice Ninja by ID. Returns full invoice details including line items, client info, and payment status.

Parameters: id

Generic CLI call

kosmo integrations:call invoiceninja.invoiceninja_get_invoice '{"id":"example_id"}' --json

Provider shortcut

kosmo integrations:invoiceninja invoiceninja_get_invoice '{"id":"example_id"}' --json

`invoiceninja.invoiceninja_create_invoice`

Write write

Create a new invoice in Invoice Ninja. Requires a client_id and at least one line item. Supports custom due dates, partial deposits, and notes.

Parameters: client_id, line_items, due_date, date, public_notes, private_notes, discount, is_amount_discount, tax_name1, tax_rate1, partial, partial_due_date

Generic CLI call

kosmo integrations:call invoiceninja.invoiceninja_create_invoice '{"client_id":"example_client_id","line_items":"example_line_items","due_date":"example_due_date","date":"example_date","public_notes":"example_public_notes","private_notes":"example_private_notes","discount":1,"is_amount_discount":true}' --json

Provider shortcut

kosmo integrations:invoiceninja invoiceninja_create_invoice '{"client_id":"example_client_id","line_items":"example_line_items","due_date":"example_due_date","date":"example_date","public_notes":"example_public_notes","private_notes":"example_private_notes","discount":1,"is_amount_discount":true}' --json

`invoiceninja.invoiceninja_list_clients`

Read read

List clients from Invoice Ninja. Supports filtering by name, email, and ID number with pagination.

Parameters: per_page, page, search, id_number, sort

Generic CLI call

kosmo integrations:call invoiceninja.invoiceninja_list_clients '{"per_page":1,"page":1,"search":"example_search","id_number":"example_id_number","sort":"example_sort"}' --json

Provider shortcut

kosmo integrations:invoiceninja invoiceninja_list_clients '{"per_page":1,"page":1,"search":"example_search","id_number":"example_id_number","sort":"example_sort"}' --json

`invoiceninja.invoiceninja_create_client`

Write write

Create a new client in Invoice Ninja. Provide name and at least one contact with an email address.

Parameters: name, contacts, id_number, vat_number, website, phone, address1, address2, city, state, postal_code, country_id, private_notes, public_notes

Generic CLI call

kosmo integrations:call invoiceninja.invoiceninja_create_client '{"name":"example_name","contacts":"example_contacts","id_number":"example_id_number","vat_number":"example_vat_number","website":"example_website","phone":"example_phone","address1":"example_address1","address2":"example_address2"}' --json

Provider shortcut

kosmo integrations:invoiceninja invoiceninja_create_client '{"name":"example_name","contacts":"example_contacts","id_number":"example_id_number","vat_number":"example_vat_number","website":"example_website","phone":"example_phone","address1":"example_address1","address2":"example_address2"}' --json

`invoiceninja.invoiceninja_list_products`

Read read

List products from Invoice Ninja. Supports filtering by product key, custom value, and text search with pagination.

Parameters: per_page, page, product_key, sort, is_deleted

Generic CLI call

kosmo integrations:call invoiceninja.invoiceninja_list_products '{"per_page":1,"page":1,"product_key":"example_product_key","sort":"example_sort","is_deleted":true}' --json

Provider shortcut

kosmo integrations:invoiceninja invoiceninja_list_products '{"per_page":1,"page":1,"product_key":"example_product_key","sort":"example_sort","is_deleted":true}' --json

`invoiceninja.invoiceninja_list_payments`

Read read

List payments from Invoice Ninja. Supports filtering by client, invoice, status, and date range with pagination.

Parameters: per_page, page, client_id, invoice_id, status, sort

Generic CLI call

kosmo integrations:call invoiceninja.invoiceninja_list_payments '{"per_page":1,"page":1,"client_id":"example_client_id","invoice_id":"example_invoice_id","status":"example_status","sort":"example_sort"}' --json

Provider shortcut

kosmo integrations:invoiceninja invoiceninja_list_payments '{"per_page":1,"page":1,"client_id":"example_client_id","invoice_id":"example_invoice_id","status":"example_status","sort":"example_sort"}' --json

`invoiceninja.invoiceninja_get_current_user`

Read read

Get the profile of the currently authenticated Invoice Ninja user. Useful for verifying connection details and account information.

Parameters: none

Generic CLI call

kosmo integrations:call invoiceninja.invoiceninja_get_current_user '{}' --json

Provider shortcut

kosmo integrations:invoiceninja invoiceninja_get_current_user '{}' --json

Function Schemas

Use these parameter tables when building CLI payloads without calling integrations:schema first.

`invoiceninja.invoiceninja_list_invoices`

List invoices from Invoice Ninja. Supports filtering by client, status, and date range with pagination.

Operation: Read read
Schema command: kosmo integrations:schema invoiceninja.invoiceninja_list_invoices --json

Parameter	Type	Required	Description
`per_page`	integer	no	Number of invoices per page (default: 20).
`page`	integer	no	Page number for pagination.
`client_id`	string	no	Filter invoices by client ID.
`status`	string	no	Filter by status: draft, sent, partial, paid, cancelled, overdue, reversed.
`number`	string	no	Filter by invoice number (partial match).
`sort`	string	no	Sort field (e.g. "number", "date", "due_date", "amount").

`invoiceninja.invoiceninja_get_invoice`

Get a single invoice from Invoice Ninja by ID. Returns full invoice details including line items, client info, and payment status.

Operation: Read read
Schema command: kosmo integrations:schema invoiceninja.invoiceninja_get_invoice --json

Parameter	Type	Required	Description
`id`	string	yes	The invoice ID.

`invoiceninja.invoiceninja_create_invoice`

Create a new invoice in Invoice Ninja. Requires a client_id and at least one line item. Supports custom due dates, partial deposits, and notes.

Operation: Write write
Schema command: kosmo integrations:schema invoiceninja.invoiceninja_create_invoice --json

Parameter	Type	Required	Description
`client_id`	string	yes	The client ID to assign the invoice to.
`line_items`	array	yes	Array of line items. Each item should have: product_key (or product_cost), notes, quantity, cost (unit price).
`due_date`	string	no	Due date in YYYY-MM-DD format.
`date`	string	no	Invoice date in YYYY-MM-DD format (defaults to today).
`public_notes`	string	no	Public notes visible to the client.
`private_notes`	string	no	Private notes (internal only).
`discount`	number	no	Discount amount or percentage.
`is_amount_discount`	boolean	no	Whether discount is a fixed amount (true) or percentage (false).
`tax_name1`	string	no	First tax name.
`tax_rate1`	number	no	First tax rate percentage.
`partial`	number	no	Partial/deposit amount.
`partial_due_date`	string	no	Due date for the partial deposit (YYYY-MM-DD).

`invoiceninja.invoiceninja_list_clients`

List clients from Invoice Ninja. Supports filtering by name, email, and ID number with pagination.

Operation: Read read
Schema command: kosmo integrations:schema invoiceninja.invoiceninja_list_clients --json

Parameter	Type	Required	Description
`per_page`	integer	no	Number of clients per page (default: 20).
`page`	integer	no	Page number for pagination.
`search`	string	no	Search clients by name or email (partial match).
`id_number`	string	no	Filter by client ID number.
`sort`	string	no	Sort field (e.g. "name", "balance", "created_at").

`invoiceninja.invoiceninja_create_client`

Create a new client in Invoice Ninja. Provide name and at least one contact with an email address.

Operation: Write write
Schema command: kosmo integrations:schema invoiceninja.invoiceninja_create_client --json

Parameter	Type	Required	Description
`name`	string	yes	Client or company name.
`contacts`	array	yes	Array of contacts. Each contact should have: first_name, last_name, email. Optionally: phone.
`id_number`	string	no	Custom ID number for the client.
`vat_number`	string	no	VAT/tax identification number.
`website`	string	no	Client website URL.
`phone`	string	no	Primary phone number.
`address1`	string	no	Street address line 1.
`address2`	string	no	Street address line 2.
`city`	string	no	City.
`state`	string	no	State or province.
`postal_code`	string	no	Postal / ZIP code.
`country_id`	string	no	Country ID (ISO 3166-1 numeric).
`private_notes`	string	no	Private notes (internal only).
`public_notes`	string	no	Public notes visible to the client.

`invoiceninja.invoiceninja_list_products`

List products from Invoice Ninja. Supports filtering by product key, custom value, and text search with pagination.

Operation: Read read
Schema command: kosmo integrations:schema invoiceninja.invoiceninja_list_products --json

Parameter	Type	Required	Description
`per_page`	integer	no	Number of products per page (default: 20).
`page`	integer	no	Page number for pagination.
`product_key`	string	no	Filter by product key (exact match).
`sort`	string	no	Sort field (e.g. "product_key", "cost", "created_at").
`is_deleted`	boolean	no	Include soft-deleted products.

`invoiceninja.invoiceninja_list_payments`

List payments from Invoice Ninja. Supports filtering by client, invoice, status, and date range with pagination.

Operation: Read read
Schema command: kosmo integrations:schema invoiceninja.invoiceninja_list_payments --json

Parameter	Type	Required	Description
`per_page`	integer	no	Number of payments per page (default: 20).
`page`	integer	no	Page number for pagination.
`client_id`	string	no	Filter payments by client ID.
`invoice_id`	string	no	Filter payments by invoice ID.
`status`	string	no	Filter by payment status (e.g. "completed", "pending", "failed", "refunded").
`sort`	string	no	Sort field (e.g. "amount", "date", "created_at").

`invoiceninja.invoiceninja_get_current_user`

Get the profile of the currently authenticated Invoice Ninja user. Useful for verifying connection details and account information.

Operation: Read read
Schema command: kosmo integrations:schema invoiceninja.invoiceninja_get_current_user --json

Parameter	Type	Required	Description
No parameters.

Permissions

Headless calls still follow the integration read/write permission policy. Configure read/write defaults with integrations:configure. Add --force only for trusted automation that should bypass that policy.