Altoviz CLI is a command-line interface tool designed to streamline financial management tasks such as customer, invoice, quote, product, and receipt handling directly from the terminal. Built for both human users and automation processes (including LLMs), it simplifies interactions with the Altoviz SaaS platform for small businesses and freelancers.
Key Features:
Multi-Format Output: Supports table, JSON, YAML, Markdown, CSV, TSV, and other formats to cater to diverse needs.
Secure Credential Management: Stores API keys securely using OS keychains (macOS Keychain, Windows Credential Manager, Linux Secret Service).
Profile-Based Switching: Allows users to manage multiple environments or companies with ease via profiles.
Scriptable and Automation-Friendly: Enables seamless integration into workflows, including piped JSON input and column customization.
Audience & Benefit:
Ideal for small businesses, freelancers, and automation developers seeking a reliable invoicing and accounting solution. Altoviz CLI empowers users to manage finances efficiently from the terminal or via automated scripts, reducing manual effort and errors while maintaining flexibility in output formats.
Available via winget for Windows users, the tool is designed with a focus on ease of use and integration into existing workflows.
Command-line interface for Altoviz — the French SaaS invoicing & accounting platform for small businesses and freelancers.
Built for humans, automation processes and LLMs alike.
Overview
altoviz is a self-contained CLI that wraps the Altoviz REST API. It lets you manage customers, suppliers, invoices, quotes, products, receipts, and more — directly from the terminal or from an LLM agent.
Key highlights:
No runtime required — single binary for macOS, Linux, and Windows
Manual install: download the zip from Releases, extract and have fun.
Quick Start
# Store your API key (saved to OS keychain)
altoviz config create
# Add a named profile for a test company with interactive experience
altoviz config create my_test_company
# Add a named profile for a test company with args
altoviz config create my_test_company --api-key={YOUR_API_KEY}
# — or pass it inline / via environment variable
export ALTOVIZ_CLI_API_KEY=your_key_here
# — or pass it as an arg on every command
altoviz invoice list --api-key={YOUR_API_KEY}
# List invoices
altoviz invoice list
# List invoices as JSON
altoviz invoice list --json
# List invoices as Markdown
altoviz invoice list --output markdown
# Fetch a single customer as colored JSON
altoviz customer get 42 --cjson
# Use a specific profile
altoviz --profile staging customers list
# Export this year's invoices to CSV
altoviz export invoices --from 2026-01-01 --to 2026-12-31
Commands
General
Command
Description
altoviz about
Display version, website, and copyright
altoviz version [--check]
Print current version; --check compares with the latest GitHub release
altoviz completion
Emit a completion script for bash, zsh, fish, or pwsh
altoviz commands
List every command with its options, types and allowed values, as data
altoviz schema [entity] [op]
Show the JSON request body for a create/update command
Discovery (for scripts and LLM agents)
commands and schema let a tool learn the whole CLI without scraping --help. Both work offline, before any API key is configured.
altoviz commands --toon # the entire command surface, one call
altoviz schema # list every documented request body
altoviz schema invoice create --json # the invoice-create body, with required fields
altoviz schema invoice create --json | jq '.example' > body.json
altoviz invoice create -f body.json # round-trips straight back in
Configuration
Command
Description
config list
List all configured profiles
config get [profile]
Display a profile's endpoint and key status
config create [profile]
Add or update a profile (interactive or via flags)
config delete [profile]
Remove a profile and its stored credentials
config reset
Delete all profiles and credentials
config create accepts --api-key and --endpoint flags for non-interactive use. When run interactively it prompts with a link to app.altoviz.com/go/settings/apis.
Customers
Command
Description
customer list
List customers (supports --query, --order-by, --all-pages)
customer get
Get a customer by ID
customer find
Find a customer by --email, --number, or --internal-id
customer create
Create a customer (flags or --file )
customer update
Update a customer (merges flag changes onto existing record)
customer delete
Delete a customer (prompts for confirmation)
Suppliers
Command
Description
supplier list
List suppliers
supplier get
Get a supplier by ID
supplier find
Find a supplier by --email or --internal-id
supplier create
Create a supplier (--name, --payment-method, person fields, or --file)
supplier update
Update a supplier
supplier delete
Delete a supplier
Contacts
Command
Description
contact list
List contacts
contact get
Get a contact by ID
contact find
Find by --email or --internal-id
contact create
Create a contact (--company-name, --function, --service, person fields, or --file)
contact update
Update a contact
contact delete
Delete a contact
Colleagues
Command
Description
colleague list
List colleagues
colleague get
Get a colleague by ID
colleague find
Find by --email, --number, or --internal-id
colleague create
Create a colleague (--name, --is-partner, --user-id, person fields, or --file)
colleague update
Update a colleague
colleague delete
Delete a colleague
Products
Command
Description
product list [--family-id]
List products, optionally filtered by family
product get
Get a product by ID
product find
Find by --reference or --internal-id
product create
Create a product (--name, --unit-price, --type, …, or --file)
product update
Update a product
product delete
Delete a product
product family list
List product families
product family get
Get a product family
product family create
Create a product family (--file required)
product family delete
Delete a product family
Invoices
Command
Description
invoice list
List invoices (--from, --to, --customer-id, --status)
invoice get
Get an invoice by ID
invoice find
Find by --number or --internal-id
invoice create
Create an invoice (--file required)
invoice update
Update a draft invoice
invoice delete
Delete an invoice
invoice finalize
Finalize (issue) an invoice
invoice send
Send an invoice by email
invoice mark-paid
Mark an invoice as paid
invoice download
Download the invoice PDF (--file )
Quotes
Command
Description
quote list
List quotes
quote get
Get a quote by ID
quote find
Find by --number or --internal-id
quote create
Create a quote (--file required)
quote delete
Delete a quote
quote send
Send a quote by email
quote download
Download the quote PDF (--file )
Credit Notes
Command
Description
credit list
List credit notes
credit get
Get a credit note by ID
credit find
Find by --number or --internal-id
credit create
Create a credit note (--file required)
credit update
Update a draft credit note
credit delete
Delete a credit note
credit finalize
Finalize a credit note
credit send
Send a credit note by email
credit mark-refunded
Mark a credit note as refunded
credit download
Download the credit note PDF (--file )
Receipts
Command
Description
receipt list
List receipts
receipt get
Get a receipt by ID
receipt find
Find by --internal-id
receipt create
Create a receipt (--file required)
receipt update
Update a receipt
receipt delete
Delete a receipt
Webhooks
Command
Description
webhook list
List webhooks
webhook create
Create a webhook (--name, --url, --type, optional --secret-key, or --file)
webhook delete
Delete a webhook by numeric ID or URL
Exports
All export commands accept --from / --to (date range), --format (Excel, EuropeanCsv, AmericanCsv, Tsv, Json, Markdown), --sheets (Summary, Detail, Analysis, All), and --out to save to disk.
Export type
Description
export invoices
Sales invoices
export quotes
Sales quotes
export credits
Credit notes
export products
Product catalog
export customers
Customer list
export suppliers
Supplier list
export receipts-book
Receipts journal
export expenses-book
Expenses journal
export bank-transactions
Bank transactions (requires --id)
export expense-charges
Expense charges
export expense-reports
Expense reports (--colleague-id)
export settlements
Settlements
export commitments
Commitments
Statistics
Command
Description
stats by-month [--year]
Monthly breakdown for a given year (default: current year)
stats turnover
Sales turnover vs previous period
stats evolution [--by] [--years]
Turnover evolution by customer, supplier, product, or colleague
Reference Data
Command
Description
vats
List VAT rates
units
List units of measure
classifications [--type]
List classifications, optionally filtered by type
settings
Get account settings
Output Formats
Use --output / -o on any command, or the shorthand flags below:
TOON (Token-Oriented Object Notation) is an
indentation-based format that packs uniform arrays into a compact tabular layout, making
it noticeably cheaper than JSON for feeding data to LLMs. It is also accepted as --file
input (see below).
Control which columns appear with --columns id|name|email (pipe-separated dot-paths).
Global Options
These options are available on every command:
Option
Short
Description
--profile
-p
Profile to use (env: ALTOVIZ_CLI_PROFILE, default: default)
--api-key
Override API key (env: ALTOVIZ_CLI_API_KEY)
--endpoint
Override base URL (env: ALTOVIZ_CLI_ENDPOINT, default: https://api.altoviz.com)
--output
-o
Output format (see above)
--json
Shorthand for --output json
--yaml
Shorthand for --output yaml
--cjson
Shorthand for --output colored-json
--md
Shorthand for --output markdown
--csv
Shorthand for --output csv-us
--tsv
Shorthand for --output tsv
--toon
Shorthand for --output toon
--columns
Pipe-separated dot-path column list
--file
-f
JSON/YAML/TOON input file (by extension), or - for stdin (JSON)
--verbose
Print HTTP request/response to stderr
--no-color
Disable ANSI colors
--quiet
-q
Suppress all output except errors
--yes
-y
Skip confirmation prompts (required for destructive commands when non-interactive)
--show-time
Include time component in date columns
Setting ALTOVIZ_CLI_AGENT=1 forces machine-readable JSON errors even at a terminal. Output format still follows --output / ALTOVIZ_CLI_OUTPUT (default table); set ALTOVIZ_CLI_OUTPUT=toon for compact, parseable output.
Exit Codes
Code
Meaning
0
Success
1
General failure (network error, server error)
2
Usage error (invalid arguments or options)
3
Resource not found (HTTP 404)
4
Permission denied (HTTP 401 / 403)
5
Conflict (HTTP 409 — resource already exists)
Error output
Errors are always written to stderr; stdout only ever carries command data. When stderr is not a terminal (piped, captured, or when ALTOVIZ_CLI_AGENT=1 is set), each error is a single JSON line with a stable machine-readable code, and a hint describing the next step:
{
"error": true,
"code": "not_found",
"statusCode": 404,
"message": "API request failed with HTTP 404.",
"hint": "The id does not exist. Use 'altoviz list' or 'altoviz find' to locate it."
}
Codes include missing_config, unauthorized, not_found, conflict, validation_error, bad_output_type, input_error, confirmation_required, network_error, and timeout. At an interactive terminal the same errors are shown as coloured prose instead.
Non-interactive safety
Confirmation prompts (delete, finalize, mark-paid) require a real terminal on stdin. When there is none — a script, a pipe, an agent — a destructive command without --yes/-yrefuses and exits 2 (confirmation_required) rather than proceeding silently. Pass --yes to confirm non-interactively.
Configuration
Profiles
The CLI supports named profiles so you can switch between different environments or accounts:
# Add or update the default profile
altoviz config create
# Add a staging profile
altoviz config create staging --endpoint https://api.staging.altoviz.com
# Use a profile for a single command
altoviz --profile staging invoice list
# Set the active profile for the session
export ALTOVIZ_CLI_PROFILE=staging
Credential storage
API keys are stored securely in the OS keychain — no plain text on disk:
Platform
Store
macOS
Keychain
Windows
Credential Manager
Linux
Secret Service (libsecret)
WSL
Windows Credential Manager
If no keychain is available, the key falls back to the config file with a warning.
Credential resolution order
For each command, credentials are resolved in priority order:
-blue){kind=icon}
