16bitsrl/fattureincloud-cli

Comprehensive CLI for Fatture in Cloud API - built for humans and agents.

Maintainers

Package info

github.com/16bitsrl/fattureincloud-cli

Type:project

pkg:composer/16bitsrl/fattureincloud-cli

Statistics

Installs: 9

Dependents: 0

Suggesters: 0

Stars: 1

Open Issues: 0

Security

Advisories: 0

Aikido package health analysis

v1.0.3 2026-04-26 08:59 UTC

Requires

  • php: ^8.2

Requires (Dev)

MIT ab638f6ec346d099aec82314fe3e4612e523b865

  • Mattia Trapani <mt.woop@16bit.it>

apicliinvoicingE-Invoicefattureinclouditaliafattura

This package is auto-updated.

Last update: 2026-04-26 09:01:04 UTC

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
  • 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

License

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