alegracli

README

alegra-cli

A fast, scriptable command-line interface for the Alegra accounting API — manage contacts, invoices, items, payments, taxes, and the full Alegra resource surface from your terminal, with table/json/yaml/csv output, named profiles, a dry-run mode, and a built-in MCP server.

Built in Go with a small generic core: a typed API client plus one thin file per resource.

Unofficial. Not affiliated with Alegra. Uses the public API at https://api.alegra.com/api/v1.

Install

# Homebrew (macOS/Linux)
brew install jjuanrivvera/alegra-cli/alegra-cli

# Scoop (Windows)
scoop bucket add alegra-cli https://github.com/jjuanrivvera/scoop-alegra-cli
scoop install alegra-cli

# Docker
docker run --rm ghcr.io/jjuanrivvera/alegra-cli:latest version

# From source
go install github.com/jjuanrivvera/alegra-cli/cmd/alegra@latest

# Or build locally
make build && ./bin/alegra --help

Linux .deb/.rpm/.apk packages are attached to each release. Release archives, packages, and the Homebrew/Scoop installs all ship shell completions (bash/zsh/fish). Releases are also SBOM-attested and the checksums are signed with cosign (keyless); see RELEASING.md for verification.

Authenticate

Alegra uses HTTP Basic auth with your account email and an API token (Alegra → Configuración → Integraciones → API).

# Friendliest first run: prompts for email + token, verifies them, auto-detects
# your country, and saves a profile — all in one step
alegra init

# Or sign in directly: token is stored in your OS keyring, never written to disk
alegra auth login

# Or via environment variables (great for CI / scripts)
export ALEGRA_EMAIL="you@example.com"
export ALEGRA_TOKEN="your-api-token"

alegra auth status   # verifies against /users/self

Usage

# List the first page of contacts as a table
alegra contacts list

# Filter + paginate, fetch every page
alegra contacts list --type client --all --limit 30

# Get one record as JSON
alegra invoices get 12 -o json

# Create from a JSON file (or stdin with -f -)
alegra invoices create -f new-invoice.json

# Create with inline fields (values parsed as JSON when valid)
alegra contacts create --set name="Acme S.A.S" --set 'type=["client"]'

# Custom actions
alegra invoices void 12
alegra invoices email 12 --set 'emails=["client@acme.com"]'
alegra payments stamp 88

# See the exact request without sending it
alegra invoices list --status open --dry-run

Filtering, counting & pagination

# Natural date ranges (this-month, last-month, 7d, 3m, YYYY-MM-DD, ...)
alegra invoices list --status open --since this-month
alegra payments list --type in --since 7d

# Just the count (uses the API's metadata total — no full fetch)
alegra invoices list --status open --count

# Escape hatch: pass ANY Alegra query parameter the CLI doesn't expose as a flag
alegra contacts list --param identification=900123456 --param order_field=name

# Fetch every page
alegra items list --all

Power features

alegra doctor                              # diagnose config, auth, plan, rate limit
alegra alias set unpaid "invoices list --status open --all"
alegra unpaid --client-id 12               # run the alias (+ extra args)
alegra contacts import -f clients.csv --map 'Name=name,NIT=identification.number'
alegra invoices export --param status=open > receivables.csv
alegra invoices create -f invoice.json --draft   # country pre-flight validated
alegra invoices emit --all                 # stamp drafts, auto-chunked, idempotent
alegra catalog units --country mexico      # offline per-country reference catalogs

Pre-flight validation runs per detected country (CO/MX/PE/CR); skip it with --no-validate. Check for upgrades with alegra version --check.

Output formats

-o table (default), -o json, -o yaml, -o csv. Pick columns with --columns:

alegra items list -o csv --columns id,name,price > items.csv
alegra contacts list --columns id,name,email

Shell completion

Completion for bash/zsh/fish/PowerShell is data-aware — Tab completes your actual records, not just command names:

alegra invoices get <Tab>            # live invoice IDs, labelled with status
alegra invoices list --status <Tab>  # open  closed  draft  void
alegra contacts get --columns <Tab>  # that resource's columns (comma-aware)
alegra --profile <Tab>               # your configured profiles

Release archives and the Homebrew/Scoop/.deb/.rpm/.apk installs bundle the scripts; otherwise source <(alegra completion bash) (or zsh/fish). Full setup: docs › Shell Completion.

Profiles

Manage multiple Alegra accounts:

alegra config set-profile --name prod --email you@biz.com
alegra auth login --profile prod
alegra --profile prod invoices list
alegra config use prod          # set the default

Config lives at ~/.alegra-cli/config.yaml (tokens stay in the keyring).

MCP server

Expose the entire CLI to AI agents over the Model Context Protocol:

alegra mcp           # see MCP subcommands

Resources

Full Alegra v1 surface — each with list/get/create/update/delete plus resource-specific actions. A few are read-only or restricted (e.g. recurring-payments is read-only; reconciliations has no separate update; categories has no delete):

contacts, items, item-categories, invoices, global-invoices, recurring-invoices, credit-notes, income-debit-notes, estimates, remissions, transportation-receipts, bills, debit-notes, purchase-orders, payments, recurring-payments, taxes, retentions, terms, currencies, number-templates, bank-accounts, reconciliations, cost-centers, journals, categories, additional-charges, sellers, company, users, warehouses, warehouse-transfers, inventory-adjustments, inventory-adjustment-numerations, price-lists, custom-fields, variant-attributes, webhook-subscriptions, reports.

Plus catalog (aliases catalogs/reference) — offline per-country reference data (units of measure, identification types, tax types, payment methods, …), and validate for pre-flight document checks.

Run alegra <resource> --help for actions and filters.

Use it from your AI agent (skill)

alegra-cli ships an agent skill that teaches AI coding agents (Claude Code, Cursor, Codex, Gemini CLI, Windsurf, Copilot, …) how to drive it. Install the skill across every agent you have with one command:

npx skills add jjuanrivvera/alegra-cli

Or use one of the built-in / native paths:

alegra skills install --global              # write the bundled skill (no Node needed)
alegra skills install --agent cursor        # target a specific agent

# Native Claude Code plugin:
#   /plugin marketplace add jjuanrivvera/alegra-cli
#   /plugin install alegra-cli@alegra

The skill wraps this binary, so install the CLI (above) and authenticate first. For structured tool access (Claude Desktop, etc.) the CLI is also an MCP server: claude mcp add alegra -- alegra mcp start (or wire it automatically with alegra mcp claude enable).

Guides & recipes

The documentation site has more than flag references — it's full of real accounting recipes:

• Cookbook — copy-paste commands for everyday tasks
• Invoice → Cash — a full sales cycle: client → item → invoice → email → payment
• Electronic Invoicing — the draft→open→stamp lifecycle, numberTemplate/stamp, and per-country fields (CO/MX/PE/CR)
• Expenses & Purchases — suppliers, bills, purchase orders, outgoing payments
• Reporting & Month-End — totals, aging, and closing snapshots
• Productivity Features — doctor, aliases, date ranges, counts, validation
• Automation & Scripting — CSV bulk ops, cron, CI, MCP agents
• Errors & Rate Limits · FAQ

Configuration reference

Env var	Meaning
ALEGRA_EMAIL	Account email (Basic auth user)
ALEGRA_TOKEN	API token (Basic auth password)
ALEGRA_BEARER_TOKEN	OAuth bearer token (marketplace apps)
ALEGRA_BASE_URL	Override the API base URL
ALEGRA_PROFILE	Active profile name
ALEGRA_OUTPUT	Default output format
ALEGRA_CONFIG	Override the config file path

Global flags: --profile, -o/--output, --base-url, --columns, --requests-per-second, --dry-run, --show-token, -v/--verbose.

Architecture

cmd/alegra/         entry point
commands/           cobra command tree (one file per resource, init-registered)
  root.go           global flags, client construction, output rendering
  generic.go        generic list/get/create/update/delete + action builders
internal/
  api/              typed client + generic Resource[T] + one file per resource
    client.go       auth, retries, rate limiting, dry-run
    resource.go     generic CRUD over the REST collection
    pagination.go   start/limit offset pagination
  config/           YAML profiles + env overrides
  auth/             OS keyring token storage
  output/           table / json / yaml / csv rendering
  version/          build metadata
tools/gendocs/      command reference generator (MkDocs)

Each resource is a thin typed wrapper: a Go struct + a one-line Client accessor + a small command registration. The generic core handles HTTP, auth, retries, adaptive rate limiting, pagination, and output.

Development

make dev            # fmt + vet + build
make test           # run tests
make lint           # golangci-lint
make check          # full local quality gate
make docs-serve     # preview the docs site

License

MIT — see LICENSE.

Documentation

Overview

Package alegracli embeds the agent-skill assets (SKILL.md + references) into the binary so `alegra skills install` can write them into an AI agent's skills directory. The same files under skills/alegra-cli/ are what `npx skills add jjuanrivvera/alegra-cli` and the Claude Code plugin consume.

Index

• Constants
• Variables

Constants

const SkillName = "alegra-cli"

SkillName is the directory the skill installs into within an agent's skills dir.

Variables

var SkillFS = mustSub(embedded, "skills/"+SkillName)

SkillFS is rooted at the skill directory, so it contains SKILL.md and references/ at its top level.