Altoviz CLI

Command-line interface for Altoviz — the French SaaS invoicing & accounting platform for small businesses and freelancers.
Built for humans, automation processes and LLMs alike.

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
• 10 output formats — table (default), JSON, YAML, TOON, Markdown, CSV, TSV
• Shell completions — bash, zsh, fish, PowerShell
• Signed & notarized binaries — macOS builds are signed with an Apple Developer ID and notarized; Windows builds are signed with Azure Trusted Signing
• Secure credential storage — API key stored in the OS keychain (macOS Keychain, Windows Credential Manager, Linux Secret Service)
• Multiple profiles — switch between environments with --profile
• Scriptable — pipe JSON in with --file -, control columns with --columns, page with --all-pages

brew trust altoviz/tap && brew install altoviz/tap/altoviz

# Homebrew
brew trust altoviz/tap && brew install altoviz/tap/altoviz

# One-liner installer
curl -fsSL https://raw.githubusercontent.com/altoviz/cli/main/install.sh | sh

# Debian / Ubuntu
sudo apt install ./altoviz_1.0.2_amd64.deb

# Fedora / RHEL
sudo rpm -i altoviz-1.0.2-1.x86_64.rpm

## WinGet
winget install Altoviz.CLI

## Chocolatey
choco install altoviz

Manual install: download the zip from Releases, extract and have fun.

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

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.

All export commands accept --from / --to (date range), --format (Excel, EuropeanCsv, AmericanCsv, Tsv, Json, Markdown), --sheets (Summary, Detail, Analysis, All), and --out <file> to save to disk.

Use --output / -o on any command, or the shorthand flags below:

Additional --output values: compact-json, csv-eu (; separator).

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).

These options are available on every command:

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.

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 <entity> list' or 'altoviz <entity> 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.

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/-y refuses and exits 2 (confirmation_required) rather than proceeding silently. Pass --yes to confirm non-interactively.

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

API keys are stored securely in the OS keychain — no plain text on disk:

If no keychain is available, the key falls back to the config file with a warning.

For each command, credentials are resolved in priority order:

1. --api-key / --endpoint CLI flags
2. ALTOVIZ_CLI_API_KEY / ALTOVIZ_CLI_ENDPOINT environment variables
3. OS keychain (keyed by profile name)
4. ~/.altoviz/cli.yaml config file

~/.altoviz/cli.yaml uses an INI-style format with one section per profile:

[default]
apikey={YOUR_API_KEY}

[my_other_company]
apikey={YOUR_OTHER_API_KEY}

API keys are omitted from the file when the OS keychain is available.

• Website: altoviz.com
• API documentation: developer.altoviz.com
• API key settings: app.altoviz.com/go/settings/apis
• Releases: github.com/altoviz/cli/releases

_{© 2024–2026 Altoviz}