# Aegro CLI

Command-line interface for the [Aegro](https://aegro.com.br) agricultural management API.

[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![PyPI](https://img.shields.io/pypi/v/aegro.svg)](https://pypi.org/project/aegro/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

---

## Install

```bash
# pipx (recommended)
pipx install aegro

# uv
uv tool install aegro

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

```powershell
# Windows — pipx (recommended)
pipx install aegro

# Windows — uv
uv tool install aegro

# Windows — pip
pip install aegro
```

> Credentials are stored in `%LOCALAPPDATA%\aegro\`.

> **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:

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

---

## Quick Start

```bash
# 1. Authenticate
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:

```bash
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
```

---

## Usage Examples

### Human workflow

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

```bash
# 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 project includes guided workflows for AI assistants in `.claude/skills/`:

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

Credential resolution priority:

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, `%LOCALAPPDATA%\aegro\` on Windows) — interactive setup via `aegro auth login`

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

# Option 2: Interactive login (saves to OS-native config directory)
aegro auth login --farm-name "Fazenda Norte" --api-key "aegro_key1"
```

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

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

---

## Development

```bash
# 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](https://aegro.com.br) — Agricultural management platform
- [Typer](https://typer.tiangolo.com/) — CLI framework
- [PyPI: aegro](https://pypi.org/project/aegro/) — Package page

---

## License

[MIT](LICENSE)
