CLI

arbol is the Arbol API from your terminal. Every API operation is a command, generated from the API’s public OpenAPI document, and every request goes through the TypeScript SDK. It is published on npm as @arbol-ai/cli under the Apache 2.0 license.

Install

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

It needs Node.js 26 or newer. Run the same install command to update. arbol --version also names the API release its commands were generated from, in the form arbol <version> (Arbol API 1.YYYYMMDD.HMMSS). The API is at release 1.20261104.21009; when each change reaches the CLI is in Versions and updates.

On Linux, saving a sign-in or a key needs secret-tool, from the libsecret-tools package. An API key passed to a single command saves nothing.

Sign in

arbol auth login
arbol auth status

arbol auth login opens your browser to sign in. When you belong to several organizations, the sign-in page asks which one. With --no-browser it prints the sign-in URL for you to open; the sign-in still returns to this machine.

• arbol auth status prints which credential commands use and, for a sign-in, its organization. Add --json for scripts.
• arbol auth switch moves to another of your organizations. Pass the organization’s name or org_… id to skip the question.
• arbol auth logout signs out, or forgets a profile’s saved API key. The key itself keeps working until it is revoked in Account.

A sign-in asks for every scope of the API release, but what it may do is those scopes within your roles’ permissions: asking for a scope doesn’t grant it. To ask for fewer, set ARBOL_SCOPES to a space-separated list that includes openid.

Use an API key

For scripts, servers and CI, use an API key (see Authentication). The CLI never takes a key as an argument: put it in ARBOL_API_KEY, or pipe it to --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

A key given this way is used for that command only and wins over ARBOL_PROFILE and the default profile; it can’t be combined with --profile. A refused key never falls back to your sign-in.

Profiles

A profile is a named way to call Arbol: a sign-in, or a saved API key.

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 reads the key from stdin, or asks for it without showing it, checks it against the API and saves it. A command uses, in order: an API key from ARBOL_API_KEY or --api-key-stdin, the profile that --profile or ARBOL_PROFILE names, then the default profile. arbol auth use sets the default, and arbol auth profiles marks it with *.

Run operations

Commands are arbol <service> <resource> <verb>, the operation’s public name: raiz.agents.list is arbol raiz agents list, and account.apiKeys.list is arbol account api-keys list. A service is one word, without hyphens: salud-total.affiliations.lookup is arbol saludtotal affiliations lookup, and policia-colombia is policiacolombia. The hyphenated name works too. arbol <service> lists a service’s commands, and --help after a command prints its fields, the values each accepts, their defaults and an example.

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

• Each input field is a flag in kebab case: agentId is --agent-id. An id that goes in the operation’s path is an argument instead, as in arbol account api-keys delete <id>.
• --input file.json passes the whole input as JSON, and --input - reads it from stdin; flags override its fields. With --api-key-stdin, stdin carries the key, so use a file.
• The CLI checks the input against the operation’s schema before it sends anything.
• --dry-run prints the request (method, URL and body) without reading a credential or sending it.
• A deletion asks for confirmation on a terminal; in a script, pass --yes.

Output and failures

A command prints the response’s data as JSON. A failure prints the error code and the request id, says so when a write got no answer and its outcome is unknown, and exits with a nonzero status.

Nothing is retried, even after a 401 or 403. Check the state behind an uncertain write before you run it again. See Retries.

Where credentials are kept

~/.arbol/config.json holds your profiles and the default, and no secret. Each sign-in and saved API key is a sealed file under ~/.arbol/ (directories mode 0700, files 0600), encrypted with AES-256-GCM under a key that your operating system keeps:

There is no plaintext fallback. A sign-in renews by itself, and arbol auth logout removes the local credentials even when revoking them remotely fails, and tells you so.