sibill-cli

Interfaccia a riga di comando per la Sibill Integration API. Gestisci aziende, conti bancari, documenti, transazioni, riconciliazioni e molto altro direttamente dal terminale.

Indice

• Quick Start
• Installazione
• Configurazione
• Concetti chiave
• Opzioni globali
• Comandi
  • config
  • companies
  • accounts
  • categories
  • counterparts
  • documents
  • transactions
  • flows
  • reconciliations
• Paginazione
• Output JSON e ricette jq
• Workflow di esempio
• Uso in CI/CD
• Risoluzione problemi
• Licenza

Quick Start

Quattro comandi per essere operativi:

npx sibill-cli config set-key sk-la-tua-api-key
npx sibill-cli config set-env prod
npx sibill-cli config set-company comp_abc123
npx sibill-cli companies list

Da qui in poi gli esempi usano sibill (installazione globale). Con npx basta anteporre npx sibill-cli a ogni comando.

Installazione

Via npm

Usa direttamente con npx senza installare:

npx sibill-cli --version

Oppure installa globalmente:

npm install -g sibill-cli
sibill --version

Configurazione

Prima di usare la CLI devi impostare una API key e (opzionalmente) un'azienda predefinita.

# Salva la chiave API
sibill config set-key sk-la-tua-api-key

# Scegli l'ambiente (prod o dev)
sibill config set-env prod

# Imposta un'azienda predefinita (evita di passare -c ogni volta)
sibill config set-company comp_abc123

# Abilita la modalita beta per sbloccare le operazioni di scrittura
sibill config set-beta on

# Verifica la configurazione
sibill config show

La configurazione viene salvata in ~/.sibill/config.json.

Variabile d'ambiente

La variabile SIBILL_API_KEY ha priorita sulla chiave salvata nel file di configurazione:

export SIBILL_API_KEY=sk-la-tua-api-key
sibill companies list

Ambienti

| Nome | URL | |--------|--------------------------------------| | prod | https://integration.sibill.com | | dev | https://integration.dev.sibill.com |

Modalita beta

Le operazioni di scrittura (create, update, delete, share) sono disabilitate per impostazione predefinita. Per sbloccarle, abilita la modalita beta:

sibill config set-beta on
# Attenzione: la modalita beta abilita le operazioni di scrittura (create, update, delete, share).
# Queste azioni possono modificare o eliminare dati in modo irreversibile.
# L'utente e il solo responsabile di qualsiasi modifica effettuata.
# Vuoi abilitare la modalita beta? [y/N]: y
# Beta mode enabled.

L'abilitazione richiede una conferma interattiva. La disabilitazione (set-beta off) ha effetto immediato senza prompt.

Quando la modalita beta e disattivata, qualsiasi comando di scrittura termina con un messaggio d'errore. Per disabilitarla:

sibill config set-beta off

Concetti chiave

Il modello dati di Sibill segue questa gerarchia:

Azienda (Company)
 |
 |-- Conti bancari (Accounts)
 |     |
 |     `-- Transazioni (Transactions) -------.
 |                                            |
 |-- Controparti (Counterparts)               |  Riconciliazione
 |                                            |
 |-- Categorie (Categories)                   |
 |                                            |
 `-- Documenti (Documents)                    |
       |                                      |
       `-- Scadenze (Flows) -----------------'

• Azienda: entita centrale. Ogni risorsa appartiene a un'azienda.
• Conto bancario: conto collegato all'azienda da cui vengono importate le transazioni.
• Transazione: movimento bancario reale (data, importo, descrizione, tipo).
• Controparte: cliente o fornitore coinvolto in un documento o flusso di pagamento.
• Categoria: etichetta definita dall'utente per organizzare documenti e transazioni.
• Documento: fattura, nota di credito, ordine o altro documento fiscale/contabile. Puo essere emesso o ricevuto.
• Scadenza (Flow): termine di pagamento atteso su un documento (importo, data, metodo, stato). Un documento puo avere piu scadenze (es. pagamento rateale).
• Riconciliazione: collegamento tra una scadenza e la transazione bancaria che la salda.

Opzioni globali

| Opzione | Descrizione | |-------------|---------------------------------------------------| | --json | Restituisce il JSON grezzo dell'API invece della tabella formattata | | --version | Mostra la versione e termina | | --help | Mostra l'aiuto e termina |

sibill --json companies list
sibill --version
sibill --help

Comandi

config — Configurazione della CLI

Configura la CLI con le credenziali API e l'ambiente preferito. Le impostazioni vengono salvate localmente e usate da tutti i comandi successivi.

config set-key

Salva la chiave API di Sibill.

sibill config set-key API_KEY

Esempio:

sibill config set-key sk-abc123xyz
# API key saved.

config set-env

Cambia ambiente tra produzione e sviluppo.

sibill config set-env ENV      # prod | dev

Esempio:

sibill config set-env dev
# Environment set to dev (https://integration.dev.sibill.com)

config set-company

Imposta un'azienda predefinita. Tutti i comandi che richiedono un'azienda useranno automaticamente questo ID.

sibill config set-company COMPANY_ID

Esempio:

sibill config set-company comp_abc123
# Default company set to comp_abc123

config set-beta

Abilita o disabilita la modalita beta. Quando attiva, le operazioni di scrittura sono sbloccate.

sibill config set-beta STATE    # on | off

config show

Mostra la configurazione corrente: ambiente, chiave API (mascherata), azienda predefinita e stato beta.

sibill config show

Output di esempio:

Environment:  prod (https://integration.sibill.com)
API Key:      sk-abc12...
Company ID:   comp_abc123
Beta mode:    on

companies — Aziende

L'Azienda e l'entita centrale di Sibill: ogni risorsa (documenti, conti, transazioni, controparti) appartiene a un'azienda.

companies list

Elenca tutte le aziende accessibili con la chiave API corrente.

sibill companies list [--expand CAMPO]

| Opzione | Descrizione | |------------|------------------------------------------------| | --expand | Espandi campi correlati (es. subscriptions) |

Esempi:

# Lista semplice
sibill companies list

# Con dettagli sugli abbonamenti
sibill companies list --expand subscriptions

accounts — Conti bancari

Un Conto rappresenta un conto bancario collegato a un'azienda. Sibill importa le transazioni da questi conti per abilitare la riconciliazione con fatture e scadenze.

accounts list

Elenca tutti i conti bancari collegati all'azienda.

sibill accounts list [OPZIONI]

| Opzione | Breve | Descrizione | |----------------|-------|---------------------------------------| | --company | -c | ID azienda (predefinito: da config) | | --page-size | | Elementi per pagina | | --cursor | | Cursore di paginazione | | --sort | | Campo di ordinamento (created_at) | | --filter-id | | Filtra per ID conto |

Esempi:

# Tutti i conti dell'azienda predefinita
sibill accounts list

# Conti di un'azienda specifica
sibill accounts list -c comp_xyz789

# Filtra per ID
sibill accounts list --filter-id acc_123

accounts get

Recupera i dettagli completi di un conto specifico.

sibill accounts get ACCOUNT_ID [-c COMPANY_ID]

Esempio:

sibill accounts get acc_123

categories — Categorie

Le Categorie e Sottocategorie sono etichette definite dall'utente per organizzare documenti, transazioni e altre risorse in gruppi significativi (es. "Spese operative", "Marketing").

categories list

Elenca tutte le categorie dell'azienda.

sibill categories list [OPZIONI]

| Opzione | Breve | Descrizione | |------------------|-------|--------------------------------------| | --company | -c | ID azienda | | --page-size | | Elementi per pagina | | --cursor | | Cursore di paginazione | | --sort | | Campo di ordinamento (name) | | --filter-id | | Filtra per ID categoria | | --filter-name | | Filtra per nome |

Esempi:

sibill categories list
sibill categories list --filter-name "Marketing"

categories get

Recupera i dettagli di una categoria specifica.

sibill categories get CATEGORY_ID [-c COMPANY_ID]

Esempio:

sibill categories get cat_456

counterparts — Controparti

Una Controparte e l'altra parte coinvolta in un documento o flusso di pagamento, tipicamente un cliente o un fornitore. E identificata per ragione sociale, partita IVA o codice fiscale.

counterparts list

Elenca tutte le controparti associate all'azienda.

sibill counterparts list [OPZIONI]

| Opzione | Breve | Descrizione | |------------------|-------|--------------------------------------| | --company | -c | ID azienda | | --page-size | | Elementi per pagina | | --cursor | | Cursore di paginazione | | --sort | | Campo di ordinamento (company_name)| | --filter-vat | | Filtra per partita IVA | | --filter-tax | | Filtra per codice fiscale | | --filter-name | | Filtra per ragione sociale |

Esempi:

# Tutti i fornitori/clienti
sibill counterparts list

# Cerca per partita IVA
sibill counterparts list --filter-vat IT12345678901

# Cerca per ragione sociale
sibill counterparts list --filter-name "Acme"

counterparts get

Recupera i dettagli completi di una controparte.

sibill counterparts get COUNTERPART_ID [-c COMPANY_ID]

Esempio:

sibill counterparts get ctp_789

counterparts search

Cerca una controparte per partita IVA su tutte le aziende collegate alla chiave API. Utile per verificare se un cliente o fornitore esiste gia prima di creare un documento.

sibill counterparts search --vat PARTITA_IVA

| Opzione | Obbligatorio | Descrizione | |---------|--------------|------------------------------| | --vat | Si | Partita IVA da cercare |

Esempio:

sibill counterparts search --vat IT12345678901

documents — Documenti

Un Documento e la rappresentazione generica di qualsiasi record fiscale o contabile: fatture, note di credito, ordini, preventivi e altro. I documenti possono essere emessi (ISSUED) o ricevuti (RECEIVED). Ogni documento puo avere una o piu scadenze di pagamento.

documents list

Elenca tutti i documenti dell'azienda con filtri avanzati.

sibill documents list [OPZIONI]

| Opzione | Breve | Descrizione | |----------------------------|-------|------------------------------------------------| | --company | -c | ID azienda | | --page-size | | Elementi per pagina | | --cursor | | Cursore di paginazione | | --sort | | Ordinamento (created_at, creation_date, delivery_date, number) | | --expand | | Espandi (category, counterpart, flows, subcategory) | | --filter-direction | | ISSUED o RECEIVED | | --filter-status | | DRAFT, CREATED, SENT, DELIVERED, ecc. | | --filter-type | | INVOICE, BILL, CREDIT_NOTE, ecc. | | --filter-number | | Numero documento | | --filter-counterpart | | Ragione sociale controparte | | --filter-source-id | | ID sorgente | | --filter-creation-date | | Filtra per data creazione | | --filter-delivery-date | | Filtra per data consegna |

Esempi:

# Tutte le fatture emesse
sibill documents list --filter-direction ISSUED --filter-type INVOICE

# Fatture ricevute in bozza
sibill documents list --filter-direction RECEIVED --filter-status DRAFT

# Cerca per numero documento con dettagli controparte
sibill documents list --filter-number "2025/001" --expand counterpart

# Documenti creati in una data specifica
sibill documents list --filter-creation-date 2025-03-15

documents get

Recupera i dettagli completi di un documento.

sibill documents get DOCUMENT_ID [-c COMPANY_ID] [--expand CAMPO]

| Opzione | Descrizione | |------------|-----------------------------------------------------------------------| | --expand | Espandi (category, counterpart, flows, subcategory) |

Esempi:

sibill documents get doc_abc123
sibill documents get doc_abc123 --expand counterpart --expand flows

documents update

Aggiorna i metadati di un documento esistente: assegna una categoria o aggiungi note testuali (max 1000 caratteri). Richiede modalita beta.

sibill documents update DOCUMENT_ID [OPZIONI]

| Opzione | Descrizione | |--------------------|---------------------------------| | --company / -c | ID azienda | | --category-id | ID categoria da assegnare | | --notes | Note (max 1000 caratteri) |

Almeno uno tra --category-id o --notes e obbligatorio.

Esempio:

sibill documents update doc_abc123 --category-id cat_456 --notes "Pagamento confermato"

documents create-invoice

Crea una nuova fattura da un payload JSON. Puoi emetterla immediatamente con --issue. Richiede modalita beta.

sibill documents create-invoice --body FILE [OPZIONI]

| Opzione | Obbligatorio | Descrizione | |-----------------------|--------------|------------------------------------------| | --company / -c | No | ID azienda | | --body | Si | File JSON della fattura (o - per stdin) | | --issue | No | Emetti la fattura immediatamente | | --reconciliation-id | No | Identificativo riconciliazione |

Esempi:

# Crea ed emetti una fattura
sibill documents create-invoice --body fattura.json --issue

# Da stdin (utile in pipeline)
cat fattura.json | sibill documents create-invoice --body - --issue

# Crea senza emettere (bozza)
sibill documents create-invoice --body fattura.json

documents get-invoice

Recupera il file della fattura (PDF o XML) con un URL firmato e temporaneo per il download.

sibill documents get-invoice DOCUMENT_ID [-c COMPANY_ID]

Esempio:

sibill documents get-invoice doc_abc123

documents share-invoice

Invia una fattura via email a un destinatario. Richiede modalita beta.

sibill documents share-invoice DOCUMENT_ID --to EMAIL --reply-to EMAIL [OPZIONI]

| Opzione | Obbligatorio | Descrizione | |--------------|--------------|------------------------------| | --to | Si | Email del destinatario | | --reply-to | Si | Email per le risposte | | --subject | No | Oggetto dell'email | | --body | No | Corpo dell'email |

Esempio:

sibill documents share-invoice doc_abc123 \
  --to [email protected] \
  --reply-to [email protected] \
  --subject "Fattura n. 42" \
  --body "In allegato la fattura. Cordiali saluti."

transactions — Transazioni

Una Transazione e un movimento bancario reale importato da un conto collegato. Ogni transazione ha data, importo, descrizione e tipo. Le transazioni sono la controparte "reale" delle scadenze attese sui documenti e servono come base per la riconciliazione.

transactions list

Elenca tutte le transazioni bancarie dell'azienda.

sibill transactions list [OPZIONI]

| Opzione | Breve | Descrizione | |-------------------------|-------|------------------------------------------------| | --company | -c | ID azienda | | --page-size | | Elementi per pagina | | --cursor | | Cursore di paginazione | | --sort | | Ordinamento (amount, created_at, date) | | --expand | | Espandi (category, subcategory, reconciliations, reconciliations.flow) | | --filter-account | | Filtra per ID conto | | --filter-date | | Filtra per data | | --filter-type | | Filtra per tipo | | --filter-counterpart | | Filtra per nome controparte | | --filter-description | | Filtra per descrizione |

Esempi:

# Tutte le transazioni
sibill transactions list

# Transazioni di un conto specifico
sibill transactions list --filter-account acc_123

# Transazioni di una data con riconciliazioni
sibill transactions list --filter-date 2025-03-15 --expand reconciliations

# Cerca per descrizione
sibill transactions list --filter-description "bonifico"

transactions get

Recupera i dettagli completi di una transazione.

sibill transactions get TRANSACTION_ID [-c COMPANY_ID] [--expand CAMPO]

| Opzione | Descrizione | |------------|----------------------------------------------------------------------------------| | --expand | Espandi (category, subcategory, reconciliations, reconciliations.flow) |

Esempio:

sibill transactions get txn_xyz789 --expand reconciliations.flow

flows — Scadenze

Una Scadenza (Flow) rappresenta i termini di pagamento attesi per un documento: quanto e dovuto, quando, con quale metodo, e se e stato pagato. Un documento puo avere piu scadenze (es. pagamento rateale). Le scadenze sono il ponte tra documenti e transazioni bancarie: la riconciliazione collega una scadenza alla transazione che la salda.

Tutti i comandi flows richiedono l'opzione --document / -d per specificare il documento padre.

flows list

Elenca tutte le scadenze di un documento.

sibill flows list -d DOCUMENT_ID [OPZIONI]

| Opzione | Breve | Descrizione | |----------------|-------|--------------------------------------| | --company | -c | ID azienda | | --document | -d | ID documento (obbligatorio) | | --page-size | | Elementi per pagina | | --cursor | | Cursore di paginazione |

Esempio:

sibill flows list -d doc_abc123

flows get

Recupera i dettagli di una scadenza specifica.

sibill flows get FLOW_ID -d DOCUMENT_ID [-c COMPANY_ID]

Esempio:

sibill flows get flow_abc123 -d doc_abc123

flows update

Aggiorna i dettagli di una scadenza: importo, data prevista, data effettiva, metodo o stato di pagamento. Richiede modalita beta.

sibill flows update FLOW_ID -d DOCUMENT_ID [OPZIONI]

| Opzione | Descrizione | |----------------------|------------------------------------------------------------------| | --company / -c | ID azienda | | --document / -d | ID documento (obbligatorio) | | --amount | Importo come JSON: {"amount": "100", "currency": "EUR"} | | --expected-date | Data pagamento prevista (AAAA-MM-GG) | | --payment-date | Data pagamento effettiva (AAAA-MM-GG) | | --payment-method | Metodo di pagamento | | --payment-status | Stato del pagamento |

Almeno un campo di aggiornamento e obbligatorio.

Esempi:

# Segna come pagato
sibill flows update flow_abc123 -d doc_abc123 \
  --payment-status PAID --payment-date 2025-01-15

# Aggiorna l'importo
sibill flows update flow_abc123 -d doc_abc123 \
  --amount '{"amount": "1500.00", "currency": "EUR"}'

reconciliations — Riconciliazioni

Una Riconciliazione e il collegamento tra una transazione bancaria reale e una scadenza attesa su un documento. Creando una riconciliazione confermi che una specifica transazione salda una specifica scadenza, chiudendo il cerchio tra cio che hai fatturato e cio che e effettivamente arrivato (o uscito) dal conto.

reconciliations list

Elenca tutte le riconciliazioni dell'azienda.

sibill reconciliations list [OPZIONI]

| Opzione | Breve | Descrizione | |------------------------|-------|--------------------------------------| | --company | -c | ID azienda | | --page-size | | Elementi per pagina | | --cursor | | Cursore di paginazione | | --sort | | Ordinamento (created_at) | | --expand | | Espandi (flow, transaction) | | --filter-transaction | | Filtra per ID transazione | | --filter-flow | | Filtra per ID scadenza |

Esempi:

# Tutte le riconciliazioni con dettagli
sibill reconciliations list --expand flow --expand transaction

# Riconciliazioni di una transazione specifica
sibill reconciliations list --filter-transaction txn_xyz789

reconciliations get

Recupera i dettagli di una riconciliazione specifica.

sibill reconciliations get RECONCILIATION_ID [-c COMPANY_ID] [--expand CAMPO]

| Opzione | Descrizione | |------------|--------------------------------------| | --expand | Espandi (flow, transaction) |

Esempio:

sibill reconciliations get rec_456 --expand flow --expand transaction

reconciliations create

Crea una nuova riconciliazione collegando una scadenza a una transazione bancaria. Richiede modalita beta.

sibill reconciliations create --flow-id FLOW_ID --transaction-id TXN_ID [OPZIONI]

| Opzione | Obbligatorio | Descrizione | |---------------------|--------------|--------------------------------------| | --flow-id | Si | ID scadenza da riconciliare | | --transaction-id | Si | ID transazione da riconciliare | | --expand | No | Espandi (flow, transaction) |

Esempio:

sibill reconciliations create \
  --flow-id flow_abc123 \
  --transaction-id txn_xyz789 \
  --expand flow

reconciliations delete

Elimina una riconciliazione esistente, scollegando la scadenza dalla transazione. La CLI chiede conferma prima di procedere. Richiede modalita beta.

sibill reconciliations delete RECONCILIATION_ID [-c COMPANY_ID]

Esempio:

sibill reconciliations delete rec_456
# Are you sure you want to delete this reconciliation? [y/N]: y
# Reconciliation deleted.

Paginazione

I comandi list supportano la paginazione tramite cursore con --page-size e --cursor:

# Prima pagina (10 risultati)
sibill transactions list --page-size 10

# L'output mostra: "Next page cursor: abc123..."
# Usa il cursore per la pagina successiva
sibill transactions list --page-size 10 --cursor abc123...

Per scorrere tutte le pagine in uno script:

CURSOR=""
while true; do
  if [ -z "$CURSOR" ]; then
    RESULT=$(sibill --json transactions list --page-size 50)
  else
    RESULT=$(sibill --json transactions list --page-size 50 --cursor "$CURSOR")
  fi
  echo "$RESULT" | jq '.data[]'
  CURSOR=$(echo "$RESULT" | jq -r '.next_cursor // empty')
  [ -z "$CURSOR" ] && break
done

Output JSON e ricette jq

Passa --json prima del comando per ottenere la risposta grezza dell'API:

sibill --json documents list --filter-direction ISSUED

Ricette utili con jq

# Estrarre solo gli importi delle transazioni
sibill --json transactions list | jq '.data[].amount'

# Elenco ID e numeri di tutte le fatture emesse
sibill --json documents list --filter-direction ISSUED --filter-type INVOICE \
  | jq '.data[] | {id, number, gross_amount}'

# Somma totale degli importi lordi
sibill --json documents list --filter-direction ISSUED \
  | jq '[.data[].gross_amount | tonumber] | add'

# Esporta controparti in CSV
sibill --json counterparts list \
  | jq -r '.data[] | [.id, .company_name, .vat_number] | @csv'

# Filtra transazioni non riconciliate (senza riconciliazioni)
sibill --json transactions list --expand reconciliations \
  | jq '.data[] | select(.reconciliations == [] or .reconciliations == null)'

# Elenco scadenze scadute (confronto con data odierna)
sibill --json flows list -d doc_abc123 \
  | jq --arg today "$(date +%Y-%m-%d)" \
    '.data[] | select(.expected_payment_date < $today and .payment_status != "PAID")'

Workflow di esempio

1. Setup iniziale

# Configura credenziali e azienda
sibill config set-key sk-la-tua-api-key
sibill config set-env prod

# Visualizza le aziende disponibili per trovare l'ID
sibill companies list

# Imposta l'azienda predefinita
sibill config set-company comp_abc123

# Abilita le operazioni di scrittura
sibill config set-beta on

# Verifica tutto
sibill config show

2. Fatturazione completa: crea, emetti, invia, traccia, riconcilia

# 1. Crea ed emetti la fattura
sibill documents create-invoice --body fattura.json --issue

# 2. Verifica che sia stata creata
sibill documents list --filter-direction ISSUED --filter-type INVOICE --sort created_at

# 3. Recupera l'ID della fattura appena creata e scarica il PDF
sibill documents get-invoice doc_nuovaFattura

# 4. Invia via email al cliente
sibill documents share-invoice doc_nuovaFattura \
  --to [email protected] \
  --reply-to [email protected] \
  --subject "Fattura n. 42 - Gennaio 2025"

# 5. Quando arriva il pagamento, trova la transazione
sibill transactions list --filter-counterpart "Acme" --filter-date 2025-02-01

# 6. Visualizza le scadenze del documento
sibill flows list -d doc_nuovaFattura

# 7. Riconcilia scadenza e transazione
sibill reconciliations create \
  --flow-id flow_abc123 \
  --transaction-id txn_xyz789

3. Riconciliazione manuale

# Trova la transazione da riconciliare
sibill transactions list --filter-description "bonifico" --filter-date 2025-03-01

# Trova il documento con la scadenza corrispondente
sibill documents list --filter-counterpart "Acme" --expand flows

# Prendi l'ID della scadenza
sibill flows list -d doc_abc123

# Crea la riconciliazione
sibill reconciliations create \
  --flow-id flow_456 \
  --transaction-id txn_789

# Verifica
sibill reconciliations get rec_nuovo --expand flow --expand transaction

4. Monitoraggio scadenze

# Tutte le scadenze di un documento
sibill flows list -d doc_abc123

# Dettagli di una scadenza specifica
sibill flows get flow_abc123 -d doc_abc123

# Aggiorna lo stato di pagamento
sibill flows update flow_abc123 -d doc_abc123 \
  --payment-status PAID \
  --payment-date 2025-01-15

5. Export dati per contabilita

# Esporta tutte le transazioni di marzo in JSON
sibill --json transactions list --filter-date 2025-03-01 > transazioni_marzo.json

# Esporta le fatture emesse
sibill --json documents list \
  --filter-direction ISSUED \
  --filter-type INVOICE \
  > fatture_emesse.json

# Esporta le controparti in CSV
sibill --json counterparts list \
  | jq -r '.data[] | [.company_name, .vat_number, .tax_number, .city] | @csv' \
  > controparti.csv

Uso in CI/CD

Usa la variabile d'ambiente SIBILL_API_KEY per evitare di salvare credenziali su disco:

# Esempio GitHub Actions
name: Esporta dati Sibill
on:
  schedule:
    - cron: '0 8 * * 1'  # ogni lunedi alle 8:00

jobs:
  export:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/setup-node@v4
        with:
          node-version: 20

      - name: Esporta transazioni settimanali
        env:
          SIBILL_API_KEY: ${{ secrets.SIBILL_API_KEY }}
        run: |
          npx sibill-cli config set-company ${{ vars.SIBILL_COMPANY_ID }}
          npx sibill-cli --json transactions list \
            --filter-date $(date -d '7 days ago' +%Y-%m-%d) \
            > transazioni.json

      - uses: actions/upload-artifact@v4
        with:
          name: transazioni-settimanali
          path: transazioni.json

# In uno script generico
export SIBILL_API_KEY=sk-la-tua-api-key
sibill config set-company comp_abc123
sibill --json transactions list > output.json

Risoluzione problemi

Error: API key not configured

Non hai impostato la chiave API. Esegui:

sibill config set-key sk-la-tua-api-key

Oppure imposta la variabile d'ambiente:

export SIBILL_API_KEY=sk-la-tua-api-key

Error: No company ID provided and no default set

Il comando richiede un ID azienda ma non ne hai impostato uno predefinito. Soluzioni:

# Passa l'ID direttamente
sibill accounts list -c comp_abc123

# Oppure imposta un'azienda predefinita
sibill config set-company comp_abc123

Error: this command requires beta mode

Stai tentando un'operazione di scrittura (create, update, delete, share) senza la modalita beta attiva:

sibill config set-beta on

Errore 401 — Unauthorized

La chiave API non e valida o e scaduta. Verifica la configurazione:

sibill config show

Se necessario, imposta una nuova chiave:

sibill config set-key sk-nuova-chiave

Errore 404 — Not Found

La risorsa richiesta non esiste o appartiene a un'altra azienda. Verifica:

1. L'ID della risorsa sia corretto
2. Stai usando l'azienda giusta (sibill config show)
3. La risorsa esista ancora (sibill <risorsa> list)

L'output e troncato o mancano dati

L'API usa la paginazione. Per impostazione predefinita restituisce una pagina di risultati. Usa --page-size per controllare il numero di elementi e --cursor per navigare:

sibill transactions list --page-size 100

Come vedere il JSON grezzo dell'API?

Usa --json prima del comando (non dopo):

# Corretto
sibill --json transactions list

# Sbagliato
sibill transactions list --json

Licenza

Vedi LICENSE per i dettagli.