KosmoKrator

data

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.

Freeagent CLI Setup

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

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 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 reuse the same stored profile from scripts, coding CLIs, Lua, and MCP.

KeyEnv varTypeRequiredLabel
access_token FREEAGENT_ACCESS_TOKEN Secret secret yes Access Token
url FREEAGENT_URL URL url no API URL

Command Patterns

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

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

Discovery

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

Discovery commands 
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

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.

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.

Read read
Parameters
status, from_date, to_date, contact, project, page, per_page
Generic 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
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

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

Read read
Parameters
invoice_id
Generic call 
kosmo integrations:call freeagent.freeagent_get_invoice '{"invoice_id":1}' --json
Shortcut 
kosmo integrations:freeagent freeagent_get_invoice '{"invoice_id":1}' --json

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.

Write write
Parameters
contact, dated_on, invoice_items, due_on, reference, currency, comments, project
Generic 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
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

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

Read read
Parameters
view, order, created_since, updated_since, page, per_page
Generic 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
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

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

Read read
Parameters
contact_id
Generic call 
kosmo integrations:call freeagent.freeagent_get_contact '{"contact_id":1}' --json
Shortcut 
kosmo integrations:freeagent freeagent_get_contact '{"contact_id":1}' --json

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).

Write write
Parameters
first_name, last_name, organisation_name, email, phone_number, contact_type, billing_email, address1, address2, town, region, postcode, country
Generic 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
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

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

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

freeagent.freeagent_list_expenses

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

Read read
Parameters
from_date, to_date, contact, project, page, per_page
Generic 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
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

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.

Read read
Parameters
none
Generic call 
kosmo integrations:call freeagent.freeagent_get_current_user '{}' --json
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 7 parameters
Schema command 
kosmo integrations:schema freeagent.freeagent_list_invoices --json
ParameterTypeRequiredDescription
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 1 parameters
Schema command 
kosmo integrations:schema freeagent.freeagent_get_invoice --json
ParameterTypeRequiredDescription
invoice_id integer yes The ID of the invoice to retrieve.
freeagent.freeagent_create_invoice 8 parameters
Schema command 
kosmo integrations:schema freeagent.freeagent_create_invoice --json
ParameterTypeRequiredDescription
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 6 parameters
Schema command 
kosmo integrations:schema freeagent.freeagent_list_contacts --json
ParameterTypeRequiredDescription
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 1 parameters
Schema command 
kosmo integrations:schema freeagent.freeagent_get_contact --json
ParameterTypeRequiredDescription
contact_id integer yes The ID of the contact to retrieve.
freeagent.freeagent_create_contact 13 parameters
Schema command 
kosmo integrations:schema freeagent.freeagent_create_contact --json
ParameterTypeRequiredDescription
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 4 parameters
Schema command 
kosmo integrations:schema freeagent.freeagent_list_projects --json
ParameterTypeRequiredDescription
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 6 parameters
Schema command 
kosmo integrations:schema freeagent.freeagent_list_expenses --json
ParameterTypeRequiredDescription
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 0 parameters
Schema command 
kosmo integrations:schema freeagent.freeagent_get_current_user --json
ParameterTypeRequiredDescription
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.