---
title: "CLI"
description: "Install the arbol command, sign in or use an API key, and run any Arbol API operation from your 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` 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](/en/developers/sdks/typescript/). It is published on npm as [`@arbol-ai/cli`](https://www.npmjs.com/package/@arbol-ai/cli) under the Apache 2.0 license.

## Install

```bash
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 ; when each change reaches the CLI is in [Versions and updates](/en/developers/concepts/versions/).

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

```bash
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](/en/developers/authentication/)). The CLI never takes a key as an argument: put it in `ARBOL_API_KEY`, or pipe it to `--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
```

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.

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

```bash
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](/en/developers/concepts/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:

| OS | Where the key is |
|---|---|
| macOS | The Keychain item "Arbol CLI", read through `/usr/bin/security` |
| Linux | The Secret Service, through `secret-tool` |
| Windows | `~/.arbol/session-key.dpapi`, protected by DPAPI for your Windows user |

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.

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