# Agent CLI

URL: https://theelena.me/docs/avileo/tiendas/agent-cli
Text: https://theelena.me/docs/avileo/tiendas/agent-cli.txt
Description: Operate Avileo through durable, human-approved agent mutations.
Context: environment=production; apiBaseUrl=https://tienda.theelena.me; activation=active; rubro=tiendas

# Agent CLI

## Instalación y conexión

La CLI pública está verificada en npm: `@tarileo/avileo-catalog-cli@0.3.4`
incluye el contrato de selección de origen. Ejecútala sin instalación global:

```sh
npx --yes @tarileo/avileo-catalog-cli@0.3.4 auth login --base-url https://tienda.theelena.me --json
```

Abre el enlace de verificación, inicia sesión en Avileo y elige un modo: **Solo
lectura** o **Lectura y mutación**. La CLI imprime solo la URI de verificación,
el código de usuario y el origen fijado; guarda la Agent Key localmente con
permisos `0600` y nunca la imprime ni la coloca en una URL. Usa
`auth status --json` para revisar el origen fijado sin revelar la clave y
`auth logout --json` para retirar la credencial local; la revocación remota es
una acción de Avileo.

No uses una versión anterior de la CLI como sustituto: su contrato de
credenciales y destino es distinto. Si el host aporta un checkout o wrapper
local compatible y verificado, consérvalo y confirma que el origen guardado
coincide con el seleccionado antes de acceder al negocio. No cambies de
despliegue ni reenvíes una clave ante un conflicto o una credencial sin origen.
Sin un cliente compatible, detente en la lectura de documentación: no solicites
vinculación ni credenciales.

## Evalúa el perfil y el catálogo

```sh
avileo business profile show --json
avileo catalog product list --limit 25 --offset 0 --json
```

El perfil devuelve campos, valores reales, faltantes y porcentaje de
completitud según el rubro. Para mejorarlo, prepara únicamente valores
confirmados, revisa primero el diff local y luego crea la propuesta:

```sh
avileo business profile update --from profile-update.json --json
avileo business profile update --from profile-update.json --apply --json
# Después de aprobar la propuesta en Avileo
avileo operation apply "$APPROVAL_ID" --json
```

Una evaluación puede recomendar cambios sin aplicarlos. No confundas una
recomendación con autorización.

## Read and mutate modes

A read key can inspect resources. A mutate key can create proposals, but every
effective write still requires approval in Avileo.

```sh
# Local preview
avileo catalog product update "$PRODUCT_ID" --from changes.json --json

# Create proposal; returns approvalUrl
avileo catalog product update "$PRODUCT_ID" --from changes.json --apply --json

Capture the complete JSON response and copy its literal `.data.approvalUrl`.
Never rebuild the link from the operation ID or replace its origin; local,
preview and production environments can advertise different app hosts.

# Execute only after approval
avileo catalog product update "$PRODUCT_ID" \
  --from changes.json --apply --approval-id "$APPROVAL_ID" --json
```

The same flow applies to products, variants, categories, tags, assets,
inventory and import apply. `catalog import preview` remains direct and safe.

## Operations

```sh
avileo operation status "$APPROVAL_ID" --json
avileo operation apply "$APPROVAL_ID" --json
```

## Create a Client Key for a web

```sh
avileo catalog-key create --name "Web del cliente" --json
# Approve the returned URL
avileo operation apply "$APPROVAL_ID" --json
```

The successful apply response returns the new public `avileo_pk_...` once. It
may be saved as `AVILEO_CLIENT_KEY` in the customer web project. Never save the
secret `AVILEO_AGENT_API_KEY` there.

For the underlying server-to-server contract, see [Agent HTTP API](/docs/avileo/tiendas/agent-http).

## Output and redaction

Success uses stdout and failure uses stderr, each with one versioned JSON
envelope. Agent keys, API keys, authorization, tokens, passwords and secrets
are redacted. The only intentional exception is the one-shot public Client Key
returned by an approved create operation.