---
title: "CLI"
description: "Instala el comando arbol, inicia sesión o usa una API key, y ejecuta cualquier operación de la API de Arbol desde tu terminal."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.getarbol.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/developers/sdks/typescript/). Se publica en npm como [`@arbol-ai/cli`](https://www.npmjs.com/package/@arbol-ai/cli) bajo la licencia Apache 2.0.

## Instalar

```bash
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 ; cuándo llega cada cambio a la CLI está en [Versiones y actualizaciones](/developers/concepts/versions/).

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

```bash
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](/developers/authentication/)). La CLI nunca recibe una key como argumento: ponla en `ARBOL_API_KEY`, o pásala por un pipe a `--api-key-stdin`.

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

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

```bash
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](/developers/concepts/retries/).

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

| Sistema operativo | Dónde está la clave |
|---|---|
| macOS | El elemento "Arbol CLI" del Llavero, que se lee a través de `/usr/bin/security` |
| Linux | El Secret Service, a través de `secret-tool` |
| Windows | `~/.arbol/session-key.dpapi`, protegido con DPAPI para tu usuario de Windows |

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.

Source: https://docs.getarbol.com/developers/cli/index.mdx