# Comandos

> Comandos principais da CLI do Nodaro, com opções: projetos, workflows e compartilhamento, apps, nós, modelos, seletores, execuções, jobs, prompts e Recast.

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

Os **comandos principais da CLI do Nodaro** gerenciam projetos e workflows, executam apps publicados e nós avulsos, e inspecionam execuções e jobs. Esta página lista cada um deles com as opções. Os comandos de entidades, de mídia e de espaços de trabalho têm páginas próprias, listadas na primeira tabela.

Todos os exemplos pressupõem que você já [instalou a CLI e fez login](https://nodaro.ai/docs/developers/cli).

## Grupos de comandos
| Grupo | O que faz | Onde está documentado |
| --- | --- | --- |
| `auth` | Faz login, mostra e remove perfis | [CLI](https://nodaro.ai/docs/developers/cli#sign-in) |
| `projects` | Cria, lê, atualiza e exclui projetos | Esta página |
| `workflows` | Gerencia, exporta, importa, executa e compartilha workflows | Esta página |
| `apps` | Navega pelos apps publicados e os executa | Esta página |
| `nodes` | Lista os tipos de nó e executa um único nó | Esta página |
| `models` | Navega pelo catálogo de modelos | Esta página |
| `pickers` | Lê os catálogos de seletores e preenche seletores a partir de uma descrição | Esta página |
| `catalog` | Mantém os pacotes de catálogo de uma implantação, offline | Esta página |
| `executions`, `jobs` | Inspeciona e cancela execuções | Esta página |
| `video-pro` | Para e retoma execuções do **Gerar vídeo Pro** (Generate Video Pro) | Esta página |
| `prompt` | Transforma uma ideia vaga em um prompt otimizado | Esta página |
| `shots` | Cria e lê registros de compartilhamento de tomadas | Esta página |
| `recast` | Planeja e renderiza uma execução de Recast, ou importa um script | Esta página |
| `characters`, `locations`, `objects` | Gerencia entidades e gera as imagens e os movimentos delas | [Comandos de entidades](https://nodaro.ai/docs/developers/cli/asset-commands) |
| `voice`, `media`, `audio`, `edit` | Troca vozes, legenda, compõe e edita mídias | [Comandos de mídia e voz](https://nodaro.ai/docs/developers/cli/media-commands) |
| `org`, `workspace` | Organizações, convites, espaços de trabalho e relatórios de uso | [Espaços de trabalho e organizações](https://nodaro.ai/docs/developers/cli/workspaces) |

## Opções aceitas por todos os comandos
- `--profile <name>` executa o comando com um perfil salvo em vez do perfil padrão.
- `--json` imprime uma saída legível por máquina em todos os comandos que leem dados. Veja [Saída e códigos de saída](https://nodaro.ai/docs/developers/cli/output).
- `--workspace <id>` é uma opção global. Ela define o espaço de trabalho só para este comando. Veja [Espaços de trabalho e organizações](https://nodaro.ai/docs/developers/cli/workspaces).
- `-v` ou `--version` imprime a versão da CLI.

Nas sinopses abaixo, `<value>` é um valor que você informa, `[...]` é opcional e `a|b` significa um dos valores listados.

## Projetos
```bash
nodaro projects list [--json]
nodaro projects get <id> [--json]
nodaro projects create --name <name> [--description <desc>] [--json]
nodaro projects update <id> [--name <name>] [--description <desc>] [--json]
nodaro projects delete <id> [--json]
```

## Workflows
```bash
nodaro workflows list --project <projectId> [--json]
nodaro workflows get <id> [--json]
nodaro workflows create --project <projectId> --name <name> [--file bundle.json] [--json]
nodaro workflows update <id> [--name <name>] [--file nodes-edges.json] [--json]
nodaro workflows delete <id> [--json]
nodaro workflows export <id> [--with-assets] [--output bundle.json]
nodaro workflows import <file> --project <projectId> [--json]
nodaro workflows run <id> [--watch] [--node n1 n2 ...] [--json]
```

| Opção | O que faz |
| --- | --- |
| `create --file` | Cria o workflow a partir de um pacote de workflow exportado. |
| `update --file` | Grava no workflow os nós, as conexões e as configurações de um arquivo JSON. |
| `export --with-assets` | Adiciona ao pacote os dados de personagens, objetos e locais que o workflow usa. |
| `export --output` | Grava o pacote em um arquivo em vez de imprimi-lo. |
| `run --node` | Executa só os ids de nós listados, separados por espaços. |
| `run --watch` | Acompanha a execução até ela terminar. |

O formato do pacote é o mesmo que o editor exporta. Veja [Importação e exportação de workflows](https://nodaro.ai/docs/guides/import-export).

### Compartilhar e mover workflows
Estes comandos funcionam em instâncias com organizações e espaços de trabalho.

```bash
nodaro workflows share <id> [--visibility workspace|private] [--json]
nodaro workflows move <id> --project <projectId> [--json]
nodaro workflows shared-with-me [--json]
nodaro workflows collaborators list <id> [--json]
nodaro workflows collaborators add <id> (--user <userId> | --email <email>) --role viewer|editor [--json]
nodaro workflows collaborators update <id> <userId> --role viewer|editor [--json]
nodaro workflows collaborators remove <id> <userId> [--json]
```

- `share` define quem no espaço de trabalho pode ver o workflow. A visibilidade padrão é `workspace`.
- `collaborators add --email` encontra o endereço de qualquer conta do Nodaro, seja qual for a organização dela. Um endereço sem conta retorna `404`.
- `move` coloca o workflow em outro projeto. Mover para outro espaço de trabalho remove os colaboradores do workflow, e o resultado informa quem perdeu o acesso.

## Apps
Um app é um workflow envolto em um formulário de entradas e saídas com curadoria. Veja [Apps](https://nodaro.ai/docs/concepts/apps).

```bash
nodaro apps list [--search <query>] [--limit <n>] [--cursor <token>] [--category <slug>]
nodaro apps get <slug>                                   # input schema and outputs
nodaro apps run <slug> --input prompt="..." [--watch]
nodaro apps run <slug> --params-file inputs.json [--watch]
nodaro apps run <slug> --input prompt="..." --override <nodeId>.<field>=<value>
nodaro apps runs <slug> [--limit <n>] [--cursor <token>] [--json]   # your past runs
nodaro apps run-get <slug> <runId>
```

- `apps list` retorna até 50 apps por página. Passe o `--cursor` de uma página para obter a próxima.
- `apps get` mostra os nomes das entradas do app. Use esses nomes como chaves de `--input`.
- `--input` define uma entrada do app. Repita a opção para cada entrada, ou coloque todas em um arquivo JSON com `--params-file`.
- `--override` define diretamente um campo de nó, só nesta execução, no formato `<nodeId>.<field>=<value>`. A opção alcança campos que o app não expõe, como `promptPrefix`. Veja [Texto antes e depois do prompt](https://nodaro.ai/docs/concepts/prompt-pre-post-text).

Uma substituição nunca pode mudar para onde um nó externo envia dados ou de onde ele os busca, como o endereço de um nó **Saída de webhook** (Webhook Output). Nesse caso, a execução é recusada com `locked_field`.

## Nós
```bash
nodaro nodes list [--category <category>] [--json]
nodaro nodes get <type>                                  # full input schema
nodaro nodes run <type> --param prompt="..." --param provider=flux [--watch]
nodaro nodes run <type> --params-file body.json [--watch] [--poll-interval 1000]
```

- `--category` é um destes valores: `input`, `parameter`, `ai-image`, `ai-video`, `ai-audio`, `ai-text`, `processing`, `composition`, `output`, `control`, `entity`, `trigger` ou `utility`.
- `nodes get` imprime o schema de entrada de um tipo de nó: os campos que `--param` aceita.
- `--watch` consulta o job periodicamente até ele terminar, quando a resposta tem um id de job. `--poll-interval` define o intervalo da consulta periódica, em milissegundos. O padrão é 2000.

A sintaxe de `--param` e de `--params-file` está em [Parâmetros e arquivos de entrada](https://nodaro.ai/docs/developers/cli/params).

## Modelos
```bash
nodaro models list [--kind image|video|audio] [--mode <mode>] [--family <vendor>] [--featured] [--json]
```

- `--mode` filtra por operação, como `t2i`, `i2v`, `t2v` ou `tts`.
- `--family` filtra pelo fabricante do modelo, como `Google` ou `Bytedance`.
- `--featured` mostra só os modelos em destaque.

A tabela mostra o id, o tipo, a família, os modos e os níveis de crédito de cada modelo. Ela também marca os modelos em destaque e as famílias de modelos para as quais o Nodaro reuniu orientações de prompt. `--json` retorna as fichas completas de recursos, os preços em créditos e as dicas de prompt. Navegue pelo mesmo catálogo em [Modelos](https://nodaro.ai/docs/models).

## Seletores
Os seletores são os nós de Controles criativos, como **Clima** (Mood) e **Enquadramento** (Framing). Estes comandos leem os catálogos de valores válidos deles. Veja [Catálogos de seletores](https://nodaro.ai/docs/developers/picker-catalogs).

```bash
nodaro pickers list [--json]
nodaro pickers get <nodeType> [--full] [--category <c>] [--field <f>] [--json]
nodaro pickers analyze "<text>" [--target <types>] [--instructions <text>] [--model <id>] [--effort <level>] [--json]
```

| Comando ou opção | O que faz |
| --- | --- |
| `pickers list` | Lista todos os tipos de nó de seletor, o número de opções de cada um e quantas opções têm imagem. |
| `pickers get` | Retorna um catálogo. Cada opção traz `id`, `label`, `category`, `term`, `icon` e, quando tem imagem, `imageUrl`. |
| `--full` | Inclui a descrição de cada opção e o trecho de prompt que ela adiciona. |
| `--category` | Filtra um seletor de uma única dimensão por uma categoria. |
| `--field` | Retorna uma dimensão de um seletor de várias dimensões, como `shotSize` do Enquadramento. |
| `pickers analyze` | AI Fill: escolhe valores de seletores a partir de uma descrição em texto livre. É uma chamada a um LLM, cobrada em créditos. |
| `--target` | Uma lista, separada por vírgulas, dos tipos de nó de seletor a preencher. O padrão é todo seletor que pode ser analisado. |

`term` é a expressão profissional curta que o modo **Compacto** do **Trecho do prompt** adiciona a um prompt. Ele fica vazio em uma opção sem efeito, como `auto` ou `none`. **Pessoa** (Person) e **Figurino e beleza** (Styling) também retornam `sections`: os tópicos deles, cada um com uma imagem redonda.

## Pacotes de catálogo
Uma implantação pode fazer a curadoria dos catálogos de seletores com pacotes de catálogo próprios (vendored). Estes comandos mantêm esses pacotes. Eles funcionam offline, sobre arquivos, e não exigem login.

```bash
nodaro catalog snapshot --in <file>
nodaro catalog diff-upstream --baseline <f> --upstream <f> --pack <f> [--write <f>]
nodaro catalog validate --pack <file> [--exempt es,fr,...]
```

- `snapshot` imprime em JSON uma projeção `/v1/catalogs` completa de um arquivo, com os arquivos de tradução dele.
- `diff-upstream` é uma mesclagem de três vias (three-way merge). Ele leva as edições do upstream para as entradas que você não alterou, com os textos delas nas 11 localidades traduzidas. Ele informa os conflitos, em que você e o upstream alteraram a mesma entrada, e mantém a sua versão. Ele lista as novas entradas e as remoções do upstream, e nunca adiciona nada por conta própria. Ele sai com o código 2 quando há conflitos.
- `validate` verifica se o snapshot de um pacote tem traduções nas 11 localidades traduzidas; com `--exempt`, você declara exceções. Ele sai com o código 1 quando falta uma tradução em uma localidade que não é exceção.

## Execuções e jobs
Uma **execução** é cada vez que um workflow ou um app é executado. Um **job** é o trabalho de um único nó, como a geração de uma imagem. `nodaro nodes run` retorna um job.

```bash
nodaro executions get <id> [--watch] [--json]
nodaro executions cancel <id> [--mode cancelled|stopping]
nodaro jobs get <id> [--json]
nodaro jobs cancel <id> [--json]
```

- `executions get --watch` consulta periodicamente até a execução ser concluída, falhar ou ser cancelada.
- `executions cancel --mode cancelled`, o padrão, para a execução na hora. `--mode stopping` deixa o nível atual de nós terminar primeiro.

## Controle de execuções do Gerar vídeo Pro
O [**Gerar vídeo Pro**](https://nodaro.ai/docs/nodes/video/generate-video-pro) cria um vídeo longo um segmento de cada vez, então você pode parar uma execução e retomá-la depois. Ele roda no Nodaro Cloud; uma instalação self-hosted o executa pela conexão com o Nodaro Cloud.

```bash
nodaro video-pro stop <jobId> [--json]
nodaro video-pro continue <jobId> [--from-segment N] [--watch] [--poll-interval <ms>] [--json]
```

- `stop` encerra a execução de forma ordenada. Os segmentos concluídos são mantidos e entregues, e o restante da reserva é reembolsado. O segmento em andamento ainda é cobrado.
- `continue` inicia um novo job que gera de novo a partir do segmento `N`. O padrão é o primeiro segmento que não foi entregue. Você paga só pelos segmentos gerados de novo, mais a taxa fixa do Pro.

## Assistente de prompt
O assistente de prompt transforma uma ideia vaga em um prompt otimizado para um tipo de nó, como `generate-image`.

```bash
nodaro prompt wizard [--node-type <type>] [--prompt "..."] [--provider <name>] [--style <name>] [--aspect-ratio <ratio>] [--duration <seconds>] [--llm-model <id>] [--reasoning-effort <level>] [--advanced] [--temperature <n>] [--max-tokens <n>]
nodaro prompt analyze --node-type <type> [--prompt "..."] [--provider <name>] [--style <name>] [--aspect-ratio <ratio>] [--duration <seconds>] [--llm-model <id>] [--reasoning-effort <level>] [--advanced] [--temperature <n>] [--max-tokens <n>] [--json]
nodaro prompt generate --node-type <type> --selection category=value [--selection ...] [--original-prompt "..."] [--provider <name>] [--style <name>] [--aspect-ratio <ratio>] [--duration <seconds>] [--llm-model <id>] [--reasoning-effort <level>] [--advanced] [--temperature <n>] [--max-tokens <n>] [--json]
nodaro prompt enhance --node-type <type> [--prompt "..."] [--provider <name>] [--style <name>] [--aspect-ratio <ratio>] [--duration <seconds>] [--llm-model <id>] [--reasoning-effort <level>] [--advanced] [--temperature <n>] [--max-tokens <n>] [--json]
```

| Comando | O que faz |
| --- | --- |
| `prompt wizard` | Faz perguntas guiadas no terminal. Sem `--node-type`, ele pergunta primeiro para qual nó é o prompt. Exige um terminal interativo. |
| `prompt analyze` | Retorna as perguntas guiadas do assistente, para um script. |
| `prompt generate` | Monta o prompt final a partir das suas respostas. Repita `--selection category=value` uma vez por resposta. |
| `prompt enhance` | Reescreve um prompt em uma etapa, sem perguntas. |

- `--reasoning-effort` é `none`, `low`, `medium`, `high`, `xhigh` ou `max`. O suporte depende do modelo; um valor não aceito ou omitido usa o padrão do modelo. `xhigh` e `max` cobram um nível acima, com teto no nível premium.
- `--advanced` funciona só com modelos Gemini. Ele ativa `--temperature`, `--max-tokens` e a faixa completa de raciocínio, e cobra um nível acima, com teto no nível premium.

## Tomadas
Uma tomada (shot) é um estado salvo do construtor: seleções de seletores, prompts, modelos escolhidos e referências a entidades. As tomadas alimentam os links de compartilhamento e o remix com um clique.

```bash
nodaro shots get <id> [--json]
nodaro shots create [--file shot.json] [--visibility private|public] [--json]
nodaro shots update <id> [--file fields.json] [--visibility private|public] [--json]
nodaro shots delete <id>
```

Uma tomada nova é privada, a menos que você defina `--visibility public`. Qualquer pessoa que tenha o id de uma tomada pública pode lê-la.

## Recast
O Recast gera de novo um vídeo analisado com o seu próprio elenco. Você também pode importar um script que escreveu e renderizá-lo como um recast. Os comandos recast só funcionam no Nodaro Cloud.

```bash
nodaro recast skill
nodaro recast validate --file script.json [--json]
nodaro recast import --file script.json --rights-attested [--json]
nodaro recast estimate --analysis-job <id> [--fidelity faithful] [--resolution <r>] [--segment-sec <n>] [--json]
nodaro recast create --workflow <id> --analysis-job <id> [--rights-attested] [--fidelity faithful] [--resolution <r>] [--segment-sec <n>] [--json]
nodaro recast start <recastId> [--segment-sec <n>] [--json]
nodaro recast status <recastId> [--json]
```

| Comando | O que faz | Custo |
| --- | --- | --- |
| `recast skill` | Imprime em Markdown o guia de criação de scripts. | Grátis |
| `recast validate` | Verifica um script. Sai com o código 1 enquanto o script for inválido. | Grátis |
| `recast import` | Importa um script validado como uma análise concluída. `--rights-attested` declara que o script é obra sua. Um recast criado a partir de um script é renderizado em Faithful, exatamente como foi escrito. | Grátis |
| `recast estimate` | Faz a cotação de uma execução em créditos. | Grátis |
| `recast create` | Compra o plano e retorna o id da execução. Execute `estimate` antes. | Créditos |
| `recast start` | Renderiza uma execução planejada. Executar duas vezes não causa problema. | Incluído no plano |
| `recast status` | Mostra o status e qualquer etapa interativa que esteja esperando por você. | Grátis |

**O `--segment-sec` na CLI 1.24.0.** As rotas do Recast recebem o nome de um pacote na configuração de segmentos: `scenes-max` (o menor número de emendas), `scenes` (partes mais curtas) ou `max` (as partes mais longas que o modelo permite). A CLI 1.24.0 envia `--segment-sec` como número, então ela não consegue enviar o nome de um pacote, e um número como `10` é recusado com `400 validation_error`. Deixe a opção de fora, e o servidor usa o padrão dele, `scenes-max`. Para escolher outro pacote, chame a [API do Recast](https://nodaro.ai/docs/developers/api/recast).

Veja [Recast](https://nodaro.ai/docs/mcp/recast) para entender como um recast funciona, e a [API do Recast](https://nodaro.ai/docs/developers/api/recast) para os endpoints por trás destes comandos.

## Frequently asked questions

### Como listo todos os tipos de nó que a CLI do Nodaro pode executar?

Execute nodaro nodes list. Adicione --category ai-image, ou outra categoria, para filtrar a lista, e execute nodaro nodes get generate-image para ver o schema de entrada completo de um tipo de nó.

### Como executo só alguns nós de um workflow pela CLI?

Adicione --node a nodaro workflows run, seguido dos ids dos nós separados por espaços. Só esses nós são executados.

### Como paro um workflow em execução pelo terminal?

Execute nodaro executions cancel com o id da execução. O modo padrão, cancelled, para a execução na hora. Com --mode stopping, o nível atual de nós termina primeiro.

### Quais comandos da CLI do Nodaro precisam do Nodaro Cloud?

Os comandos recast só funcionam no Nodaro Cloud. O controle de execuções do Gerar vídeo Pro (Generate Video Pro) também funciona em uma instalação self-hosted, pela conexão dela com o Nodaro Cloud.

### Como exporto um workflow junto com os personagens dele?

Execute nodaro workflows export com --with-assets e --output bundle.json. O pacote inclui os dados de personagens, objetos e locais que o workflow usa. Importe o pacote com nodaro workflows import bundle.json --project seguido do id de um projeto.