# Referência de argumento

As tabelas abaixo listam cada argumento disponível agrupado por categoria.

Nota informativa

A interface do usuário aplica padrões diferentes para algumas configurações. O assistente é padronizado para o modo de tela fixa, com recarregamento habilitado e binário automático habilitado. A CLI assume por padrão o modo de grade dinâmica, recarregamento desabilitado e auto-binário desabilitado. Ao passar do assistente para a CLI, especifique estas flags explicitamente para corresponder ao comportamento do assistente.

## Entrada e saída

| Argumento | Descrição | Padrão |
| --- | --- | --- |
| `--prjPath PATH` | Caminho para a pasta QV PRJ ou arquivo ZIP. Também aceita arquivos zip PRJ. | — |
| `--qvw PATH` | Caminho para o arquivo QVW ou QVF. Obrigatório no modo de projeto único. | — |
| `--generatePrj` | Gerar automaticamente pastas PRJ a partir de arquivos QVW antes da conversão | Desligado |
| `--outputDir FOLDER` | Diretório raiz de saída. QV2QS cria automaticamente uma subpasta nomeada com base no projeto. Obrigatório. | — |

## Modo em lote

| Argumento | Descrição | Padrão |
| --- | --- | --- |
| `--batchDir FOLDER` | Escanear uma ou mais pastas recursivamente em busca de pares QVW e PRJ. Separe várias pastas com `;`. | — |
| `--batchWorkers N` | Máximo de conversões simultâneas (`0` = automático: núcleos de CPU menos 1) | `0` |
| `--batchFlatOutput` | Escreva toda a saída diretamente sob `--outputDir` em vez de preservar a hierarquia da pasta de origem | Desligado |

## Qlik Cloud

| Argumento | Descrição | Padrão |
| --- | --- | --- |
| `--unbuildOnly` | Modo somente local. Gerar saída de compilação e relatório de conversão em disco sem se conectar ao Qlik Cloud. Destinado a avaliação, revisão e uso offline. A saída local não inclui uploads de mídia, resolução em segundo plano, criação de estado alternativo ou publicação de pasta. Para detalhes, consulte [Como a conversão funciona](https://help.qlik.com/pt-BR/migration/Content/Qv2qsMigration/getting-started/how-conversion-works.htm#local-only-mode). | Desligado |
| `--qsAppName NAME` | Nome para o aplicativo Qlik Sense no Qlik Cloud | Nome do arquivo QVW, nome da pasta PRJ ou nome da pasta de saída |
| `--appId APP_ID` | Atualizar um aplicativo Qlik Cloud existente em vez de criar um novo | — |
| `--appIdFile PATH` | Carregar ID do aplicativo de um arquivo | — |
| `--reuseAppId` | Reutilize o ID do aplicativo de `cloud/cloud_state.json` se o Arquivo existe | Desligado |
| `--preserveTargetAppScript` | Mantenha o script de carregamento existente no aplicativo de destino. O script de carregamento convertido não é aplicado. Requer `--appId` ou `--reuseAppId`. Pode ser combinado com `--reload` para executar o script existente. | Desligado |
| `--preserveTargetAppVariables` | Mantenha as variáveis existentes no aplicativo de destino. As variáveis convertidas não são aplicadas. Requer `--appId` ou `--reuseAppId`. | Desligado |
| `--noBackup` | Ignorar o backup automático de pré-implementação ao reutilizar um aplicativo existente. Por padrão, o QV2QS exporta um QVF sem dados para `cloud/backups/` antes de modificar o aplicativo. | Desligado |
| `--reload` | Recarregue o aplicativo após a construção para executar o script de carregamento | Desligado |
| `--autoBinary` | Carregar QVW/QVF para o Qlik Cloud para carga binária, depois excluir após a recarga. Requer `--reload`. No modo de projeto único, também requer `--qvw`. No modo em lote, os arquivos QVW são descobertos automaticamente. Mutuamente exclusivo com `--binaryAppId`. | Desligado |
| `--binaryAppId APP_ID` | Use um aplicativo existente no Qlik Cloud para a carga binária em vez de fazer upload. Mutuamente exclusivo com `--autoBinary`. | — |
| `--noPublishSheets` | Não publique planilhas depois de construir. Por padrão, QV2QS publica todas as planilhas convertidas como planilhas base para que todo usuário do aplicativo possa vê-las. Use esta flag para manter planilhas como objetos pessoais (não publicados). Ao reutilizar um aplicativo existente (`--reuseAppId` ou `--appId`), as planilhas publicadas anteriormente são restauradas automaticamente; este sinalizador se aplica apenas a novas planilhas adicionadas na conversão atual. | Desligado |
| `--noData` | Construir sem dados | Desligado |
| `--exportQvf` | Exporte o aplicativo como um arquivo QVF e, em seguida, exclua o aplicativo na nuvem | Desligado |
| `--exportQvfNoData` | Exportar o QVF sem dados. Requer `--exportQvf`. | Desligado |
| `--mediaUploadWorkers N` | Threads de upload de mídia paralelos | `2` |
| `--buildConfig PATH` | Manifesto de configuração de construção passado para `qlik app build`. QV2QS gera automaticamente este arquivo durante a conversão. Substitua apenas se estiver fornecendo um manifesto personalizado. | `config.yml` |
| `--spaceId SPACE_ID` | Espaço de destino do Qlik Cloud para criação de aplicativo | Espaço pessoal |

## Autenticação

| Argumento | Descrição | Padrão |
| --- | --- | --- |
| `--qlikContext NAME` | Nome do contexto qlik-cli para autenticação | — |
| `--qlikTenantUrl URL` | URL do Inquilino (`https://<tenant>.<region>.qlikcloud.com`). Quando combinado com `--qlikApiKey`, autentica diretamente sem criar um contexto qlik-cli. | — |
| `--qlikApiKey KEY` | Chave da API para autenticação. Quando combinado com `--qlikTenantUrl`, autentica diretamente sem criar um contexto qlik-cli. A chave não é gravada em disco. | — |
| `--qlikCliPath PATH` | Caminho para o executável qlik-cli | Agrupado |
| `--qlikContextsFile PATH` | Sobrescrever a localização do arquivo de contextos do qlik-cli | — |
| `--qlikNoPrompt` | Falhe imediatamente com código de saída 1 se a autenticação estiver ausente. Sem prompts interativos. Adequado para pipelines de CI/CD. | Desligado |
| `--setupQlikAuth` | Configurar autenticação do Qlik Cloud e sair. Não é necessário quando ambos `--qlikTenantUrl` e `--qlikApiKey` são fornecidos. | — |

## Layout e estilização

Para uma explicação detalhada dos modos de tela fixa e grade dinâmica, consulte [Configurações de layout de conversão](https://help.qlik.com/pt-BR/migration/Content/Qv2qsMigration/conversion-layout-settings/index.htm).

| Argumento | Descrição | Padrão |
| --- | --- | --- |
| `--fixedSheetCanvas` | Habilitar folhas de tela em pixel de tamanho fixo (posicionamento no estilo QlikView) | Desligado |
| `--fixedSheetCanvasScale FACTOR` | Escalar as dimensões da tela por este fator | `1.4` |
| `--fixedSheetCanvasObjectScale FACTOR` | Dimensionar posições e tamanhos de objetos por este fator | `1.4` |
| `--fixedSheetCanvasMinWidthPx PX` | Largura mínima da tela em pixels | `1200` |
| `--fixedSheetCanvasMinHeightPx PX` | Altura mínima do canvas em pixels | `700` |
| `--perSheetCanvasSize` | Usar dimensões da tela por pasta em vez de dimensionamento uniforme | Desligado |
| `--noAutoExtendDynamicSheet` | Desabilitar a autoextensão da altura da pasta no modo dinâmico | Desligado |
| `--layoutShrinkX STEPS` | Diminuir a largura do contêiner de layout em N passos da grade (0–23) | `0` |
| `--layoutShrinkY STEPS` | Reduzir a altura do contêiner de layout em N passos da grade (0–11) | `0` |
| `--cropCanvasWidth PX` | Cortar tela para largura exata em pixels. Apenas modo de tela fixa. Deve ser especificado juntamente com `--cropCanvasHeight`. Mutuamente exclusivo com `--perSheetCanvasSize`. | `0` |
| `--cropCanvasHeight PX` | Recortar tela para altura exata em pixels. Apenas modo de tela fixa. Deve ser especificado juntamente com `--cropCanvasWidth`. Mutuamente exclusivo com `--perSheetCanvasSize`. | `0` |
| `--maxCanvasWidth PX` | Largura máxima da tela em pixels. `0` desativa o limite. Modo de tela fixa apenas. | `0` |
| `--maxCanvasHeight PX` | Altura máxima da tela em pixels. `0` desativa o limite. Modo de tela fixa apenas. | `0` |
| `--appTheme THEME` | Tema do aplicativo Qlik Sense aplicado ao aplicativo convertido. Aceita qualquer identificador de tema integrado (`sense`, `horizon`, `breeze`, `card`) ou um nome de tema personalizado instalado no locatário. Sense Classic (`sense`) é o tema menos intrusivo e produz a maior fidelidade 1:1 com o QlikView. Temas não clássicos podem alterar bordas de objetos, cores de fundo, fontes e preenchimento. O tema define o padrão apenas; os usuários podem trocar de temas a qualquer momento no cliente Qlik Sense. | `sense` |
| `--disableSheetBackgrounds` | Ignorar extração de imagem de fundo da pasta | Desligado |
| `--noDocBgFallback` | Não aplicar o plano de fundo do documento a folhas que não o tenham | Desligado |
| `--sheetBackgroundColor COLOR` | Preenchimento de cor sólida para todas as folhas (`#RRGGBB`, `#RRGGBB@0.5`, ou `transparent`) | — |
| `--showSheetHeader` | Mostrar a região do cabeçalho da pasta | Desligado |
| `--skipHiddenSheets` | Omitir planilhas com condições de exibição sempre falsas | Desligado |

## Relatório de conversão

O relatório do console e o relatório do Excel são ambos habilitados por padrão no modo CLI e na interface do usuário.

| Argumento | Descrição | Padrão |
| --- | --- | --- |
| `--report` | Ativar o relatório de conversão do console | Ativado |
| `--noReport` | Desativar o relatório de conversão do console | — |
| `--reportXlsx [PATH]` | Exporte o relatório como um arquivo Excel. Aceita um nome de arquivo (ex. `MyReport`) ou um caminho completo; `.xlsx` é adicionado automaticamente. Nomes relativos são colocados em `outputDir/reports/`. Omitir o caminho para auto-nomear. | Automático |
| `--noReportXlsx` | Desativar exportação do Excel | — |
| `--reportIncludeBuiltIns` | Incluir Seleções Atuais e objetos de Pesquisa no relatório | Desligado |

## Console e registro

| Argumento | Descrição | Padrão |
| --- | --- | --- |
| `--console {pretty,plain,silent,ui}` | Modo de saída do console | `pretty` |
| `--dark` | Tema escuro do console | Ativado |
| `--light` | Tema claro do console | Desligado |
| `--surface` | Habilitar preenchimento de fundo para o console | Ativado (no modo bonito) |
| `--noSurface` | Desativar preenchimento de fundo | — |
| `--plain` | Atalho para `--console plain` | — |
| `--silent` | Atalho para `--console silent` | — |
| `--logLevel LEVEL` | Verbosidade do log: `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL` | `INFO` |
| `--logDir FOLDER` | Sobrescrever a pasta de saída de log | `%LOCALAPPDATA%\QV2QS\logs\` (projeto único) ou `<outputDir>/logs/` (em lote) |
| `--cleanLogs` | Excluir arquivos de log com mais de 30 dias antes da execução | Desligado |

O QV2QS suporta quatro modos de saída de console.

* Bonito — Saída ricamente formatada com cores, spinners animados, barras de progresso e painéis temáticos. Modo formatado é o padrão para uso interativo do terminal. Requer um terminal com capacidade de cores (Windows 10+, PowerShell 5+, ou shells tipo Unix).
* Simples — Saída de texto com carimbo de data/hora, sem códigos de escape ANSI. Cada linha é prefixada com um carimbo de tempo decorrido e uma tag de fase no formato `[MM:SS] [phase] message`. Cabeçalhos e tabelas usam caracteres ASCII. Adequado para pipelines de CI/CD, arquivos de log e terminais que não suportam formatação ANSI.
* Silencioso — Suprime toda a saída padrão. Apenas erros são exibidos. Adequado para processamento em lote automatizado e fluxos de trabalho com script onde nenhuma saída de console é necessária.
* UI — Saída orientada a linha, sem carimbos de data/hora ou códigos ANSI. A interface do usuário define este modo automaticamente ao iniciar um subprocesso de conversão. O formato é otimizado para o visualizador de log incorporado. Executar `--console ui` de um terminal produz uma saída legível, mas sem formatação; use `--plain` ou `--console pretty` em vez disso para uso direto no terminal.

As `--dark` e `--light` bandeiras selecionam um tema de cor. O tema escuro (padrão) usa uma paleta azul-marinho profunda inspirada no Qlik. O tema claro usa uma paleta cinza claro. A flag `--surface` permite um preenchimento de fundo sutil atrás de cada linha de saída. O preenchimento de superfície é ativado por padrão no modo bonito. Use `--noSurface` para desativar o preenchimento de fundo.

No modo de projeto único, os arquivos de log são gravados em `%LOCALAPPDATA%\QV2QS\logs\` por padrão. No modo em lote, os arquivos de log são gravados na subpasta `logs/` no diretório de saída. Substituir a localização com `--logDir`. Defina `--logLevel DEBUG` para capturar a saída de diagnóstico detalhada para solucionar problemas de conversão. Use `--cleanLogs` para excluir arquivos de log mais antigos que 30 dias antes de cada execução. Para uma descrição completa dos locais, rotação e formato dos arquivos de log, consulte [Registro e diagnóstico](https://help.qlik.com/pt-BR/migration/Content/Qv2qsMigration/command-line-interface/logging-and-diagnostics.htm).

## Carregar script

| Argumento | Descrição | Padrão |
| --- | --- | --- |
| `--scriptReplacements PATH` | Arquivo JSON com regras de substituição de script. Quando fornecidas, apenas as regras no arquivo são executadas. Padrões internos não são carregados automaticamente. Veja o formato abaixo. | — |
| `--noScriptReplacements` | Desabilitar todas as substituições de script. Nenhuma regra é executada, independentemente de um arquivo ser fornecido. | Desligado |

Por padrão, o QV2QS aplica oito regras internas que normalizam caminhos de barra invertida do Windows para barras normais para compatibilidade com o Qlik Cloud. A tabela a seguir lista cada regra integrada.

| ID | Descrição | Destinos: |
| --- | --- | --- |
| 1 | Normalizar barras invertidas em `lib://` caminhos | `lib://DataFiles\subfolder\file.qvd` |
| 2 | Normalizar barras invertidas em `STORE...INTO` caminhos | `STORE table INTO 'C:\data\file.qvd'` |
| 3 | Normalizar barras invertidas em `FROM` caminhos (entre aspas) | `FROM 'C:\data\file.qvd'` |
| 4 | Normalizar barras invertidas em `LET` caminhos de instrução | `LET vPath = 'C:\data\files';` |
| 5 | Normalizar barras invertidas em `SET` caminhos de instrução | `SET vPath = 'C:\data\files';` |
| 6 | Normalizar barras invertidas em `BINARY` caminhos de instrução | `BINARY 'C:\apps\source.qvw'` |
| 7 | Normalizar barras invertidas em `FROM` caminhos (sem aspas) | `FROM C:\data\file.qvd` |
| 8 | Normalizar barras invertidas em `$(Variable=path)` expansão | `$(Must_Includes=C:\lib\file.qvs)` |

Cada regra usa um processo de correspondência em duas etapas. O `pattern` campo é uma regex que seleciona uma região do script de carregamento. O campo `search` é então aplicado apenas dentro de cada região correspondente. Essa abordagem evita substituições não intencionais fora do contexto visado.

O `--scriptReplacements` argumento aceita um arquivo JSON que se torna a única fonte de verdade para todas as regras de substituição. Quando um arquivo é fornecido, os padrões internos não são carregados automaticamente. Para incluir regras internas juntamente com regras personalizadas, exportar o conjunto completo de regras do assistente e edite o arquivo exportado. As regras são executadas em `execution_order` ordem.

Três comportamentos de CLI estão disponíveis:

* Nenhuma flag — as oito regras incorporadas são executadas.
* `--scriptReplacements <file>` — apenas as regras no arquivo são executadas. Padrões incorporados não são carregados automaticamente.
* `--noScriptReplacements` — nenhuma regra é executada.

Nota de dica

Para criar um arquivo de regras personalizado, abra o assistente, clique em Exportar na seção de substituições do Script, e use o JSON exportado como ponto de partida. O arquivo exportado contém todas as oito regras internas no formato correto. Adicione, remova ou modifique as regras conforme necessário, em seguida, passe o arquivo com `--scriptReplacements`.

O arquivo `--scriptReplacements` é um array JSON de objetos de regra:

```
[
  {
    "description": "Replace server path with lib connection",
    "pattern": "FROM\\s+'[^']*'",
    "search": "\\\\\\\\server\\\\share\\\\",
    "replace": "lib://DataFiles/",
    "is_regex": true,
    "case_sensitive": false,
    "enabled": true,
    "execution_order": 1
  }
]
```

Cada regra tem os seguintes campos:

| Campo | Descrição | Obrigatório |
| --- | --- | --- |
| `description` | Rótulo legível para a regra | Sim |
| `pattern` | Regex que seleciona regiões do script para examinar | Sim |
| `search` | Texto ou regex a ser encontrado dentro de cada região correspondente | Sim |
| `replace` | Texto de substituição | Não (padrão: string vazia, que exclui o texto correspondente) |
| `is_regex` | Se `search` é uma regex (`true`) ou uma string literal (`false`) | Não (padrão: `true`) |
| `case_sensitive` | Se a correspondência diferencia maiúsculas de minúsculas | Não (padrão: `false`) |
| `enabled` | Se a regra está ativa | Não (padrão: `true`) |
| `id` | Identificador numérico para rastreamento da interface do usuário | Não |
| `execution_order` | Valor numérico que controla a ordem de execução. Valores menores são executados primeiro. | Não (padrão: `0`) |

Nota informativa

O arquivo também aceita nomes de campo em camelCase (`isRegex`, `caseSensitive`, `executionOrder`) para compatibilidade com arquivos exportados do assistente.

## Outros

| Argumento | Descrição | Padrão |
| --- | --- | --- |
| `--listboxBackgroundExpr EXPR` | Cor de fundo da caixa de listagem. `dynamic` preserva as cores do QV. Também aceita `#RRGGBB`, `#AARRGGBB`, `rgb(r,g,b)`, ou `argb(a,r,g,b)`. | `dynamic` |
| `--disableDateStateStickySort` | Desativar a proteção de ordenação do campo de data. Consulte abaixo. | Desligado |
| `--fixSingleQuotedSearch` / `--noFixSingleQuotedSearch` | Converter curingas e comparações entre aspas simples para aspas duplas na análise de conjunto. Consulte abaixo. | Ativado |
| `--fixUnquotedSetValues` / `--noFixUnquotedSetValues` | Experimental. Envolva valores de string simples sem aspas entre aspas simples na análise de conjunto. Consulte abaixo. | Desligado |
| `--ui` | Iniciar a interface do usuário em vez de executar uma conversão | Desligado |
| `--port PORT` | Porta da interface do usuário | Automático |
| `--noBrowser` | Não abrir o navegador automaticamente ao iniciar a interface do usuário | Desligado |
| `--version` | Mostrar versão e sair | — |
| `--accept-eula` | Aceitar o Contrato de Licença de Usuário Final sem um prompt interativo. Destinado a pipelines de CI/CD e fluxos de trabalho automatizados. | Desligado |

### Guarda de ordenação de campo de data

Por padrão, o Qlik Sense classifica os valores selecionados para o topo de uma caixa de listagem. Para campos semelhantes a datas, como Trimestre, Mês ou Ano, essa reordenação quebra a sequência cronológica esperada. QV2QS aplica uma heurística para detectar nomes de campos semelhantes a datas e suprimir a ordenação baseada em estado nesses campos, mantendo os valores em sua ordem natural independentemente do estado de seleção.

A heurística tokeniza cada nome de campo dividindo-o em caracteres não alfanuméricos e limites camelCase (por exemplo, `OrderDate` torna-se `order` e `date`). Todos os tokens estão em minúsculas. Um campo corresponde se qualquer token for igual a um dos seguintes: `date`, `dates`, `month`, `months`, `year`, `years`, `quarter`, `quarters`, `qtr`, `qtrs`, `week`, `weeks`, `day`, `days`, `fiscal`, `fy`, `period`, `calendar`. Um campo também corresponde se qualquer token terminar com `date`, `month`, ou `year` (por exemplo, `OrderDate`, `FiscalMonth`). Os tokens `update`, `candidate`, e `validate` são excluídos para evitar falsos positivos. A correspondência não diferencia maiúsculas de minúsculas e usa apenas tokens em inglês. Nomes de campos não-ingleses (por exemplo, `Monat` ou `Fecha`) não são detectados.

Campos que correspondem à heurística têm a ordenação baseada em estado removida e a ordenação automática desativada.

Use `--disableDateStateStickySort` para desativar esta heurística. Quando desativado, todos os campos de caixa de listagem usam o comportamento de classificação padrão do Qlik Sense, incluindo a reordenação baseada no estado.

### Correções de aspas na análise de conjunto

QlikView e Qlik Sense interpretam diferentemente o uso de aspas em modificadores de análise de conjunto. QV2QS aplica duas correções independentes durante a conversão. A correção de pesquisa entre aspas simples está ativada por padrão. A correção de valores de conjunto sem aspas é experimental e desabilitada por padrão.

Corrigir valores de pesquisa entre aspas simples (`--fixSingleQuotedSearch`)

Valores entre aspas simples contendo sintaxe de pesquisa são convertidos para aspas duplas. Padrões de pesquisa detectados incluem curingas (`*`, `?`, `^`), operadores de comparação (`>`, `>=`, `<`, `<=`), pesquisa avançada (`~`), pesquisa de expressão (`=`), modificadores de pesquisa (`+`, `-`), e pesquisa composta (`(…|…)`, `(…&…)`):

* `{<Year={'2*'}>}` torna-se `{<Year={"2*"}>}`
* `{<Amount={'>100'}>}` torna-se `{<Amount={">100"}>}`
* `{<Customer={'~company'}>}` torna-se `{<Customer={"~company"}>}`

Literais de texto simples entre aspas simples (por exemplo, `'USA'`) e valores entre aspas simples em campos numéricos não são afetados. Use `--noFixSingleQuotedSearch` para desativar esta correção.

Corrigir valores de conjunto não entre aspas (`--fixUnquotedSetValues`) — *experimental*

Valores de string simples sem aspas são envolvidos por aspas simples:

* `{<Country={USA}>}` torna-se `{<Country={'USA'}>}`

Valores numéricos (`2024`), variáveis com cifrão (`$(vYear)`), e strings entre aspas duplas são deixadas inalteradas. Essa correção está desabilitada por padrão. Passe `--fixUnquotedSetValues` para ativá-lo. Use `--noFixUnquotedSetValues` para desativá-lo explicitamente.

Ambas as correções se aplicam apenas a expressões de dimensão e de medida. Descobertas de funções não suportadas não são modificadas. Quando uma correção é desativada, os padrões sinalizados permanecem para revisão manual na planilha Expression\_Findings.

## Saiba mais

* [Fluxos de trabalho comuns](https://help.qlik.com/pt-BR/migration/Content/Qv2qsMigration/command-line-interface/common-workflows.htm)
* [Registro de logs e diagnósticos](https://help.qlik.com/pt-BR/migration/Content/Qv2qsMigration/command-line-interface/logging-and-diagnostics.htm)
* [Modos de layout](https://help.qlik.com/pt-BR/migration/Content/Qv2qsMigration/conversion-layout-settings/index.htm)