README

A comprehensive command-line interface for the Fatture in Cloud API — Italy's most popular e-invoicing platform.

123 API endpoints auto-generated from the official OpenAPI spec. Built for humans and agents.

Installation

composer global require 16bitsrl/fattureincloud-cli

Make sure Composer's global bin directory is in your PATH. You can find the path with:

composer global config bin-dir --absolute

Updating

composer global require 16bitsrl/fattureincloud-cli

Usage

Authentication

# Log in with your access token
fic auth:login

# Direct token login (non-interactive, ideal for CI/agents)
fic auth:login --token=YOUR_ACCESS_TOKEN

# OAuth2 flow
fic auth:login --client-id=ID --client-secret=SECRET

# Check status
fic auth:status
fic auth:status --json

# Refresh OAuth token
fic auth:refresh

# Log out
fic auth:logout

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

Company context

Most API calls require a --company-id option. Set a default to avoid repeating it:

# Interactive selection from your companies
fic company:set

# Direct set
fic company:set 12345

# Check current
fic company:current

Commands

Every Fatture in Cloud API endpoint has a corresponding command. Run fic <command> --help for details on a specific command.

# List all 123 available API commands
fic fic:list

# Examples
fic fic:list-clients --company-id=12345
fic fic:get-issued-document --company-id=12345 --document-id=99
fic fic:create-client --company-id=12345 --input='{"data":{"name":"Acme S.r.l.","type":"company"}}'
fic fic:send-e-invoice --company-id=12345 --document-id=99

fic fic:list-suppliers --company-id=12345
fic fic:list-products --company-id=12345
fic fic:list-issued-documents --company-id=12345 --type=invoice
fic fic:list-received-documents --company-id=12345
fic fic:list-receipts --company-id=12345
fic fic:list-f24 --company-id=12345
fic fic:list-archive-documents --company-id=12345
fic fic:list-cashbook-entries --company-id=12345 --date-from=2025-01-01 --date-to=2025-12-31

fic fic:get-company-info --company-id=12345
fic fic:get-user-info
fic fic:list-user-companies

# Plain-text client search helper
fic clients:search zanetto --company-id=12345
fic suppliers:search zanetto --company-id=12345
fic products:search consulting --company-id=12345

Searching clients

Fatture in Cloud --q uses its own query syntax, not plain free text.

# Plain-text search helper
fic clients:search zanetto --company-id=12345
fic suppliers:search studio --company-id=12345
fic products:search consulting --company-id=12345

# Raw API query syntax
fic fic:list-clients --company-id=12345 --q="name like '%zanetto%'" --json
fic fic:list-suppliers --company-id=12345 --q="name like '%studio%'" --json
fic fic:list-products --company-id=12345 --q="name like '%consulting%'" --json

Output formats

# Human-readable tables (default)
fic fic:list-clients --company-id=12345

# JSON
fic fic:list-clients --company-id=12345 --json

# YAML
fic fic:list-clients --company-id=12345 --yaml

# Compact JSON (best for piping)
fic fic:list-clients --company-id=12345 --minify

Attachments

Attachment upload for issued and received documents is token-based. Upload commands only return an attachment_token: they do not attach the file directly to the document.

# Upload an issued document attachment
fic fic:upload-issued-document-attachment \
  --company-id=12345 \
  --field=filename=document.pdf \
  --field='attachment=@/absolute/path/to/document.pdf' \
  --json

# Then pass the token when creating or modifying the document
fic fic:modify-issued-document --company-id=12345 --document-id=99 --input='{
  "data": {
    "attachment_token": "abc123..."
  }
}'

# Upload a received document attachment
fic fic:upload-received-document-attachment \
  --company-id=12345 \
  --field=filename=invoice.pdf \
  --field='attachment=@/absolute/path/to/invoice.pdf' \
  --json

# Then pass the token when creating or modifying the document
fic fic:modify-received-document --company-id=12345 --document-id=77 --input='{
  "data": {
    "attachment_token": "abc123..."
  }
}'

Verify the result with fic fic:get-issued-document or fic fic:get-received-document and check fields like attachment_url or attachment_preview_url.

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

This repository includes an agent skill that teaches coding agents how to use the Fatture in Cloud CLI.

Install

fic install-skill

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.

16bitsrl / fattureincloud-cli

Maintainers

Package info

Statistics

Security