Metadata-Version: 2.4
Name: mayai-fatture-cli
Version: 0.1.0
Summary: Fatture in Cloud CLI — built for AI agents and developers. Manage invoices, clients, and products from the terminal.
Project-URL: Homepage, https://mayai.it
Project-URL: Repository, https://github.com/mayai-it/fatture-cli
Project-URL: Issues, https://github.com/mayai-it/fatture-cli/issues
Project-URL: Documentation, https://developers.fattureincloud.it/
Author-email: MayAI <info@mayai.it>
Maintainer-email: MayAI <info@mayai.it>
License: MIT
License-File: LICENSE
Keywords: ai-agents,automation,cli,fatture,fatture-in-cloud,invoicing,italian-invoicing
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Natural Language :: Italian
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Office/Business :: Financial :: Accounting
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Requires-Dist: click>=8.1.0
Requires-Dist: httpx>=0.27.0
Provides-Extra: dev
Requires-Dist: pytest-httpx>=0.30.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.5.0; extra == 'dev'
Description-Content-Type: text/markdown

# fatture-cli

Command-line client for the [Fatture in Cloud](https://developers.fattureincloud.it/)
API, built for both humans and AI agents. Designed to be context-efficient: the
default output strips empty fields, and `--json` produces NDJSON suitable for
piping into LLMs or jq.

Part of [MayAI CLI](https://mayai.it).

## Requirements

- Python 3.11+
- A Fatture in Cloud developer app (free) — create one at
  https://developers.fattureincloud.it/

## Installation

From source:

```bash
git clone https://github.com/mayai-it/fatture-cli.git
cd fatture-cli
make install
```

Or directly with pip:

```bash
pip install -e .
```

For local development (adds `pytest`, `ruff`):

```bash
make dev
```

## Quick start

```bash
# 1. Authenticate (opens a browser for OAuth2 consent)
fatture auth login --client-id YOUR_ID --client-secret YOUR_SECRET

# 2. Verify
fatture auth status

# 3. List the 10 most recent invoices, paid only, as NDJSON
fatture --json list invoices --status paid --limit 10

# 4. Fetch a single invoice
fatture get invoice 526346861

# 5. Search clients by name
fatture search clients "Rossi"
```

## Command reference

| Command | Description |
|---|---|
| `fatture auth login --client-id ID --client-secret SECRET` | Run the OAuth2 flow and save credentials. |
| `fatture auth status` | Show whether credentials are present and valid. |
| `fatture auth logout` | Delete saved credentials. |
| `fatture list invoices [--year Y] [--status S] [--limit N]` | List issued invoices for the active company. |
| `fatture get invoice <id>` | Fetch a single invoice with lines and payments. |
| `fatture list clients [--limit N]` | List all clients. |
| `fatture get client <id>` | Fetch a single client with address details. |
| `fatture search clients <query>` | Search clients by name (`LIKE '%query%'`). |
| `fatture list products [--limit N]` | List products / services. |
| `fatture get product <id>` | Fetch a single product. |

### Global flags

These work in any position (before or after the subcommand):

| Flag | Effect |
|---|---|
| `--json` | Emit one JSON object per line (NDJSON). |
| `--verbose` | Log HTTP method, URL, status, and duration to stderr. |
| `-h`, `--help` | Show help for the current command. |

### Exit codes

| Code | Meaning |
|---|---|
| `0` | Success |
| `1` | Application error (API 4xx/5xx, validation, etc.) |
| `2` | Not authenticated — run `fatture auth login` |

## Authentication

Fatture in Cloud uses OAuth2 Authorization Code flow. The CLI handles the
full round-trip locally:

1. Create an app at https://developers.fattureincloud.it/ and register a
   redirect URI of the form `http://127.0.0.1:<port>/callback`. The default
   port is shown by `fatture auth login --no-browser`; use `--port 0` to pick
   a free one automatically.
2. Run `fatture auth login --client-id ... --client-secret ...`. The CLI
   spins up a one-shot HTTP server on the callback port, opens your browser
   to the Fatture in Cloud consent screen, captures the authorization code,
   and exchanges it for an access + refresh token.
3. After login the CLI fetches `/user/companies` and stores the first
   company's id as the default `company_id` for subsequent calls.
4. Tokens are saved to `~/.config/mayai-cli/fatture/credentials.json` with
   `0600` permissions. Refresh happens transparently on near-expiry or 401.

To revoke locally:

```bash
fatture auth logout
```

## Output format

- **Default** — compact human-readable text. Empty / null fields are stripped
  so terminal output stays scannable.
- **`--json`** — NDJSON. One object per line; lists stream one element per
  line so consumers can process incrementally.
- **`--verbose`** — adds one stderr line per HTTP request:
  `[fatture] GET https://... -> 200 in 287ms`.

Errors always go to stderr, prefixed with `error:`.

## Development

```bash
make dev       # install with dev extras
make test      # run pytest
make lint      # run ruff
make clean     # remove caches and build artifacts
```

## License

MIT — see [LICENSE](./LICENSE).
