Fatture in Cloud CLI

A CLI for the Fatture in Cloud API, with full API coverage, agent-oriented docs, and a practical XML import workflow for fattura elettronica files.

See CHANGELOG.md for release notes starting from 1.0.1.

Install

Composer

composer global require 16bitsrl/fattureincloud-cli

Static binaries

Each release also ships static builds for Linux, macOS, and Windows.

• Download them from the GitHub release assets
• Or inspect the local examples in builds/static/

After download, make the binary executable on Unix-like systems:

chmod +x ./fic-linux-x86_64
./fic-linux-x86_64 --version

Quick start

# Authenticate
fic auth:login

# Set your default company
fic company:set

# Explore the generated API commands
fic api:list

# Search helpers
fic clients:search acme --company-id=12345
fic suppliers:search studio --company-id=12345
fic products:search consulting --company-id=12345

Get your manual token at secure.fattureincloud.it/api.

XML e-invoice import

The official API does not ingest raw XML, so the CLI recreates documents through JSON APIs.

For issued XML imports, the recreated document is treated as an electronic invoice by default.

# Preview a single XML
fic einvoice:import /absolute/path/to/fattura.xml --company-id=12345 --dry-run

# Preview a signed XML.p7m file
fic einvoice:import /absolute/path/to/fattura.xml.p7m --company-id=12345 --dry-run

# Import a folder of XML files (direction is auto-detected from XML content)
fic einvoice:import /absolute/path/to/xml-dir --company-id=12345 --yes

The import supports recap before creation, dry runs, .xml and .xml.p7m inputs, client/supplier matching, embedded attachment carry-over, automatic direction inference (issued/received/self-invoice), and structured mapping for supported e-invoice fields before falling back to ei_raw. If neither XML party matches the selected company, the import is rejected.

Agent skill

This repository includes an agent skill that teaches coding agents how to use the CLI, including filtering, sorting, pagination, FAQ edge cases, quotas, and XML import.

Install the skill

fic install-skill

Skill sources live in skills/fattureincloud/.

Handy examples

fic api:list-issued-documents --company-id=12345 --type=invoice --sort=-date --json
fic api:list-clients --company-id=12345 --q="vat_number = 'IT01234567890'" --json
fic api:send-e-invoice --company-id=12345 --document-id=99

API coverage

Resource	Commands
Clients	list, get, create, modify, delete, info
Suppliers	list, get, create, modify, delete
Products	list, get, create, modify, delete
Issued documents	list, get, create, modify, delete, totals, email, transform, join
E-Invoices	send, verify XML, get XML, rejection reason
Received documents	list, get, create, modify, delete, totals, pending
Receipts	list, get, create, modify, delete, monthly totals
Taxes (F24)	list, get, create, modify, delete, attachments
Cashbook	list, get, create, modify, delete
Archive	list, get, create, modify, delete, attachments
Settings	payment accounts/methods, VAT types, tax profile, templates
Info	cities, countries, currencies, languages, categories, etc.
Webhooks	list, create, get, modify, delete, verify
User	info, companies
Companies	info, plan usage

Agent skill

See the dedicated section above.

Testing

composer test

Releasing a new version

Use the release script:

./bin/release.sh X.Y.Z

It will:

• build builds/fic with the requested version
• verify that builds/fic matches the source version
• commit builds/fic
• create tag vX.Y.Z
• push branch and tag

Then the GitHub release workflow will build the PHAR and static binaries for Linux, macOS, and Windows.

If you only want to verify that the committed PHAR is still aligned with the source version:

./bin/check-phar-sync.sh

CI also runs the same sync check on pushes and pull requests.

Users install or update with composer global require 16bitsrl/fattureincloud-cli.

Updating the OpenAPI spec

./bin/update-spec.sh              # latest from master
./bin/update-spec.sh v2.1.8       # specific tag
fic clear-cache                   # clear cached normalized spec

Credits

• Built with Laravel Zero and Spatie Laravel OpenAPI CLI
• API by Fatture in Cloud
• Made by Mattia Trapani at 16bit S.r.l.

License

The MIT License (MIT). Please see LICENSE.md for more information.