Can I use Xero as a CLI?

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

Can I expose Xero through MCP?

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

Where are Xero credentials stored?

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

Can I deny write access for Xero MCP tools?

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

data

Xero CLI for AI Agents

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

Xero CLI Setup

Xero can be configured headlessly with `kosmokrator integrations:configure xero`.

Install, configure, and verify

# 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 xero --set access_token="$XERO_ACCESS_TOKEN" --enable --read allow --write ask --json
kosmokrator integrations:doctor xero --json
kosmokrator integrations:status --json

Credentials

Authentication type: Manual OAuth token oauth2_manual_token. Configure credentials once, then reuse the same stored profile from scripts, coding CLIs, Lua, and MCP.

Key	Env var	Type	Required	Label
`access_token`	`XERO_ACCESS_TOKEN`	Secret `secret`	yes	Access Token
`base_url`	`XERO_BASE_URL`	URL `url`	no	API Base URL

Command Patterns

The generic command is stable across every integration. The provider shortcut is shorter for humans.

Generic CLI call

kosmo integrations:call xero.xero_create_invoice '{"contact_id":"example_contact_id","type":"example_type","date":"example_date","due_date":"example_due_date","reference":"example_reference","line_items":"example_line_items","status":"example_status"}' --json

Provider shortcut

kosmo integrations:xero xero_create_invoice '{"contact_id":"example_contact_id","type":"example_type","date":"example_date","due_date":"example_due_date","reference":"example_reference","line_items":"example_line_items","status":"example_status"}' --json

Discovery

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

Discovery commands

kosmo integrations:docs xero --json
kosmo integrations:docs xero.xero_create_invoice --json
kosmo integrations:schema xero.xero_create_invoice --json
kosmo integrations:search "Xero" --json
kosmo integrations:list --json

Automation Contexts

The same configured command surface works in these environments. The command does not change unless the host wrapper, credentials, or permissions change.

CI Run integration calls from CI jobs with JSON output, explicit credentials, and predictable exit status. Cron Jobs Schedule repeatable integration workflows from cron while keeping credentials in KosmoKrator config. Shell Scripts Call integration functions from shell scripts with stable JSON input and output. Headless Automation Use KosmoKrator as a non-interactive integration runtime for local automations and wrappers. Coding Agents Let coding agents discover schemas and execute integration functions through CLI commands or MCP.

CLI Functions

Every function below can be called headlessly. Commands are highlighted, copyable, and scroll horizontally when payloads are long.

`xero.xero_create_invoice`

Create a new invoice in Xero. Requires a contact_id and at least one line item with description and unit_amount. Returns the created invoice with its ID and number.

Write write

Parameters: contact_id, type, date, due_date, reference, line_items, status

Generic call

kosmo integrations:call xero.xero_create_invoice '{"contact_id":"example_contact_id","type":"example_type","date":"example_date","due_date":"example_due_date","reference":"example_reference","line_items":"example_line_items","status":"example_status"}' --json

Shortcut

kosmo integrations:xero xero_create_invoice '{"contact_id":"example_contact_id","type":"example_type","date":"example_date","due_date":"example_due_date","reference":"example_reference","line_items":"example_line_items","status":"example_status"}' --json

`xero.xero_get_contact`

Retrieve a Xero contact by its ID. Returns the contact's ID, name, email, phone, addresses, and status.

Read read

Parameters: contact_id

Generic call

kosmo integrations:call xero.xero_get_contact '{"contact_id":"example_contact_id"}' --json

Shortcut

kosmo integrations:xero xero_get_contact '{"contact_id":"example_contact_id"}' --json

`xero.xero_get_current_user`

Retrieve the currently authenticated Xero user. Returns the user's ID, name, and email. Useful for identifying which Xero organisation or token is in use.

Read read

Parameters: none

Generic call

kosmo integrations:call xero.xero_get_current_user '{}' --json

Shortcut

kosmo integrations:xero xero_get_current_user '{}' --json

`xero.xero_get_invoice`

Retrieve a Xero invoice by its ID. Returns the full invoice including line items, contact details, and totals.

Read read

Parameters: invoice_id

Generic call

kosmo integrations:call xero.xero_get_invoice '{"invoice_id":"example_invoice_id"}' --json

Shortcut

kosmo integrations:xero xero_get_invoice '{"invoice_id":"example_invoice_id"}' --json

`xero.xero_list_accounts`

List Xero chart of accounts. Returns account codes, names, types, tax types, and statuses.

Read read

Parameters: where, order

Generic call

kosmo integrations:call xero.xero_list_accounts '{"where":"example_where","order":"example_order"}' --json

Shortcut

kosmo integrations:xero xero_list_accounts '{"where":"example_where","order":"example_order"}' --json

`xero.xero_list_contacts`

List Xero contacts with pagination. Returns contact IDs, names, emails, and types. Use page for pagination (1-indexed).

Read read

Parameters: page, where, order, include_archived

Generic call

kosmo integrations:call xero.xero_list_contacts '{"page":1,"where":"example_where","order":"example_order","include_archived":true}' --json

Shortcut

kosmo integrations:xero xero_list_contacts '{"page":1,"where":"example_where","order":"example_order","include_archived":true}' --json

`xero.xero_list_invoices`

List Xero invoices with pagination and filtering. Returns invoice IDs, numbers, amounts, status, and dates. Use page and pageSize for pagination.

Read read

Parameters: page, pageSize, statuses, where, order

Generic call

kosmo integrations:call xero.xero_list_invoices '{"page":1,"pageSize":1,"statuses":"example_statuses","where":"example_where","order":"example_order"}' --json

Shortcut

kosmo integrations:xero xero_list_invoices '{"page":1,"pageSize":1,"statuses":"example_statuses","where":"example_where","order":"example_order"}' --json

Function Schemas

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

xero.xero_create_invoice 7 parameters

Schema command

kosmo integrations:schema xero.xero_create_invoice --json

Parameter	Type	Required	Description
`contact_id`	string	yes	Xero contact ID (UUID) to invoice.
`type`	string	no	Invoice type: "ACCREC" (accounts receivable) or "ACCPAY" (accounts payable). Default: ACCREC.
`date`	string	no	Invoice date (YYYY-MM-DD). Defaults to today.
`due_date`	string	no	Due date (YYYY-MM-DD).
`reference`	string	no	Reference text for the invoice.
`line_items`	array	yes	Array of line items, each with description, quantity, unit_amount, account_code, tax_type.
`status`	string	no	Invoice status: "DRAFT" or "AUTHORISED". Default: DRAFT.

xero.xero_get_contact 1 parameters

Schema command

kosmo integrations:schema xero.xero_get_contact --json

Parameter	Type	Required	Description
`contact_id`	string	yes	Xero contact ID (UUID).

xero.xero_get_current_user 0 parameters

Schema command

kosmo integrations:schema xero.xero_get_current_user --json

Parameter	Type	Required	Description
No parameters.

xero.xero_get_invoice 1 parameters

Schema command

kosmo integrations:schema xero.xero_get_invoice --json

Parameter	Type	Required	Description
`invoice_id`	string	yes	Xero invoice ID (UUID).

xero.xero_list_accounts 2 parameters

Schema command

kosmo integrations:schema xero.xero_list_accounts --json

Parameter	Type	Required	Description
`where`	string	no	Xero where filter expression (e.g. Type=="BANK").
`order`	string	no	Sort order (e.g. "Code ASC").

xero.xero_list_contacts 4 parameters

Schema command

kosmo integrations:schema xero.xero_list_contacts --json

Parameter	Type	Required	Description
`page`	integer	no	Page number (default 1).
`where`	string	no	Xero where filter expression.
`order`	string	no	Sort order (e.g. "Name ASC").
`include_archived`	boolean	no	Include archived contacts (default false).

xero.xero_list_invoices 5 parameters

Schema command

kosmo integrations:schema xero.xero_list_invoices --json

Parameter	Type	Required	Description
`page`	integer	no	Page number (default 1).
`pageSize`	integer	no	Number of invoices per page (default 100, max 2000).
`statuses`	string	no	Comma-separated filter: DRAFT, SUBMITTED, AUTHORISED, PAID, VOIDED, DELETED.
`where`	string	no	Xero where filter expression (e.g. Type=="ACCREC").
`order`	string	no	Sort order (e.g. "Date DESC", "InvoiceNumber ASC").

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.