aegro 0.11.0

CLI for Aegro agricultural management API

Aegro CLI

Command-line interface for the Aegro agricultural management API.

---

Install

# pipx (recommended)
pipx install aegro

# uv
uv tool install aegro

# Homebrew (macOS)
brew tap aegro/tap
brew install aegro

# Windows — pipx (recommended)
pipx install aegro

# Windows — uv
uv tool install aegro

# Windows — pip
pip install aegro

Credentials are stored in %USERPROFILE%\.aegro\ (outside AppData on purpose: packaged apps like Claude Desktop and Store Python run under MSIX filesystem virtualization, which would silently redirect AppData writes to a per-app shadow folder). Files from the previous location (%LOCALAPPDATA%\aegro\) are migrated automatically on first run.

WSL: Inside WSL, follow the Linux instructions. WSL and Windows credentials are stored separately — do not mix installations.

OneDrive/Dropbox: Avoid pointing AEGRO_CONFIG_DIR to cloud-synced folders, as file locking may cause intermittent errors.

For development:

git clone https://github.com/aegro/tool-aegro-cli.git
cd tool-aegro-cli
uv sync
uv run aegro --help

---

Quick Start

# 1. Authenticate — opens the browser for Aegro login (email/password, OTP or Google)
aegro auth login

# Alternative: static API key (CI, agents, fallback)
aegro auth login --farm-name "Fazenda Sul" --api-key "aegro_abc123..."

# 2. Select a farm
aegro farms list
aegro farms select "Fazenda Sul"

# 3. Start working
aegro crops list --start-date 2025-01-01 --end-date 2025-12-31
aegro financial installments --status PENDING
aegro stock items --output table

---

Commands

Group	Commands	Domain
auth	login, status, logout	Authentication
farms	list, select, info	Farm management
crops	get, list, prorate, harvest-discounts, prorates, glebes	Harvest management
activities	get, list, plan, realizations, get-plan, get-realization, create-plan	Activity planning
financial	bill, installment, installments, create/update/delete-installment, realize	Accounts payable/receivable
stock	item, location, items, locations, logs, log, transfer, entry, removal	Inventory
elements	get, list, create-defensive/fertilizer/item/seed/service, set-categories	Inputs/supplies
assets	get, list, create-machine/vehicle/garner/immobilized/pivot/weather-station	Equipment
fuel-supplies	get, list, create, update	Fuel management
maintenances	get, list, create, update	Maintenance records
harvest-logs	get, create	Harvest records
bank-accounts	get, list, create	Bank accounts
companies	get, list, create	Suppliers/vendors
fin-categories	get, list, create, subcategories	Chart of accounts
catalogs	list, element-keys, elements	Catalog lookups
tags	get, list, create	Tags/labels
weather	get, create	Weather data
purchase-orders	get, list, create	Purchase orders
glebes	get, list	Farm fields
crop-glebes	get, list	Crop fields

---

Output Formats

All commands support three output formats:

aegro crops list --output json    # JSON (default, for LLMs/scripts)
aegro crops list --output table   # Rich table for humans
aegro crops list --output csv     # CSV export

---

Safe Mode for Mutations

Agents and automation should enable safe mode before running workflows that may create, update, delete, realize, transfer, enter, or remove data:

export AEGRO_SAFE_MODE=1
aegro purchase-orders create ... --dry-run   # Preview request; no API mutation
aegro purchase-orders create ... --execute   # Execute after validating payload

--dry-run prints the target farm, method, endpoint, payload, and local warnings without calling the Aegro API. With AEGRO_SAFE_MODE=1, mutating commands are blocked unless --execute is passed. List/filter/get commands continue to work.

---

Usage Examples

Human workflow

# Morning overview
aegro farms select "Fazenda Norte"
aegro crops list --output table
aegro financial installments --status PENDING --due-date-start 2025-03-01 --output table
aegro stock items --output table

# Register a fuel supply
aegro fuel-supplies create --asset-key K --date 2025-03-13 --quantity 150 --unit L --cost 900

# Check harvest
aegro harvest-logs get <key>

LLM/Agent workflow

# Agents use JSON output (default) for structured data
aegro crops list --start-date 2025-01-01 --end-date 2025-12-31
aegro activities list --crop-key <key>
aegro stock items
aegro financial installments --status PENDING

---

AI Skills

The source of truth for public Aegro skills is the Aegro-owned Claude plugin repository aegro/skills. Internal harness skills live separately in the private aegro/skills-internal repository.

This CLI embeds a generated snapshot of aegro/skills in aegro/_skills/ for PyPI installs. Do not edit embedded skills directly; update aegro/skills and then run:

python scripts/sync-skills.py <version>

/plugin marketplace add aegro/skills
/plugin install aegro-skills@aegro-skills

Users who install the CLI from PyPI can also install the embedded skills:

pip install --upgrade aegro
aegro skills install --force

Domain skills (personas)

Skill	Purpose
aegro-agronomo	Agronomic domain — crops, fields, activities, harvests, weather, inputs
aegro-estoquista	Stock domain — items, locations, movements, catalogs, elements
aegro-financeiro	Financial domain — bills, installments, categories, bank accounts, companies
aegro-operacional	Operational domain — farms, auth, tags, cross-domain orchestration
aegro-patrimonial	Asset domain — machines, vehicles, fuel supplies, maintenances

Workflow skills

Skill	Purpose
aegro-visao-geral	Farm overview dashboard
aegro-fechamento-safra	Crop season closing checklist
aegro-lancamento-financeiro	Financial entry guide
aegro-reconciliacao-estoque	Stock reconciliation
aegro-monitoramento-pragas	Pest monitoring
aegro-analise-rentabilidade	Profitability analysis
aegro-cadastro-patrimonio	Asset registration

---

Configuration

Authentication

Two authentication modes:

• OAuth login (default) — aegro auth login opens the browser for the regular Aegro login (email/password, e-mail code or Google). The CLI stores the user session (access + refresh token) and discovers the user's farms automatically. The session renews itself; no key handling needed.
• API key — aegro auth login --api-key ... stores a static per-farm key. Best for CI/CD, scripts and agents.

API key resolution priority (when both modes have credentials for a farm, the API key wins):

1. AEGRO_FARMS env var (JSON) — for CI/CD and scripts
2. AEGRO_FARMS_FILE env var (path) — for Docker/K8s secrets
3. Config directory (~/.config/aegro/ on Linux, ~/Library/Application Support/aegro/ on macOS, %USERPROFILE%\.aegro\ on Windows) — interactive setup via aegro auth login

# Option 1: Browser login (recommended for humans)
aegro auth login

# Option 2: Environment variable
export AEGRO_FARMS='{"Fazenda Norte": "aegro_key1", "Fazenda Sul": "aegro_key2"}'

# Option 3: Static API key (saves to OS-native config directory)
aegro auth login --farm-name "Fazenda Norte" --api-key "aegro_key1"

# Inspect the session (method, user, expiry, farms)
aegro auth status

# Remove local credentials (revokes the OAuth session server-side)
aegro auth logout             # everything
aegro auth logout --env staging   # one environment only

Active Farm Resolution

With credentials configured, the active farm for each command is resolved in this order:

1. AEGRO_ACTIVE_FARM env var — scoped to the current process/session
2. state.json written by aegro farms select — global per machine

AEGRO_ACTIVE_FARM is the recommended approach for orchestrated multi-farm contexts (e.g. Claude Cowork operating several client accounts in parallel sessions). It prevents one session's farms select from contaminating another's because env vars are process-scoped, while state.json is shared.

# Scope an entire session to one farm (no 'farms select' needed)
AEGRO_ACTIVE_FARM="Fazenda Norte" aegro assets list

# Confirm which farm is active and where it came from
aegro farms list    # each entry now has a 'source' field: "env" | "state" | null

Environment Variables

Variable	Default	Purpose
AEGRO_API_BASE_URL	https://app.aegro.com.br	Aegro API base URL
AEGRO_FARMS	—	JSON map of farm name → API key
AEGRO_FARMS_FILE	—	Path to JSON credentials file
AEGRO_ACTIVE_FARM	—	Active farm for this session; takes precedence over farms select
AEGRO_CONFIG_DIR	—	Override config directory path
AEGRO_SAFE_MODE	—	Blocks mutating commands unless --execute; use --dry-run to preview
AEGRO_OAUTH_CLIENT_ID	aegro-cli	OAuth client id (AEGRO_OAUTH_CLIENT_ID_<ENV> for other envs)

---

Development

# Install dependencies
uv sync

# Run tests
uv run pytest -v

# Lint
uv run ruff check aegro/ tests/

# Format
uv run ruff format aegro/ tests/

---

Links

• Aegro — Agricultural management platform
• Typer — CLI framework
• PyPI: aegro — Package page

---

License

MIT