# CLI

> Instale a CLI do Nodaro pelo npm ou como binário, faça login uma vez por instância e execute workflows, apps e nós avulsos no terminal ou em um job de CI.

Source: https://nodaro.ai/pt-BR/docs/developers/cli

A **CLI do Nodaro** (`@nodaro/cli`) é um cliente de linha de comando para o Nodaro. Ela lista e executa workflows, executa apps publicados, executa um único nó sem workflow e acompanha cada execução até o fim. Ela mantém vários perfis conectados lado a lado e imprime JSON para scripts, então se encaixa no trabalho no terminal, em jobs do cron e em pipelines de CI.

A CLI é uma camada fina sobre o [SDK para TypeScript](https://nodaro.ai/docs/developers/sdk). Para uma integração escrita em código, use o SDK diretamente.

## Instalação
**npm**

O pacote npm funciona em macOS, Linux e Windows. Ele precisa do Node.js 20 ou posterior.

```bash
npm install -g @nodaro/cli
nodaro --version
```

Para executar um comando sem instalar o pacote, use `npx`:

```bash
npx @nodaro/cli projects list
```

**macOS and Linux binary**

O binário independente é um único arquivo de cerca de 60 MB. Ele não precisa do Node.js e inicia em cerca de 10 ms.

As releases da CLI recebem a tag `cli-vX.Y.Z` no repositório público. A release “latest” do repositório pertence ao app, não à CLI, então um link `releases/latest/download/...` nunca chega a um binário da CLI. Encontre primeiro a tag `cli-v` mais recente e depois baixe a partir dela:

```bash
# 1. The newest CLI version
NODARO_CLI_VERSION=$(curl -fsSL "https://api.github.com/repos/nodaroai/app.nodaro.ai/git/matching-refs/tags/cli-v?per_page=100" \
| grep -o '"refs/tags/cli-v[0-9][0-9.]*"' | tr -d '"' | sed 's#refs/tags/cli-v##' \
| sort -t. -k1,1n -k2,2n -k3,3n | tail -n 1)
echo "Installing @nodaro/cli $NODARO_CLI_VERSION"

# 2. Your platform: darwin-arm64 (Apple silicon), darwin-x64 (Intel Mac), linux-x64 or linux-arm64
NODARO_CLI_PLATFORM=darwin-arm64

# 3. Download. -f fails on an HTTP error instead of saving the error page as the binary.
curl -fL "https://github.com/nodaroai/app.nodaro.ai/releases/download/cli-v$NODARO_CLI_VERSION/nodaro-$NODARO_CLI_PLATFORM" \
  -o /usr/local/bin/nodaro && chmod +x /usr/local/bin/nodaro
nodaro --version
```

**Windows binary**

No PowerShell, encontre a tag `cli-v` mais recente e depois baixe `nodaro-windows-x64.exe`:

```powershell
$v = (Invoke-RestMethod "https://api.github.com/repos/nodaroai/app.nodaro.ai/git/matching-refs/tags/cli-v?per_page=100") |
ForEach-Object { $_.ref -replace '^refs/tags/cli-v', '' } |
Where-Object { $_ -match '^\d+\.\d+\.\d+$' } |
Sort-Object { [version]$_ } | Select-Object -Last 1
Invoke-WebRequest "https://github.com/nodaroai/app.nodaro.ai/releases/download/cli-v$v/nodaro-windows-x64.exe" -OutFile nodaro.exe
.\nodaro.exe --version
```

Para fixar uma versão, pule a primeira etapa e defina a versão você mesmo. Todas as releases da CLI e os binários delas estão listados nas [releases cli-v](https://github.com/nodaroai/app.nodaro.ai/releases?q=cli-v) do repositório público.

## Login
A CLI se autentica com um token de API pessoal e o salva em um perfil.

### Iniciar o login no navegador
Execute `nodaro auth login`. A CLI abre o navegador na página **Autorizar a CLI do Nodaro** da instância do Nodaro.

### Autorizar a CLI
Faça login, se necessário, e clique em **Autorizar**. O Nodaro cria um token de API pessoal com o nome do seu dispositivo e o devolve ao terminal.

### Conferir o perfil
Execute `nodaro auth status`. O comando mostra o nome do perfil, o endereço da instância e o token, mascarado.

Se o fluxo no navegador falhar, a CLI pede que você cole um token. Para criar um token você mesmo, abra **Configurações › Tokens de API** no Nodaro e clique em **Criar token**. O token completo é mostrado uma única vez. Os tokens de API pessoais estão disponíveis no Nodaro Cloud e nas instalações da Business edition. Leia [Autenticação](https://nodaro.ai/docs/developers/api/authentication) para entender como os tokens funcionam.

```bash
nodaro auth login                                   # browser sign-in
nodaro auth login --no-browser                      # paste a token instead
nodaro auth login --token "$NODARO_TOKEN"           # non-interactive, for CI
nodaro auth status [--profile <name>] [--json]      # show a profile, token masked
nodaro auth logout [--profile <name>]               # delete a saved profile
```

| Opção de `auth login` | O que faz |
| --- | --- |
| `--profile <name>` | O perfil a salvar. O padrão é `production`. |
| `--token <token>` | Salva este token sem abrir o navegador e sem perguntar. |
| `--base-url <url>` | A instância do Nodaro. O padrão é `https://app.nodaro.ai`. |
| `--no-browser` | Pula o navegador para você colar um token. |

A CLI guarda os perfis em `~/.config/nodaro/config.json`, que só o seu usuário pode ler (modo de arquivo `0600`). Defina `NODARO_CONFIG_DIR` para guardar o arquivo em outra pasta.

## Perfis para várias instâncias
Um **perfil** é um endereço de instância e um token salvos. Crie um perfil por instância, como o Nodaro Cloud, uma instalação de staging e uma instalação local. Depois, escolha um com `--profile`, que todos os comandos aceitam:

```bash
nodaro auth login --profile prod    --base-url https://app.nodaro.ai
nodaro auth login --profile staging --base-url https://staging.example.com
nodaro auth login --profile local   --base-url http://localhost:3000

nodaro projects list --profile staging
```

Um comando sem `--profile` usa o perfil padrão. O padrão é `production` até você salvar um perfil: o primeiro perfil que você salvar passa a ser o padrão. Por isso, um único `nodaro auth login`, sem flags, é tudo de que a maioria das pessoas precisa.

## Escolher um espaço de trabalho
Em uma instância com organizações, o trabalho fica em **espaços de trabalho**. Escolha um para um único comando com `--workspace <id>`, para um shell ou um job de CI com `NODARO_WORKSPACE`, ou salve um no perfil com `nodaro workspace use <id>`. Sem nenhum definido, o trabalho acontece no seu espaço pessoal. Veja [Espaços de trabalho e organizações](https://nodaro.ai/docs/developers/cli/workspaces).

## Três formas de executar
A CLI cobre as três formas de execução do Nodaro. Escolha a que corresponde ao que você criou.

| Objetivo | Comando |
| --- | --- |
| Executar um workflow salvo | `nodaro workflows run <workflowId>` |
| Executar um app publicado, com as entradas e as saídas definidas na curadoria | `nodaro apps run <slug> --input key=value` |
| Executar um único nó diretamente, sem workflow | `nodaro nodes run <type> --param key=value` |

`nodaro nodes run` é o equivalente, na CLI, das ferramentas de ação do [servidor MCP](https://nodaro.ai/docs/mcp/tools), como `generate_image` e `generate_video`. Todo nó de geração responde em `POST /v1/<type>`, então qualquer nó que `nodaro nodes list` mostra pode ser executado com `nodaro nodes run`. Veja [Executar um único nó](https://nodaro.ai/docs/developers/api/nodes) para o lado REST.

Adicione `--watch` para aguardar até a execução terminar:

```bash
nodaro nodes run generate-image \
  --param prompt="a snow leopard on a mountain ridge, cinematic" \
  --param provider=flux \
  --watch
```

Leia [Parâmetros e arquivos de entrada](https://nodaro.ai/docs/developers/cli/params) para a sintaxe de `--param`, e [Saída e códigos de saída](https://nodaro.ai/docs/developers/cli/output) antes de usar a CLI em scripts.

## O que a CLI não cobre
A CLI deixa de fora créditos, apps de desenvolvedor, OAuth, pipelines, Reduce e os auxiliares de upload. Para esses recursos, use o [SDK](https://nodaro.ai/docs/developers/sdk) ou a [API REST](https://nodaro.ai/docs/developers/api).

Passar da CLI para o código é rápido. Este é o equivalente no SDK de `nodaro workflows run wf_abc`:

```ts

const nodaro = createClient({
baseUrl: "https://app.nodaro.ai",
auth: new StaticTokenAuth(process.env.NODARO_TOKEN!),
})

const run = await nodaro.workflows.run("wf_abc")
```

## Próximos passos
  - [Comandos](https://nodaro.ai/docs/developers/cli/commands): 
Todos os comandos principais: projetos, workflows, apps, nós, modelos, seletores, execuções e jobs.
  
  - [Parâmetros e arquivos de entrada](https://nodaro.ai/docs/developers/cli/params): 
Como --param, --input e --params-file transformam texto em um corpo de requisição.
  
  - [Saída e códigos de saída](https://nodaro.ai/docs/developers/cli/output): 
Saída em JSON, --watch e os códigos de saída para usar em condições nos scripts.
  
  - [Exemplos](https://nodaro.ai/docs/developers/cli/examples): 
Jobs do cron, condições em pipelines de CI, legendas a partir de uma transcrição e receitas do assistente de prompt.

## Frequently asked questions

### Como instalo a CLI do Nodaro?

Execute npm install -g @nodaro/cli com o Node.js 20 ou posterior. Sem o Node.js, baixe o binário independente para macOS, Linux ou Windows em uma release cli-v do repositório público no GitHub. Confira a instalação com nodaro --version.

### Como faço login na CLI do Nodaro?

Execute nodaro auth login. O navegador abre a página Autorizar a CLI do Nodaro, você clica em Autorizar, e a CLI recebe um token de API pessoal. Em um job de CI, passe um token diretamente com nodaro auth login --token.

### Onde a CLI do Nodaro guarda meu token?

Em ~/.config/nodaro/config.json, com permissões de arquivo que deixam só o seu usuário ler o arquivo. Defina a variável de ambiente NODARO_CONFIG_DIR para guardar o arquivo em outra pasta.

### Posso usar a CLI com uma instalação self-hosted do Nodaro?

Sim. Salve um perfil com --base-url apontando para o endereço da sua instalação, por exemplo nodaro auth login --profile local --base-url http://localhost:3000, e depois adicione --profile local aos seus comandos.

### Devo usar a CLI ou o SDK?

Use a CLI para trabalho no terminal, jobs do cron, pipelines de CI e verificações rápidas. Para uma integração escrita em código, use o SDK para TypeScript. A CLI é uma camada fina sobre o SDK, então tudo o que a CLI faz o SDK também faz.