Can I use Freeagent as a CLI?

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

Can I expose Freeagent through MCP?

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

Where are Freeagent credentials stored?

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

Can I deny write access for Freeagent MCP tools?

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

other

Freeagent CLI for AI Agents

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

9 functions 7 read 2 write Manual OAuth token auth

Submit Freeagent feedback View package source

Freeagent CLI Setup

Freeagent can be configured headlessly with `kosmokrator integrations:configure freeagent`.

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

Credentials

Authentication type: Manual OAuth token oauth2_manual_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
`access_token`	`FREEAGENT_ACCESS_TOKEN`	Secret `secret`	yes	Access Token
`url`	`FREEAGENT_URL`	URL `url`	no	API URL

Call Freeagent Headlessly

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

kosmo integrations:call freeagent.freeagent_list_invoices '{
  "status": "example_status",
  "from_date": "example_from_date",
  "to_date": "example_to_date",
  "contact": "example_contact",
  "project": "example_project",
  "page": 1,
  "per_page": 1
}' --json

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

kosmo integrations:freeagent freeagent_list_invoices '{
  "status": "example_status",
  "from_date": "example_from_date",
  "to_date": "example_to_date",
  "contact": "example_contact",
  "project": "example_project",
  "page": 1,
  "per_page": 1
}' --json

Agent Discovery Commands

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

kosmo integrations:docs freeagent --json
kosmo integrations:docs freeagent.freeagent_list_invoices --json
kosmo integrations:schema freeagent.freeagent_list_invoices --json
kosmo integrations:search "Freeagent" --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 Freeagent.

`freeagent.freeagent_list_invoices`

Read read

List invoices from FreeAgent. Returns a paginated list of invoices with their details. Supports filtering by status (Draft, Sent, Cancelled, Late Paid, Paid), date range, contact, and project.

Parameters: status, from_date, to_date, contact, project, page, per_page

Generic CLI call

kosmo integrations:call freeagent.freeagent_list_invoices '{"status":"example_status","from_date":"example_from_date","to_date":"example_to_date","contact":"example_contact","project":"example_project","page":1,"per_page":1}' --json

Provider shortcut

kosmo integrations:freeagent freeagent_list_invoices '{"status":"example_status","from_date":"example_from_date","to_date":"example_to_date","contact":"example_contact","project":"example_project","page":1,"per_page":1}' --json

`freeagent.freeagent_get_invoice`

Read read

Get the full details of a specific invoice from FreeAgent, including line items, totals, contact information, and status.

Parameters: invoice_id

Generic CLI call

kosmo integrations:call freeagent.freeagent_get_invoice '{"invoice_id":1}' --json

Provider shortcut

kosmo integrations:freeagent freeagent_get_invoice '{"invoice_id":1}' --json

`freeagent.freeagent_create_invoice`

Write write

Create a new invoice in FreeAgent. Requires a contact and at least one line item. Supports setting due date, currency, invoice items with quantities and prices, and comments.

Parameters: contact, dated_on, invoice_items, due_on, reference, currency, comments, project

Generic CLI call

kosmo integrations:call freeagent.freeagent_create_invoice '{"contact":"example_contact","dated_on":"example_dated_on","invoice_items":"example_invoice_items","due_on":"example_due_on","reference":"example_reference","currency":"example_currency","comments":"example_comments","project":"example_project"}' --json

Provider shortcut

kosmo integrations:freeagent freeagent_create_invoice '{"contact":"example_contact","dated_on":"example_dated_on","invoice_items":"example_invoice_items","due_on":"example_due_on","reference":"example_reference","currency":"example_currency","comments":"example_comments","project":"example_project"}' --json

`freeagent.freeagent_list_contacts`

Read read

List contacts from FreeAgent. Returns a paginated list of contacts including customers, suppliers, and employees. Supports filtering and sorting.

Parameters: view, order, created_since, updated_since, page, per_page

Generic CLI call

kosmo integrations:call freeagent.freeagent_list_contacts '{"view":"example_view","order":"example_order","created_since":"example_created_since","updated_since":"example_updated_since","page":1,"per_page":1}' --json

Provider shortcut

kosmo integrations:freeagent freeagent_list_contacts '{"view":"example_view","order":"example_order","created_since":"example_created_since","updated_since":"example_updated_since","page":1,"per_page":1}' --json

`freeagent.freeagent_get_contact`

Read read

Get the full details of a specific contact from FreeAgent, including name, email, company, billing address, and contact type.

Parameters: contact_id

Generic CLI call

kosmo integrations:call freeagent.freeagent_get_contact '{"contact_id":1}' --json

Provider shortcut

kosmo integrations:freeagent freeagent_get_contact '{"contact_id":1}' --json

`freeagent.freeagent_create_contact`

Write write

Create a new contact in FreeAgent. Contacts can be customers, suppliers, or employees. Provide at least a name (first_name/last_name for individuals or organisation_name for companies).

Parameters: first_name, last_name, organisation_name, email, phone_number, contact_type, billing_email, address1, address2, town, region, postcode, country

Generic CLI call

kosmo integrations:call freeagent.freeagent_create_contact '{"first_name":"example_first_name","last_name":"example_last_name","organisation_name":"example_organisation_name","email":"example_email","phone_number":"example_phone_number","contact_type":"example_contact_type","billing_email":"example_billing_email","address1":"example_address1"}' --json

Provider shortcut

kosmo integrations:freeagent freeagent_create_contact '{"first_name":"example_first_name","last_name":"example_last_name","organisation_name":"example_organisation_name","email":"example_email","phone_number":"example_phone_number","contact_type":"example_contact_type","billing_email":"example_billing_email","address1":"example_address1"}' --json

`freeagent.freeagent_list_projects`

Read read

List projects from FreeAgent. Returns project names, status, budget, associated contacts, and time tracking information.

Parameters: view, contact, page, per_page

Generic CLI call

kosmo integrations:call freeagent.freeagent_list_projects '{"view":"example_view","contact":"example_contact","page":1,"per_page":1}' --json

Provider shortcut

kosmo integrations:freeagent freeagent_list_projects '{"view":"example_view","contact":"example_contact","page":1,"per_page":1}' --json

`freeagent.freeagent_list_expenses`

Read read

List expenses from FreeAgent. Returns expense claims with amounts, categories, dates, and associated projects or contacts.

Parameters: from_date, to_date, contact, project, page, per_page

Generic CLI call

kosmo integrations:call freeagent.freeagent_list_expenses '{"from_date":"example_from_date","to_date":"example_to_date","contact":"example_contact","project":"example_project","page":1,"per_page":1}' --json

Provider shortcut

kosmo integrations:freeagent freeagent_list_expenses '{"from_date":"example_from_date","to_date":"example_to_date","contact":"example_contact","project":"example_project","page":1,"per_page":1}' --json

`freeagent.freeagent_get_current_user`

Read read

Get the currently authenticated FreeAgent user profile. Returns user details like name, email, role, and company information. Useful for verifying the connection and understanding which account is active.

Parameters: none

Generic CLI call

kosmo integrations:call freeagent.freeagent_get_current_user '{}' --json

Provider shortcut

kosmo integrations:freeagent freeagent_get_current_user '{}' --json

Function Schemas

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

`freeagent.freeagent_list_invoices`

List invoices from FreeAgent. Returns a paginated list of invoices with their details. Supports filtering by status (Draft, Sent, Cancelled, Late Paid, Paid), date range, contact, and project.

Operation: Read read
Schema command: kosmo integrations:schema freeagent.freeagent_list_invoices --json

Parameter	Type	Required	Description
`status`	string	no	Filter by status: Draft, Sent, Cancelled, Late, Paid.
`from_date`	string	no	Start date for filtering (ISO 8601, e.g., "2025-01-01").
`to_date`	string	no	End date for filtering (ISO 8601, e.g., "2025-12-31").
`contact`	string	no	Filter by contact URL or ID.
`project`	string	no	Filter by project URL or ID.
`page`	integer	no	Page number for pagination.
`per_page`	integer	no	Number of results per page (default: 30).

`freeagent.freeagent_get_invoice`

Get the full details of a specific invoice from FreeAgent, including line items, totals, contact information, and status.

Operation: Read read
Schema command: kosmo integrations:schema freeagent.freeagent_get_invoice --json

Parameter	Type	Required	Description
`invoice_id`	integer	yes	The ID of the invoice to retrieve.

`freeagent.freeagent_create_invoice`

Create a new invoice in FreeAgent. Requires a contact and at least one line item. Supports setting due date, currency, invoice items with quantities and prices, and comments.

Operation: Write write
Schema command: kosmo integrations:schema freeagent.freeagent_create_invoice --json

Parameter	Type	Required	Description
`contact`	string	yes	The contact URL or ID for the invoice recipient (e.g., "https://api.freeagent.com/v2/contacts/123").
`dated_on`	string	yes	The invoice date (ISO 8601, e.g., "2025-01-15").
`invoice_items`	array	yes	Array of line items, each with "description", "quantity", and "price". Optionally include "sales_tax_rate".
`due_on`	string	no	The due date (ISO 8601). If omitted, FreeAgent calculates based on contact terms.
`reference`	string	no	A reference number for the invoice.
`currency`	string	no	Currency code (e.g., "GBP", "USD", "EUR"). Defaults to the company currency.
`comments`	string	no	Comments or notes to include on the invoice.
`project`	string	no	The project URL to associate the invoice with.

`freeagent.freeagent_list_contacts`

List contacts from FreeAgent. Returns a paginated list of contacts including customers, suppliers, and employees. Supports filtering and sorting.

Operation: Read read
Schema command: kosmo integrations:schema freeagent.freeagent_list_contacts --json

Parameter	Type	Required	Description
`view`	string	no	Filter view: "all" (default), "customers", "suppliers", "active", "inactive".
`order`	string	no	Sort order: "name", "created_at", "updated_at". Prefix with "-" for descending.
`created_since`	string	no	Only contacts created after this date (ISO 8601).
`updated_since`	string	no	Only contacts updated after this date (ISO 8601).
`page`	integer	no	Page number for pagination.
`per_page`	integer	no	Number of results per page (default: 30).

`freeagent.freeagent_get_contact`

Get the full details of a specific contact from FreeAgent, including name, email, company, billing address, and contact type.

Operation: Read read
Schema command: kosmo integrations:schema freeagent.freeagent_get_contact --json

Parameter	Type	Required	Description
`contact_id`	integer	yes	The ID of the contact to retrieve.

`freeagent.freeagent_create_contact`

Create a new contact in FreeAgent. Contacts can be customers, suppliers, or employees. Provide at least a name (first_name/last_name for individuals or organisation_name for companies).

Operation: Write write
Schema command: kosmo integrations:schema freeagent.freeagent_create_contact --json

Parameter	Type	Required	Description
`first_name`	string	no	First name (for individual contacts).
`last_name`	string	no	Last name (for individual contacts).
`organisation_name`	string	no	Company or organisation name (for company contacts).
`email`	string	no	Primary email address.
`phone_number`	string	no	Phone number.
`contact_type`	string	no	Contact type: "Customer" (default) or "Supplier".
`billing_email`	string	no	Email address for invoicing.
`address1`	string	no	Address line 1.
`address2`	string	no	Address line 2.
`town`	string	no	Town or city.
`region`	string	no	Region, state, or province.
`postcode`	string	no	Postal or ZIP code.
`country`	string	no	Country code (e.g., "GB", "US", "NL").

`freeagent.freeagent_list_projects`

List projects from FreeAgent. Returns project names, status, budget, associated contacts, and time tracking information.

Operation: Read read
Schema command: kosmo integrations:schema freeagent.freeagent_list_projects --json

Parameter	Type	Required	Description
`view`	string	no	Filter view: "all" (default), "active", "completed", "cancelled", "unquoted".
`contact`	string	no	Filter by contact URL or ID.
`page`	integer	no	Page number for pagination.
`per_page`	integer	no	Number of results per page (default: 30).

`freeagent.freeagent_list_expenses`

List expenses from FreeAgent. Returns expense claims with amounts, categories, dates, and associated projects or contacts.

Operation: Read read
Schema command: kosmo integrations:schema freeagent.freeagent_list_expenses --json

Parameter	Type	Required	Description
`from_date`	string	no	Start date for filtering (ISO 8601, e.g., "2025-01-01").
`to_date`	string	no	End date for filtering (ISO 8601, e.g., "2025-12-31").
`contact`	string	no	Filter by contact URL or ID.
`project`	string	no	Filter by project URL or ID.
`page`	integer	no	Page number for pagination.
`per_page`	integer	no	Number of results per page (default: 30).

`freeagent.freeagent_get_current_user`

Operation: Read read
Schema command: kosmo integrations:schema freeagent.freeagent_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.