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

# AIHubMix CLI (Ferramenta de Linha de Comando)

> O AIHubMix CLI é a ferramenta de linha de comando oficial do AIHubMix: binário único e zero dependências. No terminal, consulte o saldo da conta, gerencie API Keys e veja os modelos disponíveis, com saída amigável para scripts e AI Agents.

O **AIHubMix CLI** é a ferramenta de linha de comando oficial do AIHubMix (executável `aihubmix`). Após a instalação, você não precisa abrir o console web para consultar o saldo da conta, gerenciar API Keys e ver os modelos disponíveis no terminal. É um binário único, **sem necessidade de instalar Python, Node ou Go**, instalável com um único comando; todos os comandos suportam saída JSON e se integram diretamente a scripts, CI e AI Agents (como o Claude Code).

**O que ele faz:**

* **Consultar saldo**: consulta em tempo real do saldo da conta e da cota utilizada
* **Gerenciar Keys**: criar, ver, buscar, atualizar e excluir API Keys
* **Ver modelos**: lista os modelos disponíveis para o token atual
* **Scriptável**: saída JSON + códigos de saída estáveis, naturalmente adequado para automação e AI Agents

<Info>
  **Não confunda as duas credenciais**: o CLI faz login com o "Token de Acesso ao Sistema" (Manage Key, formato `fd***`); obtenha-o no console em [console.aihubmix.com/setting](https://console.aihubmix.com/setting) clicando em "Gerar Token de Acesso ao Sistema". Ele serve para **gerenciar a conta** e **não é** o mesmo que a API Key (`sk-***`) usada para invocar modelos.
</Info>

<Tip>
  Procurando o antigo script Python (`aihubmix_cli.py`)? Consulte [Obter informações da conta via API](/pt/api/Cli). Esta página é o seu substituto de nova geração, mais simples e mais rápido.
</Tip>

## Instalação

### Instalação com um comando (recomendado)

Copie o comando correspondente ao seu sistema, cole no terminal e execute para baixar o binário e adicioná-lo automaticamente ao `PATH`:

<CodeGroup>
  ```bash macOS / Linux theme={null}
  curl -fsSL https://raw.githubusercontent.com/AIhubmix/platfrom-cli/main/install.sh | sh
  ```

  ```powershell Windows PowerShell theme={null}
  irm https://raw.githubusercontent.com/AIhubmix/platfrom-cli/main/install.ps1 | iex
  ```
</CodeGroup>

Após a instalação, **abra um novo terminal** e execute `aihubmix login` para começar a usar.

<Info>
  Você também pode baixar manualmente o binário da sua plataforma em [Releases](https://github.com/AIhubmix/platfrom-cli/releases) (no Windows, `aihubmix_windows_amd64.exe`) e colocá-lo em um diretório do `PATH`; em sistemas tipo Unix, execute `chmod +x`.
</Info>

Quando necessário, use variáveis de ambiente para ajustar o comportamento de instalação:

| Variável           | Descrição                                      | Padrão                                                                           |
| ------------------ | ---------------------------------------------- | -------------------------------------------------------------------------------- |
| `AIHUBMIX_VERSION` | Instalar uma versão específica (ex.: `v0.2.0`) | `latest`                                                                         |
| `AIHUBMIX_BIN_DIR` | Diretório de instalação personalizado          | Unix: `/usr/local/bin` ou `~/.local/bin`; Windows: `%LOCALAPPDATA%\aihubmix\bin` |

## Início rápido

Após o login, todos os comandos ficam disponíveis:

```bash theme={null}
# 1. Login: abre o navegador na página de geração de token, cole o Manage Key (entrada não exibida)
aihubmix login

# 2. Ver a identidade atual e o saldo
aihubmix whoami

# 3. Ver as informações completas da conta
aihubmix me

# 4. Listar suas API Keys
aihubmix keys list
```

## Referência de comandos

| Comando                                  | Função                                          |
| ---------------------------------------- | ----------------------------------------------- |
| `aihubmix login`                         | Login (cole o Manage Key)                       |
| `aihubmix logout`                        | Logout, apaga as credenciais locais             |
| `aihubmix whoami`                        | Ver a identidade de login atual e o saldo       |
| `aihubmix me`                            | Ver as informações completas da conta e o saldo |
| `aihubmix models list`                   | Ver os modelos disponíveis no momento           |
| `aihubmix keys list [--num N]`           | Listar API Keys                                 |
| `aihubmix keys search <palavra-chave>`   | Buscar Keys por palavra-chave                   |
| `aihubmix keys get <id>`                 | Ver detalhes de uma Key específica              |
| `aihubmix keys create [parâmetros]`      | Criar uma nova Key                              |
| `aihubmix keys update <id> [parâmetros]` | Atualizar uma Key                               |
| `aihubmix keys delete <id>`              | Excluir uma Key                                 |

<Tip>
  Adicione `--help` a qualquer comando para ver os parâmetros completos, por exemplo `aihubmix keys create --help`.
</Tip>

## Operações comuns

### Gerenciar API Keys

```bash theme={null}
# Criar uma Key com limite de $10, restrita aos modelos especificados
aihubmix keys create -n prod-key -q 10 -m "gpt-4o,claude-3.5-sonnet"

# Criar uma Key sem limite de cota e sem expiração
aihubmix keys create -n ci-key -u

# Renomear uma Key (demais configurações inalteradas)
aihubmix keys update 123 -n new-name

# Desativar uma Key
aihubmix keys update 123 --status 0

# Excluir uma Key
aihubmix keys delete 123
```

Aqui, `-q 10` significa que a Key tem limite de \$10 e `-u` significa sem limite de cota. A exclusão pede confirmação por padrão; em cenários de CI, adicione `--yes` para pular.

### Uso em scripts / AI Agents

O CLI é muito amigável à automação, podendo ser acionado diretamente por CI, scripts ou AI Agents (como o Claude Code):

* **Sem login**: passe o Manage Key via variável de ambiente `AIHUBMIX_TOKEN` ou `--token`, ignorando o login interativo (prioridade: `--token` > `AIHUBMIX_TOKEN` > arquivo de configuração).
* **Saída JSON**: adicione `--json` (`-j`) a qualquer comando; resultados normais vão para o stdout e os erros para o stderr, facilitando o parsing com `jq`.
* **Códigos de saída estáveis**: scripts podem usá-los para determinar sucesso ou falha.

```bash theme={null}
# Acionado por variável de ambiente, extrai os nomes de todas as Keys
AIHUBMIX_TOKEN=fd*** aihubmix keys list --json | jq '.data[].name'

# Consultar o saldo
AIHUBMIX_TOKEN=fd*** aihubmix whoami --json | jq -r '.balance'
```

Significado dos códigos de saída:

| Código de saída | Significado                                               |
| --------------- | --------------------------------------------------------- |
| `0`             | Sucesso                                                   |
| `1`             | Erro genérico (erro de parâmetro, falha de negócio, etc.) |
| `2`             | Falha de autenticação (não autenticado / Token inválido)  |
| `3`             | Erro de rede / conexão                                    |

## Parâmetros globais

Os parâmetros a seguir se aplicam a todos os comandos:

| Parâmetro          | Abreviação | Descrição                                                  |
| ------------------ | ---------- | ---------------------------------------------------------- |
| `--token <token>`  | `-t`       | Passa o Manage Key diretamente (cenários de CI / script)   |
| `--json`           | `-j`       | Saída em formato JSON                                      |
| `--base-url <url>` | `-b`       | API Base URL personalizada (padrão `https://aihubmix.com`) |
| `--no-color`       |            | Desativa a saída colorida                                  |
| `--config <path>`  |            | Especifica o caminho do arquivo de configuração            |
| `--version`        |            | Ver a versão                                               |

## Arquivo de configuração

As informações de login são salvas em `~/.aihubmix/config.json` (no Windows, `%USERPROFILE%\.aihubmix\config.json`), com permissões restritas a **leitura/escrita apenas pelo usuário atual**. Durante o login, o Manage Key não é exibido nem gravado em logs.

<Warning>
  Não submeta o Manage Key a repositórios de código nem o compartilhe com terceiros. Em caso de vazamento, gere-o novamente no console; o token antigo é invalidado imediatamente.
</Warning>

## Perguntas frequentes

**Preciso instalar Python / Node / Go?**

Não. O CLI é um binário único, pronto para usar após o download.

**Qual a diferença entre Manage Key e API Key?**

O Manage Key (`fd***`) serve para gerenciar a conta (consultar saldo, gerenciar Keys) e é usado pelo CLI; a API Key (`sk-***`) serve para invocar modelos. Ambos são gerados em locais diferentes do console e não podem ser usados de forma intercambiável.

**Há suporte para Windows?**

Sim. Há binários nativos para Windows, macOS e Linux.

**Como usar sem interação em CI / scripts?**

Passe o Manage Key via variável de ambiente `AIHUBMIX_TOKEN`, combinando com `--json` e os códigos de saída, sem precisar executar `aihubmix login`.

**E se eu esquecer ou vazar o Manage Key?**

Gere-o novamente em [console.aihubmix.com/setting](https://console.aihubmix.com/setting); o token antigo é invalidado.

***

*Documentação relacionada: [API da Plataforma · CliEndpoints](/pt/api/CliEndpoints/get-self) · [Script Python legado](/pt/api/Cli) · [Console AIHubMix](https://console.aihubmix.com)*

***

Última atualização: 2026-06-22