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

# Configurazione

> Configura la CLI di CometAPI: posizione del file di configurazione, impostazioni disponibili, gestione delle credenziali, variabili d'ambiente e pratiche di sicurezza.

La CLI di CometAPI legge le impostazioni da un file di configurazione TOML, dalle variabili d'ambiente e dai flag della riga di comando. Quando la stessa impostazione è disponibile da più origini, l'ordine di priorità è:

**Flag CLI > file di configurazione > variabili d'ambiente > valori predefiniti**

## File di configurazione

Posizione: `~/.config/cometapi/config.toml`

Esegui il wizard di configurazione per creare interattivamente il file di configurazione:

```bash theme={null}
cometapi init
```

Oppure gestisci le singole impostazioni con il sottocomando `config`:

```bash theme={null}
# View current configuration
cometapi config show

# Set a value
cometapi config set api_key "$COMETAPI_KEY"

# Remove a value
cometapi config unset api_key

# Show the config file path
cometapi config path
```

## Impostazioni disponibili

| Chiave di configurazione | Variabile d'ambiente     | Descrizione                                                                |
| ------------------------ | ------------------------ | -------------------------------------------------------------------------- |
| `api_key`                | `COMETAPI_KEY`           | API key (richiesta per tutti i comandi)                                    |
| `access_token`           | `COMETAPI_ACCESS_TOKEN`  | access token per i comandi a livello di account                            |
| `base_url`               | `COMETAPI_BASE_URL`      | URL base dell'API (predefinito: `https://api.cometapi.com/v1`)             |
| `default_model`          | `COMETAPI_DEFAULT_MODEL` | model predefinito per `chat` e `run` (fallback: `gpt-5.4`)                 |
| `output_format`          | —                        | Formato di output predefinito: `table`, `json`, `yaml`, `csv` o `markdown` |

## Credenziali

La CLI utilizza due tipi di credenziali:

### API key

Richiesta per tutti i comandi. La API key autentica le richieste agli endpoint model di CometAPI.

Crea una API key in [CometAPI Console → API Keys](https://www.cometapi.com/console/token).

Impostala in uno di questi modi:

<CodeGroup>
  ```bash Environment variable theme={null}
  read -rsp "CometAPI API key: " COMETAPI_KEY
  printf '\n'
  export COMETAPI_KEY
  ```

  ```bash Config file theme={null}
  cometapi config set api_key "$COMETAPI_KEY"
  ```

  ```bash Setup wizard theme={null}
  cometapi init
  ```
</CodeGroup>

### Access token

Opzionale. L'access token è richiesto per i comandi a livello di account: `account`, `stats`, `tokens`, `logs` e `tasks`.

Genera un access token in [CometAPI Console → Personal Settings](https://www.cometapi.com/console/personal).

Impostalo in uno di questi modi:

<CodeGroup>
  ```bash Environment variable theme={null}
  export COMETAPI_ACCESS_TOKEN="your-access-token"
  ```

  ```bash Config file theme={null}
  cometapi config set access_token your-access-token
  ```

  ```bash Setup wizard theme={null}
  cometapi init
  ```
</CodeGroup>

## Sicurezza

La CLI applica le seguenti pratiche di sicurezza:

* API key e access token non vengono mai registrati nei log né mostrati per intero. Nei dati diagnostici vengono mostrati solo gli ultimi 4 caratteri.
* Il file di configurazione viene creato con permessi restrittivi (`0600`) — leggibile solo dal proprietario del file.
* Le credenziali non devono mai essere aggiunte al version control. Aggiungi il percorso del file di configurazione al tuo `.gitignore` se applicabile.

<Warning>
  Sei responsabile di tutti gli utilizzi e dei costi sostenuti con le tue API key. Mantieni le chiavi al sicuro e ruotale se sospetti un accesso non autorizzato.
</Warning>

## Risoluzione dei problemi

| Errore                        | Soluzione                                                                                                 |
| ----------------------------- | --------------------------------------------------------------------------------------------------------- |
| `API key not configured`      | Esegui `cometapi init` o imposta la variabile d'ambiente `COMETAPI_KEY`                                   |
| `Connection failed`           | Esegui `cometapi doctor` per diagnosticare la connettività                                                |
| `Access token not configured` | Necessario solo per `account`/`stats`/`tokens`/`logs`/`tasks`. Esegui `cometapi init` per aggiungerne uno |