CLI

arbol es la API de Arbol desde tu terminal. Cada operación de la API es un comando, generado a partir del documento OpenAPI público de la API, y cada solicitud pasa por el SDK de TypeScript. Se publica en npm como @arbol-ai/cli bajo la licencia Apache 2.0.

Instalar

npm install --global @arbol-ai/cli
arbol --version

Necesita Node.js 26 o posterior. Ejecuta el mismo comando de instalación para actualizarla. arbol --version también nombra el release de la API a partir del que se generaron sus comandos, con la forma arbol <versión> (Arbol API 1.AAAAMMDD.HMMSS). La API va en el release 1.20261104.21009; cuándo llega cada cambio a la CLI está en Versiones y actualizaciones.

En Linux, guardar un inicio de sesión o una key necesita secret-tool, del paquete libsecret-tools. Una API key que se pasa a un solo comando no guarda nada.

Iniciar sesión

arbol auth login
arbol auth status

arbol auth login abre tu navegador para iniciar sesión. Cuando perteneces a varias organizaciones, la página de inicio de sesión te pregunta cuál. Con --no-browser, imprime la URL de inicio de sesión para que la abras tú; el inicio de sesión igual vuelve a esta máquina.

• arbol auth status imprime qué credencial usan los comandos y, si es un inicio de sesión, su organización. Agrega --json para scripts.
• arbol auth switch cambia a otra de tus organizaciones. Pasa el nombre o el id org_… de la organización para saltarte la pregunta.
• arbol auth logout cierra la sesión, u olvida la API key guardada de un perfil. La key en sí sigue funcionando hasta que se revoque en Cuenta.

Un inicio de sesión pide todos los permisos (scopes) del release de la API, pero lo que puede hacer son esos scopes dentro de los permisos de tus roles: pedir un scope no lo otorga. Para pedir menos, define ARBOL_SCOPES con una lista separada por espacios que incluya openid.

Usar una API key

Para scripts, servidores y CI, usa una API key (consulta Autenticación). La CLI nunca recibe una key como argumento: ponla en ARBOL_API_KEY, o pásala por un pipe a --api-key-stdin.

ARBOL_API_KEY="$(cat /secure/path/arbol-key)" arbol visoft clinics list
arbol raiz agents list --api-key-stdin < /secure/path/arbol-key

Una key dada de esta forma se usa solo para ese comando y tiene prioridad sobre ARBOL_PROFILE y el perfil por defecto; no se puede combinar con --profile. Una key rechazada nunca recurre a tu inicio de sesión.

Perfiles

Un perfil es una forma con nombre de llamar a Arbol: un inicio de sesión o una API key guardada.

arbol auth login --profile clinic
arbol auth api-key --profile ci < /secure/path/arbol-key
arbol auth profiles
arbol auth use ci
ARBOL_PROFILE=clinic arbol raiz agents list

arbol auth api-key lee la key desde stdin, o te la pide sin mostrarla, la valida contra la API y la guarda. Un comando usa, en este orden: una API key de ARBOL_API_KEY o de --api-key-stdin, el perfil que nombre --profile o ARBOL_PROFILE, y luego el perfil por defecto. arbol auth use fija el perfil por defecto, y arbol auth profiles lo marca con *.

Ejecutar operaciones

Los comandos son arbol <service> <resource> <verb>, el nombre público de la operación: raiz.agents.list es arbol raiz agents list, y account.apiKeys.list es arbol account api-keys list. Un servicio se escribe en una sola palabra, sin guiones: salud-total.affiliations.lookup es arbol saludtotal affiliations lookup, y policia-colombia es policiacolombia. El nombre con guion también funciona. arbol <service> lista los comandos de un servicio, y --help después de un comando imprime sus campos, los valores que acepta cada uno, sus valores por defecto y un ejemplo.

arbol raiz agents list --status active
arbol raiz agents get --agent-id agt_01jd8x5k2m7q9r3t6v8w0y4z1b
arbol raiz agents create --input agent.json --dry-run

• Cada campo de entrada es un flag en kebab case: agentId es --agent-id. Un id que va en la ruta de la operación es, en cambio, un argumento, como en arbol account api-keys delete <id>.
• --input file.json pasa toda la entrada como JSON, y --input - la lee desde stdin; los flags sobrescriben sus campos. Con --api-key-stdin, stdin lleva la key, así que usa un archivo.
• La CLI valida la entrada contra el esquema de la operación antes de enviar nada.
• --dry-run imprime la solicitud (método, URL y cuerpo) sin leer ninguna credencial ni enviarla.
• Una eliminación pide confirmación en una terminal; en un script, pasa --yes.

Salida y fallos

Un comando imprime el data de la respuesta como JSON. Un fallo imprime el código de error y el id de solicitud, lo indica cuando una escritura no obtuvo respuesta y su resultado es desconocido, y termina con un estado distinto de cero.

Nada se reintenta, ni siquiera después de un 401 o un 403. Revisa el estado detrás de una escritura incierta antes de volver a ejecutarla. Consulta Reintentos.

Dónde se guardan las credenciales

~/.arbol/config.json contiene tus perfiles y el perfil por defecto, y ningún secreto. Cada inicio de sesión y cada API key guardada es un archivo sellado bajo ~/.arbol/ (directorios con modo 0700, archivos con 0600), cifrado con AES-256-GCM bajo una clave que guarda tu sistema operativo:

No hay ninguna alternativa en texto plano. Un inicio de sesión se renueva solo, y arbol auth logout elimina las credenciales locales incluso cuando falla su revocación remota, y te lo dice.