README

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.

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

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 spec and temporary files

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.