dolibarr-cli

Unofficial CLI for Dolibarr ERP — full REST API coverage from your terminal.

Install

Requires Node.js 20+ and npm.

npm install -g https://github.com/VidGuiCode/dolibarr-cli/releases/download/v0.2.5/dolibarr-cli-0.2.5.tgz
dolibarr --version
dolibarr config init

This installs the dolibarr command as a normal npm global CLI. It does not require sudo, does not install a system service, and does not modify system configuration.

On Windows PowerShell, dolibarr may resolve to npm's .ps1 shim and be blocked by the execution policy. Use dolibarr.cmd from PowerShell, or run dolibarr from cmd.exe / a shell that resolves the .cmd shim.

On Linux and macOS, avoid sudo npm install -g for this CLI. If npm global installs fail with permission errors, use a user-level Node.js setup such as nvm or fnm, or configure npm's global prefix to a user-owned directory.

Or for development:

git clone https://github.com/VidGuiCode/dolibarr-cli.git
cd dolibarr-cli
npm install
npm run build
npm link

Upgrading

Once installed, the CLI can upgrade itself from GitHub Releases:

dolibarr upgrade           # show installed + latest version
dolibarr upgrade check     # fetch the latest release info from GitHub
dolibarr upgrade install   # download + install the latest .tgz via npm install -g

Every dolibarr command also prints a one-line reminder to stderr when a newer version is available (cache refreshed at most once every 24h). The reminder is suppressed automatically for piped / --json / non-TTY output, and can be turned off entirely:

export DOLIBARR_NO_UPDATE_CHECK=1

Setup

dolibarr config init

Enter your Dolibarr instance URL and API key. The CLI tests the connection before saving.

Your API key is stored at ~/.config/dolibarr-cli/config.json. Treat this file as a secret and do not share or commit it.

For CI, containers, or scripts where you do not want a saved config file, set both environment variables instead:

export DOLIBARR_URL="https://your-dolibarr-instance"
export DOLIBARR_API_KEY="your-api-key"

Environment variables are supplied by your shell, CI system, or container runtime. The CLI reads them but does not create an .env file.

Getting an API key: In Dolibarr, go to Users & Groups > [your user] > API tab > Generate key. Or ask your admin to create a dedicated API user.

Usage

# Check connection
dolibarr status

# Thirdparties (customers & suppliers)
dolibarr thirdparties list
dolibarr thirdparties list --supplier
dolibarr thirdparties get 5
dolibarr thirdparties create --name "Acme Corp" --supplier --dry-run

# Customer invoices
dolibarr invoices list --status 2 --output json
dolibarr invoices get 12
dolibarr invoices get FA2501-0001            # look up by ref
dolibarr invoices validate 12
dolibarr invoices pay 12 --amount 500.00 --date 2025-12-01

# Supplier invoices
dolibarr supplier-invoices list --thirdparty 3
dolibarr supplier-invoices get 7

# Bank
dolibarr bank list
dolibarr bank transactions 1
dolibarr bank transfer --from 1 --to 2 --amount 100.00 --date 2026-05-05 --description "Internal transfer"

# Accounting
dolibarr accounting ledger --period currentyear --format CSV

# Products
dolibarr products list --type service
dolibarr products create --label "Consulting" --price 150.00 --type service

# Documents
dolibarr documents list --module facture --ref FA2501-0001
dolibarr documents upload --module facture --ref FA2501-0001 --file ./scan.pdf
dolibarr documents download --module facture --file invoices/FA2501-0001/scan.pdf --output scan.pdf

# Setup
dolibarr setup modules
dolibarr setup company
dolibarr setup conf MAIN_INFO_SOCIETE_NOM

# Projects
dolibarr projects list --status 1
dolibarr projects get PJ2501-001             # ref-lookup
dolibarr projects tasks 12 --with-timespent

# Tickets
dolibarr tickets list --thirdparty 5
dolibarr tickets get --track-id abc123def456
dolibarr tickets reply abc123def456 --message "Looking into this now."

# Contracts
dolibarr contracts list --thirdparty 5
dolibarr contracts validate 12
dolibarr contracts activate-line 12 42 --date-start 2026-01-01

# Shipments & receptions
dolibarr shipments create --socid 5 --order 123 --date 2026-01-15
dolibarr shipments validate 7 --no-trigger
dolibarr receptions close 3

# Raw API (escape hatch)
dolibarr raw GET /thirdparties
dolibarr raw POST /invoices --body '{"socid": 1}'
dolibarr raw PUT /thirdparties/5 --body '{"fournisseur": 1}'

Output Formats

All list and get commands support --output <format> where format is table (default), json, or csv. --json is kept as a back-compat alias for --output json.

dolibarr invoices list                     # table (default)
dolibarr invoices list --output json       # JSON
dolibarr invoices list --json              # JSON (shorthand)
dolibarr invoices list --output csv        # CSV (RFC 4180, raw field keys as headers)

--compact only changes JSON indentation. It does not select JSON output by itself; use --json --compact or --output json --compact.

Bank balances

dolibarr bank list shows bank account metadata. Dolibarr's account-object balance / solde fields may be stale or zero on some server versions, so they are not shown in the default list table. For reconciliation, use dolibarr bank transactions <account-id> or raw /bankaccounts/{id}/lines output and sum transaction lines independently.

Column projection with --fields

Pick exactly the columns you want, using the raw Dolibarr field keys. Works across all three output formats.

dolibarr invoices list --fields id,ref,total_ttc
dolibarr invoices list --fields id,ref,status --output csv > invoices.csv
dolibarr thirdparties get 5 --fields id,name,email,town --output json

With --fields, values pass through raw — e.g. --fields status emits the numeric code (0 / 1 / 2) rather than the mapped label (Draft / Validated / Paid). Missing keys render as empty strings.

Ref-based lookup

get accepts a human ref in place of a numeric id for resources whose Dolibarr API exposes /ref/{ref} — invoices, orders, proposals, categories, projects, and tickets. All-digit input is still treated as an id. Tickets also support public track ID lookup via --track-id.

dolibarr invoices get FA2501-0001
dolibarr orders get CO2501-0042
dolibarr proposals get PR2501-0007
dolibarr projects get PJ2501-001
dolibarr tickets get TICKET-001
dolibarr tickets get --track-id abc123def456

Dry Run

All mutating commands support --dry-run to preview what would happen:

dolibarr thirdparties create --name "Test" --supplier --dry-run
# Would create thirdparty: { name: "Test", fournisseur: 1 }
# No changes made.

Commands

Command	Description
config	Manage CLI configuration (init, show, set)
status	Check connection and show server info
raw	Execute raw API requests
thirdparties	Customers, suppliers, prospects
invoices	Customer invoices
supplier-invoices	Purchase invoices
orders	Customer orders
supplier-orders	Purchase orders
proposals	Quotes / commercial proposals
bank	Bank accounts and transactions
accounting	Accounting export data
products	Products and services
contacts	Contact persons
categories	Tags and categories
documents	File upload, download, listing
users	User management
setup	Modules, company info, config constants
projects	Projects and tasks
tickets	Support / help desk tickets
contracts	Service contracts + line activation
shipments	Customer shipments (expeditions)
receptions	Supplier receptions

Development

# Run in dev mode (requires bun)
bun src/cli.ts status

# Build
npm run build

# Type check
npm run typecheck

# Test
npm test

# Lint & format
npm run lint
npm run format

Architecture

src/
  cli.ts              Entry point — registers all command groups
  core/
    api-client.ts     HTTP client (native fetch, DOLAPIKEY auth, retries)
    config-store.ts   Config file management (~/.config/dolibarr-cli/)
    errors.ts         Error classes (ApiError, AuthError, ConfigError)
    output.ts         Table / JSON / CSV formatting
    types.ts          Shared TypeScript types
  commands/
    config.ts         dolibarr config init|show|set
    status.ts         dolibarr status
    raw.ts            dolibarr raw <METHOD> <path>
    thirdparties.ts   dolibarr thirdparties ...
    invoices.ts       dolibarr invoices ...
    ...               (one file per resource)

Conventions:

• Commands stay thin — business logic goes in src/core/
• Native fetch only — no axios, no node-fetch
• commander is the only runtime dependency
• Same patterns as plane-cli and solidtime-cli

Compatibility

Tested with Dolibarr 20.x. Should work with any version that has the REST API enabled (16+).

License

MIT