ii999/agentenv

¿Qué hace agentenv?

agentenv lee un archivo de configuración TOML local que contiene valores ordinarios y referencias a credenciales. Los valores de las credenciales residen en una variable de entorno, en el almacén de credenciales de la plataforma o en un comando externo, nunca en el archivo. La CLI lee valores, edita el archivo con escrituras validadas que preservan el formato y lanza procesos objetivo con valores seleccionados inyectados en un entorno temporal.

Confirma que la CLI está disponible con command -v agentenv antes de depender de ella. Si falta, indícalo y detente; no reconstruyas su comportamiento leyendo el archivo de configuración directamente.

Reglas estrictas

• Nunca imprimas, registres, persistas o resumas un valor de credencial resuelto. No lances agentenv run con un objetivo elegido para revelar su propio entorno: env, printenv, set, sh -c 'echo $VAR' o escribir el entorno en un archivo son todas violaciones.
• Nunca escribas un valor secreto en el archivo de configuración. set es para valores ordinarios; credential add escribe solo una definición; credential set es la única ruta que almacena un valor, y lo almacena en el almacén de credenciales de la plataforma, no en el archivo.
• Si falta un perfil, entrada, campo o credencial, infórmalo explícitamente. No adivines un nombre de campo, cambies silenciosamente de perfil o sustituyas otra credencial.
• Lee la configuración a través de la CLI, no abriendo el archivo TOML, para que se apliquen la selección de perfil, la indirección de credenciales y la validación.
• Después de que credential fill escriba un valor en un campo del navegador, no leas ese campo de nuevo, evalúes su valor ni tomes una captura de pantalla que lo muestre. El resultado del relleno es lo único que puedes informar.

Lectura de configuración

Trabaja de arriba a abajo; omite los pasos que ya hayas realizado en esta sesión.

1. agentenv project status --json — descubre el archivo de proyecto más cercano y su estado de confianza antes de leer la configuración dependiente del perfil. Su informe se escribe en stdout incluso cuando sale con código 5 o 6; un código de salida 2 deja stdout vacío.
2. agentenv list --json — descubre perfiles y entradas. agentenv list --profiles lista los nombres de los perfiles sin seleccionar uno.
3. agentenv show <entry> --json — inspecciona una entrada desconocida antes de usarla. Los campos de credenciales aparecen como un miembro reference (credential://<name> o credential://<name>?as=<ENV>), nunca como un valor.
4. agentenv get <path> — lee un escalar ordinario. Usa --json para un array o tabla. Leer un campo de credencial devuelve la cadena de referencia, no el secreto.
5. agentenv find <needle> --json — busca nombres de entradas, nombres de campos, descripciones y valores de cadena cuando no sabes dónde vive algo. Añade --all-profiles para buscar en todos los perfiles.

Las rutas son segmentos de campo separados por puntos dentro del perfil seleccionado, por ejemplo llm.model. Pon entre comillas un segmento que contenga puntuación o espacios: servers."my host".port. El perfil no es parte de la ruta; selecciónalo con --profile <NAME> (precedencia: --profile, luego AGENTENV_PROFILE, luego el pin del archivo de proyecto de confianza, luego default_profile en el archivo). Esto se aplica a lecturas, run, set y unset. --create-profile requiere un --profile explícito y nunca usa el pin.

Configuración con ámbito de proyecto

agentenv descubre el .agentenv.toml regular más cercano mientras camina desde el directorio de trabajo hacia la raíz del sistema de archivos. El archivo tiene un esquema cerrado y solo de selección: version = 1, un profile opcional no vacío y tablas opcionales [requires.<entry>] con un reason no vacío y fields opcionales relativos a la entrada que, cuando están presentes, no están vacíos. Está limitado a 64 KiB y no puede contener valores, definiciones de credenciales, tablas inject ni cadenas credential://.

Los archivos de proyecto son inertes hasta que su contenido exacto sea aprobado. Usa agentenv project status, agentenv project allow y agentenv project revoke para inspeccionar, aprobar y eliminar la aprobación. La aprobación se guarda en el directorio de estado del usuario, fuera del repositorio; editar el archivo lo vuelve a no confiable. Un archivo no confiable no afecta a ningún comando ordinario excepto por un aviso en stderr.

Usa --no-project, o un AGENTENV_NO_PROJECT no vacío, para omitir el descubrimiento para un comando fuera del grupo project. La omisión nunca se aplica a project status, project allow o project revoke, que siempre descubren el archivo más cercano.

project status --json escribe deliberadamente su informe en stdout con código de salida 5 para un estado de proyecto no disponible, inválido o no confiable y con código de salida 6 cuando los requisitos no están satisfechos o no se pueden verificar. Esta es la excepción a la regla habitual de stdout vacío en JSON fallido. El código de salida 2 cubre errores de configuración, incluidos errores de validación del archivo de proyecto, y deja stdout vacío para este comando.

Ejecutar un comando que necesita credenciales

Usa run con uno o más flags --with <entry> y el objetivo después de --:

agentenv run --with llm -- llm-client request
agentenv run --with llm --with kubernetes -- deploy-tool sync

Cada entrada --with contribuye con sus referencias de credenciales y su tabla inject (que mapea nombres de entorno a campos ordinarios de esa entrada). Una credencial se inyecta bajo su nombre inject_as a menos que la referencia lleve una anulación ?as=<ENV>. Para saber qué nombres de entorno recibirá un objetivo, lee inject_as de agentenv credential list --json y los miembros de la tabla inject y reference de agentenv show <entry> --json.

El stdin/stdout/stderr del objetivo pasan sin cambios y se devuelve su código de salida. Las inyecciones conflictivas (dos fuentes que apuntan a un solo nombre de entorno) abortan con código de salida 4 antes de que algo se resuelva o lance.

Añade --pure para lanzar el objetivo con un entorno mínimo curado: una base de plataforma fija (PATH, HOME, locale, AGENTENV_* y nombres similares críticos para el proceso), más las variables llevadas explícitamente con --keep <NAME> repetible, más las inyecciones, nada más del shell de llamada. Un nombre mantenido no establecido en el padre se informa en stderr y la ejecución continúa. --pure filtra solo el entorno del objetivo; no es una caja de arena, y las llamadas anidadas a agentenv dentro del objetivo siguen resolviendo la misma configuración. La resolución de credenciales no cambia con --pure: un subproceso del proveedor command mantiene el entorno completo del padre.

Escritura de configuración

Usa esto cuando el usuario pida registrar configuración:

agentenv init                            # crea el archivo de configuración; se niega a sobrescribir
agentenv set <path> <value>              # escribe un valor; crea tablas intermedias
agentenv set <path> <value> --type int|float|bool|json
agentenv set llm.model gpt-5 --description "LLM predeterminado."   # también crea la entrada
agentenv set <path> <value> --profile dev --create-profile "Perfil de desarrollo."
agentenv unset <path>                    # elimina un campo o tabla

Cada entrada necesita una descripción; crear una nueva entrada de nivel superior requiere --description en el mismo set. Un perfil desconocido es un error a menos que pases --create-profile con un --profile explícito. Cada escritura se valida primero en todo el archivo y se rechaza si el resultado fuera inválido, por lo que una escritura rechazada deja el archivo idéntico en bytes; informa el diagnóstico en lugar de reintentar variaciones a ciegas.

La validación rechaza valores de texto plano en campos de cadena nombrados (o con sufijo) token, password, secret, api_key o private_key: tales campos deben contener una referencia credential://. Cuando el usuario te entregue un secreto para guardar, defínelo y almacénalo como una credencial en su lugar (siguiente sección), luego referencia.

Gestión de credenciales

agentenv credential list --json          # definiciones + estado superficial; no resuelve nada
agentenv credential check <name>         # resuelve una credencial; solo informa disponibilidad
agentenv credential add <name> --description "<text>" --provider env \
    --env-var <NAME> --inject-as <ENV>
agentenv credential add <name> --description "<text>" --provider keychain \
    --service <service> --account <account> --inject-as <ENV>
agentenv credential add <name> --description "<text>" --provider command \
    --argv <arg> [--argv <arg> ...] --inject-as <ENV>
agentenv credential set <name> --input dialog --json  # abre entrada local; espera su resultado

Orden para una nueva credencial: credential add la definición, luego para el proveedor keychain almacena el valor con credential set, luego referencia desde un campo de entrada como credential://<name>. Las credenciales de entorno y comando obtienen sus valores de sus sistemas externos; credential set no se aplica a ellas.

Para una entrada local de llavero, lanza credential set <name> --input dialog --json sin un PTY. Dile al usuario que introduzca el valor en la ventana local y guarde. Mantén el comando en ejecución y espera su finalización, incluso a través de pausas de sesión de herramienta; una ventana abierta no es una finalización. Nunca inspecciones, captures, leas ni automatices la ventana de entrada activa o el portapapeles. El usuario introduce y verifica el valor allí, y el comando devuelve solo metadatos de finalización.

Continúa la tarea dependiente solo después del código de salida 0 y JSON status: "stored". status: "cancelled" significa que la entrada terminó sin una confirmación de guardado; infórmalo y detén la acción dependiente. status: "failed" incluye un reason no secreto; informa el diagnóstico. store-unconfirmed significa que puede haber ocurrido una escritura, así que no afirmes que el valor anterior no ha cambiado ni reintentes automáticamente. Los errores de inicio/configuración pueden salir antes de que se emita JSON; maneja una salida no cero o un resultado faltante como un fallo. Una guardado ya en progreso finaliza antes de que el comando regrese; una escritura confirmada informa stored incluso si el usuario solicitó el cierre durante esa escritura.

El diálogo necesita una sesión gráfica en la máquina que ejecuta agentenv. En un host remoto o sin cabeza, explica esa limitación y haz que el usuario ejecute agentenv credential set <name> --input terminal ellos mismos en el terminal de ese host, luego confirma la finalización. No sustituyas un PTY propiedad del agente o una tubería stdin. Nunca pidas el valor en el chat ni lo coloques en argv, una variable de entorno, una tubería de comando o un archivo. La entrada de terminal soporta una alternancia de revelación local, por lo que su salida de pantalla debe permanecer fuera de las herramientas del agente.

Prefiere los proveedores keychain o command para uso local; env expone el valor a cada proceso que hereda el entorno y es adecuado para CI.

Emparejamiento con Docker Compose

Mantén las configuraciones no secretas en .env. Inyecta credenciales solo para el proceso que las necesita, luego deja que Compose reciba la variable inyectada:

agentenv run --with llm -- docker compose up

services:
  app:
    image: alpine:3.20
    environment:
      - OPENAI_API_KEY

La interpolación ${OPENAI_API_KEY} también es compatible con Compose. No uses un env_file: que contenga secretos; persiste las credenciales en un archivo.

Rellenar una credencial en un campo de navegador

Usa credential fill cuando una página que estás controlando necesite una credencial almacenada en un campo de entrada. Escribe el valor a través del protocolo de depuración del navegador; tú continúas navegando y enviando con tu propia herramienta de navegador.

agentenv credential fill --capabilities --json
agentenv credential fill <name> --backend cdp --endpoint http://127.0.0.1:<port> \
    --page-url <URL exacta de la página> --selector '<css del único campo>' --json

Pasos:

1. Confirma que --capabilities lista el backend cdp como disponible. Tu navegador debe exponer un endpoint del Protocolo de Herramientas de Desarrollo de Chrome en loopback (un Chromium iniciado con --remote-debugging-port y un --user-data-dir no predeterminado, o el endpoint que tu herramienta de navegador ya usa). Si no hay ninguno, indícalo; no lances un navegador ni pegues el valor.
2. Navega a la página con tu herramienta de navegador, luego pasa la URL exacta de la página y un selector CSS que coincida solo con el campo objetivo. Añade --page-match origin-path cuando la URL lleve parámetros de consulta volátiles, --frame-selector para cada iframe en el camino hacia el campo y --context-index si la misma URL está abierta en varios contextos.
3. Cierra las Herramientas de Desarrollo en esa pestaña y mantén apagados el rastreo, las screencasts, HAR y la grabación de video mientras llenas; agentenv falla solo en la ventana de Herramientas de Desarrollo abierta porque los otros grabadores no se pueden detectar.
4. Ejecuta el comando. El éxito imprime solo {"version":1,"backend":"cdp","effect":"field-filled"}; el contenido anterior del campo fue reemplazado y la página recibió eventos de entrada normales. Continúa con tu propia herramienta para enviar.

Solo las credenciales que permiten uso environment se pueden llenar; el valor debe ser una sola línea de como máximo 8,192 bytes sin caracteres de control, separación de línea o control bidireccional (value-unsupported en caso contrario). Un proveedor de comando se ejecuta sin terminal y se elimina su nueva línea final; la salida vacía, NUL o no UTF-8 del proveedor es un error de credencial (código de salida 4). Toda la operación, incluido un diálogo de autorización de llavero en el primer acceso, se ejecuta bajo --timeout-ms (predeterminado 30,000); auméntalo cuando el usuario deba hacer clic en tal diálogo. credential fill no verifica el campo, envía el formulario ni inicia sesión; informa el efecto, no un éxito que no observaste.

Razones de fallo en stderr (credential-fill: <reason>: <message>). Código de salida 8, nada cambió: backend-unavailable, permission, connect-failed, version-unsupported, recording-conflict, context-absent, page-absent, page-ambiguous, frame-absent, frame-ambiguous, frame-invalid, target-absent, target-ambiguous, target-hidden, target-disabled, target-readonly, target-unfillable, target-changed, value-unsupported, timeout, cancelled. Código de salida 11, el campo puede contener el valor: timeout, cancelled, o delivery-failed después de que el valor fue enviado, y cleanup-unconfirmed después de un valor entregado.

Ejecución privilegiada

Cuando la solicitud use un sudo-target configurado, lee references/sudo-execution.md antes de planificar, verificar, ejecutar, crear o rotar ese objetivo.

...