go-holded

Holded API made easy — invoicing, CRM, accounting, projects, team. TypeScript library + gateway CLI for AI agents and humans.

Features

• 9 domains: contacts, accounting, taxes, cash, invoicing, stock, team, CRM, projects
• Multi-tenant: different API key per client via profiles
• AI-agent ready: JSON CLI output, safety gates on destructive ops, pi skill included
• TypeScript-first: full types, ESM, zero runtime dependencies

Install

npm install @marcfargas/go-holded

Quick Start (Library)

import { createClient } from '@marcfargas/go-holded';

// Reads HOLDED_API_KEY env var
const client = createClient();

// Or use a profile for multi-tenant
const client = createClient({ profile: 'acme' }); // reads HOLDED_API_KEY_ACME

// Contacts
const contacts = await client.contacts.list();

// Invoicing
const invoices = await client.invoicing.documents.list('invoice');
const pdf = await client.invoicing.documents.pdf('invoice', 'abc123');

// CRM
const leads = await client.crm.leads.list();
await client.crm.leads.addNote('lead123', { note: 'Called client' });

// Accounting
const ledger = await client.accounting.dailyLedger.list();

// Team
await client.team.employees.clockIn('emp123');

Quick Start (CLI)

# Set your API key
export HOLDED_API_KEY=your-key-here

# Or per-profile
export HOLDED_API_KEY_ACME=acme-key-here

# List contacts
npx go-holded contacts list
npx go-holded --profile acme contacts list

# Invoicing
npx go-holded invoicing documents list invoice
npx go-holded invoicing documents get invoice abc123
npx go-holded invoicing documents pdf invoice abc123

# CRM
npx go-holded crm leads list
npx go-holded crm leads add-note lead123 --json '{"note":"Called"}'

# Destructive operations require --confirm
npx go-holded contacts delete abc123 --confirm
npx go-holded invoicing documents send invoice abc123 --confirm
npx go-holded team employees clock-in emp123 --confirm

Multi-Tenant

Each Holded API key maps to one tenant/company. Use profiles to manage multiple:

# Environment variables
export HOLDED_API_KEY=default-key          # default
export HOLDED_API_KEY_ACME=acme-key        # profile: acme
export HOLDED_API_KEY_STARTUP_X=startup-key # profile: startup-x

const acme = createClient({ profile: 'acme' });
const startup = createClient({ profile: 'startup-x' });

Domains

| Domain | Description | CLI prefix | |--------|-------------|------------| | contacts | Contacts + groups | contacts | | accounting | Expense accounts (6xxx), income accounts (7xxx), chart, ledger | accounting | | taxes | Tax configuration | taxes | | cash | Treasuries, payments, remittances | cash | | invoicing | Documents (10 types), numbering series, services | invoicing | | stock | Products, warehouses | stock | | team | Employees, time tracking, clock in/out | team | | crm | Funnels, leads, events, bookings | crm | | projects | Projects, tasks, time tracking | projects |

Note: Our domain organization differs from Holded's API layout to be more intuitive. See DEVELOPMENT.md for the full mapping.

Safety Model

| Level | Operations | CLI gate | |-------|-----------|----------| | READ | list, get, pdf | None | | WRITE | create, update | None | | DESTRUCTIVE | delete, send, pay, ship, clock-in/out | --confirm required |

Without --confirm, destructive CLI commands preview what would happen and exit with code 2.

For AI Agents

This package ships as a pi package with built-in skill documentation:

pi install npm:@marcfargas/go-holded

License

Code: MIT Skills (skills/): CC0 1.0 Universal — public domain, no attribution required.